Thay thế mẫu chuỗi python
Python là ngôn ngữ động chính được sử dụng tại Google. This style guide is a list of dos and don’ts for Python programs Show
To help you format code correctly, we’ve created a settings file for Vim. For Emacs, the default settings should be fine Many teams use the yapf auto-formatter to avoid arguing over formatting 2 Python Language Rules2. 1 LintRun 14 over your code using this pylintrc2. 1. 1 Definition 14 is a tool for finding bugs and style problems in Python source code. It finds problems that are typically caught by a compiler for less dynamic languages like C and C++. Because of the dynamic nature of Python, some warnings may be incorrect; however, spurious warnings should be fairly infrequent2. 1. 2 ProsCatches easy-to-miss errors like typos, using-vars-before-assignment, etc 2. 1. 3 Cons 14 isn’t perfect. To take advantage of it, sometimes we’ll need to write around it, suppress its warnings or fix it2. 1. 4 DecisionMake sure you run 14 on your codeSuppress warnings if they are inappropriate so that other issues are not hidden. To suppress warnings, you can set a line-level comment
14 warnings are each identified by symbolic name ( 19) Google-specific warnings start with 20If the reason for the suppression is not clear from the symbolic name, add an explanation Suppressing in this way has the advantage that we can easily search for suppressions and revisit them You can get a list of 14 warnings by doingTo get more information on a particular message, use Prefer 22 to the deprecated older form 23Unused argument warnings can be suppressed by deleting the variables at the beginning of the function. Always include a comment explaining why you are deleting it. “Unused. ” is sufficient. Ví dụ
Other common forms of suppressing this warning include using ‘ 24’ as the identifier for the unused argument or prefixing the argument name with ‘ 25’, or assigning them to ‘ 24’. These forms are allowed but no longer encouraged. These break callers that pass arguments by name and do not enforce that the arguments are actually unused2. 2 ImportsUse 27 statements for packages and modules only, not for individual classes or functions2. 2. 1 DefinitionCơ chế tái sử dụng để chia sẻ mã từ mô-đun này sang mô-đun khác 2. 2. 2 Ưu điểmQuy ước quản lý không gian tên rất đơn giản. Nguồn của mỗi mã định danh được chỉ định một cách nhất quán; 2. 2. 3 nhược điểmTên mô-đun vẫn có thể xung đột. Một số tên mô-đun dài bất tiện 2. 2. 4 Quyết định
For example the module 43 may be imported as follows 2Không sử dụng tên họ hàng trong nhập khẩu. Even if the module is in the same package, use the full package name. This helps prevent unintentionally importing a package twice 2. 2. 4. 1 ExemptionsMiễn trừ từ quy tắc này
2. 3 góiNhập từng mô-đun bằng vị trí tên đường dẫn đầy đủ của mô-đun 2. 3. 1 Ưu điểmTránh xung đột về tên mô-đun hoặc nhập sai do đường dẫn tìm kiếm mô-đun không như tác giả mong đợi. Làm cho nó dễ dàng hơn để tìm các mô-đun 2. 3. 2 nhược điểmLàm cho việc triển khai mã trở nên khó khăn hơn vì bạn phải sao chép hệ thống phân cấp gói. Không thực sự là một vấn đề với các cơ chế triển khai hiện đại 2. 3. 3 Quyết địnhTất cả mã mới phải nhập từng mô-đun theo tên gói đầy đủ của nó Nhập khẩu phải như sau 3 4(giả sử tệp này tồn tại trong 44 nơi mà 45 cũng tồn tại) 7Thư mục chứa tệp nhị phân chính không nên được coi là trong 46 mặc dù điều đó xảy ra trong một số môi trường. Trong trường hợp này, mã phải giả định rằng 47 đề cập đến bên thứ ba hoặc gói cấp cao nhất có tên là 48, không phải là một 45 cục bộ2. 4 ngoại lệNgoại lệ được cho phép nhưng phải được sử dụng cẩn thận 2. 4. 1 Định nghĩaNgoại lệ là phương tiện thoát ra khỏi luồng điều khiển thông thường để xử lý lỗi hoặc các điều kiện ngoại lệ khác 2. 4. 2 Ưu điểmLuồng điều khiển của mã hoạt động bình thường không bị lộn xộn bởi mã xử lý lỗi. Nó cũng cho phép luồng điều khiển bỏ qua nhiều khung khi một điều kiện nhất định xảy ra, e. g. , quay lại từ N hàm lồng nhau trong một bước thay vì phải tìm mã lỗi thông qua 2. 4. 3 nhược điểmCó thể khiến luồng điều khiển bị nhầm lẫn. Dễ bỏ sót các trường hợp lỗi khi gọi thư viện 2. 4. 4 Quyết địnhNgoại lệ phải tuân theo các điều kiện nhất định
2. 5 biến toàn cầuTránh các biến toàn cầu 2. 5. 1 Định nghĩaCác biến được khai báo ở cấp độ mô-đun hoặc dưới dạng thuộc tính lớp 2. 5. 2 Ưu điểmThỉnh thoảng hữu ích 2. 5. 3 nhược điểmCó khả năng thay đổi hành vi của mô-đun trong quá trình nhập, vì việc gán cho các biến toàn cục được thực hiện khi mô-đun được nhập lần đầu 2. 5. 4 Quyết địnhTránh các biến toàn cầu Nếu cần, các biến toàn cục phải được khai báo ở cấp độ mô-đun và được đặt bên trong mô-đun bằng cách thêm một 24 vào tên. Quyền truy cập bên ngoài vào các biến toàn cục phải được thực hiện thông qua các hàm cấp mô-đun công khai. Xem cách đặt tên bên dướiMặc dù các hằng số cấp mô-đun là các biến kỹ thuật, nhưng chúng được cho phép và khuyến khích. Ví dụ. 67. Các hằng số phải được đặt tên bằng cách sử dụng tất cả các chữ hoa có dấu gạch dưới. Xem cách đặt tên bên dưới2. 6 Các lớp và hàm lồng nhau/cục bộ/bên trongCác hàm hoặc lớp cục bộ lồng nhau vẫn ổn khi được sử dụng để đóng trên một biến cục bộ. Các lớp bên trong vẫn ổn 2. 6. 1 Định nghĩaMột lớp có thể được định nghĩa bên trong một phương thức, hàm hoặc lớp. Một hàm có thể được định nghĩa bên trong một phương thức hoặc hàm. Các hàm lồng nhau có quyền truy cập chỉ đọc vào các biến được xác định trong phạm vi kèm theo 2. 6. 2 Ưu điểmAllows definition of utility classes and functions that are only used inside of a very limited scope. Rất ADT-y. Thường được sử dụng để thực hiện trang trí 2. 6. 3 nhược điểmCác hàm và lớp lồng nhau không thể được kiểm tra trực tiếp. Việc lồng nhau có thể làm cho chức năng bên ngoài dài hơn và khó đọc hơn 2. 6. 4 Quyết địnhHọ ổn với một số lưu ý. Tránh các hàm hoặc lớp lồng nhau trừ khi đóng trên một giá trị cục bộ khác với 68 hoặc 69. Không lồng chức năng chỉ để ẩn nó khỏi người dùng mô-đun. Thay vào đó, hãy đặt tiền tố tên của nó bằng _ ở cấp độ mô-đun để nó vẫn có thể được truy cập bằng các thử nghiệm2. 7 cách hiểu và biểu thức trình tạoĐược rồi để sử dụng cho các trường hợp đơn giản 2. 7. 1 Định nghĩaKhả năng hiểu List, Dict và Set cũng như các biểu thức trình tạo cung cấp một cách ngắn gọn và hiệu quả để tạo các loại vùng chứa và trình vòng lặp mà không cần sử dụng các vòng lặp truyền thống, 70, 71 hoặc 722. 7. 2 Ưu điểmViệc hiểu đơn giản có thể rõ ràng và đơn giản hơn các kỹ thuật tạo chính tả, danh sách hoặc tập hợp khác. Biểu thức trình tạo có thể rất hiệu quả, vì chúng tránh hoàn toàn việc tạo danh sách 2. 7. 3 nhược điểmCó thể khó đọc các biểu thức trình tạo hoặc hiểu phức tạp 2. 7. 4 Quyết địnhĐược rồi để sử dụng cho các trường hợp đơn giản. Mỗi phần phải vừa trên một dòng. biểu thức ánh xạ, mệnh đề 73, biểu thức bộ lọc. Nhiều mệnh đề 73 hoặc biểu thức bộ lọc không được phép. Thay vào đó, hãy sử dụng các vòng lặp khi mọi thứ trở nên phức tạp hơn 9 02. 8 Iterator và Operator mặc địnhSử dụng các trình lặp và toán tử mặc định cho các loại hỗ trợ chúng, như danh sách, từ điển và tệp 2. 8. 1 Định nghĩaCác loại vùng chứa, như từ điển và danh sách, xác định các trình vòng lặp mặc định và toán tử kiểm tra tư cách thành viên (“in” và “not in”) 2. 8. 2 Ưu điểmCác trình vòng lặp và toán tử mặc định rất đơn giản và hiệu quả. Chúng thể hiện thao tác trực tiếp mà không cần gọi thêm phương thức. Một hàm sử dụng các toán tử mặc định là chung chung. Nó có thể được sử dụng với bất kỳ loại nào hỗ trợ hoạt động 2. 8. 3 nhược điểmBạn không thể biết loại đối tượng bằng cách đọc tên phương thức (trừ khi biến có chú thích loại). Đây cũng là một lợi thế 2. 8. 4 Quyết địnhSử dụng các trình lặp và toán tử mặc định cho các loại hỗ trợ chúng, như danh sách, từ điển và tệp. Các loại tích hợp cũng xác định các phương thức lặp. Ưu tiên các phương thức này hơn các phương thức trả về danh sách, ngoại trừ việc bạn không nên thay đổi vùng chứa trong khi lặp lại nó 0 12. 9 máy phát điệnSử dụng máy phát điện khi cần thiết 2. 9. 1 Định nghĩaHàm tạo trả về một trình vòng lặp mang lại một giá trị mỗi khi nó thực thi câu lệnh năng suất. Sau khi nó mang lại một giá trị, trạng thái thời gian chạy của hàm tạo bị tạm dừng cho đến khi cần giá trị tiếp theo 2. 9. 2 Ưu điểmMã đơn giản hơn, vì trạng thái của các biến cục bộ và luồng điều khiển được giữ nguyên cho mỗi cuộc gọi. Trình tạo sử dụng ít bộ nhớ hơn so với hàm tạo toàn bộ danh sách giá trị cùng một lúc 2. 9. 3 nhược điểmCác biến cục bộ trong trình tạo sẽ không được thu gom rác cho đến khi trình tạo bị tiêu thụ đến mức cạn kiệt hoặc chính nó đã được thu gom rác 2. 9. 4 Quyết địnhKhỏe. Sử dụng “Năng suất. ” thay vì “Trả về. ” trong chuỗi tài liệu cho các hàm tạo Nếu trình tạo quản lý một tài nguyên đắt tiền, hãy đảm bảo buộc dọn sạch A good way to do the clean up is by wrapping the generator with a context manager PEP-0533 2. 10 Hàm LambdaĐược rồi cho một lớp lót. Thích các biểu thức trình tạo hơn 70 hoặc 71 với một 722. 10. 1 Định nghĩaLambdas định nghĩa các hàm ẩn danh trong một biểu thức, trái ngược với một câu lệnh 2. 10. 2 Ưu điểmTiện lợi 2. 10. 3 nhược điểmKhó đọc và gỡ lỗi hơn các chức năng cục bộ. Việc thiếu tên có nghĩa là dấu vết ngăn xếp khó hiểu hơn. Tính biểu cảm bị hạn chế vì chức năng chỉ có thể chứa một biểu thức 2. 10. 4 Quyết địnhĐược rồi để sử dụng chúng cho một lớp lót. Nếu mã bên trong hàm lambda dài hơn 60-80 ký tự, thì có lẽ tốt hơn nên xác định nó là một hàm lồng nhau thông thường Đối với các hoạt động phổ biến như phép nhân, hãy sử dụng các hàm từ mô-đun 78 thay vì các hàm lambda. Ví dụ: thích 79 hơn 802. 11 Biểu thức điều kiệnĐược rồi cho các trường hợp đơn giản 2. 11. 1 Định nghĩaBiểu thức điều kiện (đôi khi được gọi là “toán tử bậc ba”) là cơ chế cung cấp cú pháp ngắn hơn cho câu lệnh if. Ví dụ. 812. 11. 2 Ưu điểmNgắn gọn và thuận tiện hơn câu lệnh if 2. 11. 3 nhược điểmCó thể khó đọc hơn câu lệnh if. Điều kiện có thể khó xác định nếu biểu thức dài 2. 11. 4 Quyết địnhĐược rồi để sử dụng cho các trường hợp đơn giản. Mỗi phần phải vừa trên một dòng. biểu thức đúng, biểu thức if, biểu thức khác. Sử dụng câu lệnh if hoàn chỉnh khi mọi thứ trở nên phức tạp hơn 2 32. 12 giá trị đối số mặc địnhĐược rồi trong hầu hết các trường hợp 2. 12. 1 Định nghĩaBạn có thể chỉ định giá trị cho các biến ở cuối danh sách tham số của hàm, chẳng hạn như. g. , 82. Nếu 83 được gọi chỉ với một đối số, thì 84 được đặt thành 0. Nếu nó được gọi với hai đối số, thì 84 có giá trị của đối số thứ hai2. 12. 2 Ưu điểmThường thì bạn có một hàm sử dụng nhiều giá trị mặc định, nhưng trong một số trường hợp hiếm hoi, bạn muốn ghi đè lên các giá trị mặc định. Các giá trị đối số mặc định cung cấp một cách dễ dàng để thực hiện việc này mà không cần phải xác định nhiều hàm cho các trường hợp ngoại lệ hiếm gặp. Vì Python không hỗ trợ các phương thức/hàm quá tải, nên các đối số mặc định là một cách dễ dàng để “làm giả” hành vi quá tải 2. 12. 3 nhược điểmCác đối số mặc định được đánh giá một lần tại thời điểm tải mô-đun. Điều này có thể gây ra sự cố nếu đối số là đối tượng có thể thay đổi, chẳng hạn như danh sách hoặc từ điển. If the function modifies the object (e. g. , bằng cách thêm một mục vào danh sách), giá trị mặc định được sửa đổi 2. 12. 4 Quyết địnhĐược rồi để sử dụng với cảnh báo sau Không sử dụng các đối tượng có thể thay đổi làm giá trị mặc định trong định nghĩa hàm hoặc phương thức 4 52. 13 thuộc tínhCác thuộc tính có thể được sử dụng để kiểm soát việc nhận hoặc thiết lập các thuộc tính yêu cầu tính toán hoặc logic thông thường. Việc triển khai thuộc tính phải phù hợp với kỳ vọng chung của quyền truy cập thuộc tính thông thường. rằng chúng rẻ, đơn giản và không gây ngạc nhiên 2. 13. 1 Định nghĩaMột cách để gói các cuộc gọi phương thức để nhận và đặt thuộc tính làm quyền truy cập thuộc tính tiêu chuẩn 2. 13. 2 Ưu điểm
2. 13. 3 nhược điểm
2. 13. 4 Quyết địnhCác thuộc tính được cho phép, nhưng, giống như quá tải toán tử, chỉ nên được sử dụng khi cần thiết và phù hợp với mong đợi của truy cập thuộc tính điển hình; Ví dụ: không được phép sử dụng một thuộc tính để lấy và đặt một thuộc tính nội bộ. không có tính toán xảy ra, vì vậy thuộc tính là không cần thiết (thay vào đó hãy đặt thuộc tính công khai). Trong khi đó, việc sử dụng một thuộc tính để kiểm soát quyền truy cập thuộc tính hoặc để tính toán một giá trị có nguồn gốc tầm thường được cho phép. logic rất đơn giản và không có gì đáng ngạc nhiên Các thuộc tính nên được tạo bằng trình trang trí 86. Thực hiện thủ công một bộ mô tả thuộc tính được coi là một tính năng quyền lựcKế thừa với các thuộc tính có thể không rõ ràng. Không sử dụng các thuộc tính để thực hiện tính toán mà một lớp con có thể muốn ghi đè và mở rộng 2. 14 Đánh giá Đúng/SaiSử dụng sai "ngầm" nếu có thể 2. 14. 1 Định nghĩaPython đánh giá các giá trị nhất định là 87 khi ở trong ngữ cảnh boolean. Một "quy tắc ngón tay cái" nhanh là tất cả các giá trị "trống rỗng" đều được coi là sai, vì vậy tất cả các giá trị 88 đều được đánh giá là sai trong ngữ cảnh boolean2. 14. 2 Ưu điểmCác điều kiện sử dụng booleans Python dễ đọc hơn và ít bị lỗi hơn. Trong hầu hết các trường hợp, chúng cũng nhanh hơn 2. 14. 3 nhược điểmCó thể trông lạ đối với các nhà phát triển C/C++ 2. 14. 4 Quyết địnhSử dụng sai “ngầm” nếu có thể, e. g. , 89 thay vì 90. Có một vài cảnh báo mà bạn nên ghi nhớ mặc dù
2. 16 Phạm vi từ vựngĐược rồi để sử dụng 2. 16. 1 Định nghĩaMột hàm Python lồng nhau có thể tham chiếu đến các biến được xác định trong các hàm kèm theo, nhưng không thể gán cho chúng. Các liên kết biến được giải quyết bằng cách sử dụng phạm vi từ vựng, nghĩa là dựa trên văn bản chương trình tĩnh. Bất kỳ sự gán nào cho một tên trong một khối sẽ khiến Python coi tất cả các tham chiếu đến tên đó là một biến cục bộ, ngay cả khi việc sử dụng có trước sự gán. Nếu một khai báo toàn cầu xảy ra, tên được coi là một biến toàn cầu Một ví dụ về việc sử dụng tính năng này là 82. 16. 2 Ưu điểmThường dẫn đến mã rõ ràng hơn, thanh lịch hơn. Đặc biệt an ủi các lập trình viên Lisp và Scheme (và Haskell, ML và…) có kinh nghiệm 2. 16. 3 nhược điểmCó thể dẫn đến các lỗi khó hiểu. Chẳng hạn như ví dụ này dựa trên PEP-0227 9Vì vậy, 212 sẽ in 213, không phải 2142. 16. 4 Quyết địnhĐược rồi để sử dụng 2. 17 Trình trang trí chức năng và phương thứcSử dụng decorators một cách thận trọng khi có một lợi thế rõ ràng. Tránh 215 và hạn chế sử dụng 2162. 17. 1 Định nghĩaTrình trang trí cho Hàm và Phương thức (a. k. một “ký hiệu 217”). Một trình trang trí phổ biến là 86, được sử dụng để chuyển đổi các phương thức thông thường thành các thuộc tính được tính toán động. Tuy nhiên, cú pháp của trình trang trí cũng cho phép các trình trang trí do người dùng định nghĩa. Cụ thể, đối với một số chức năng 219, điều này 20tương đương với 212. 17. 2 Ưu điểmChỉ định một cách trang nhã một số chuyển đổi trên một phương thức; 2. 17. 3 nhược điểmTrình trang trí có thể thực hiện các thao tác tùy ý trên đối số của hàm hoặc trả về giá trị, dẫn đến hành vi ngầm đáng ngạc nhiên. Ngoài ra, các trình trang trí thực thi tại thời điểm xác định đối tượng. Đối với các đối tượng cấp mô-đun (lớp, chức năng mô-đun,…) điều này xảy ra tại thời điểm nhập. Lỗi trong mã trang trí hầu như không thể phục hồi từ 2. 17. 4 Quyết địnhSử dụng decorators một cách thận trọng khi có một lợi thế rõ ràng. Người trang trí phải tuân theo các nguyên tắc nhập và đặt tên giống như các chức năng. Decorator pydoc should clearly state that the function is a decorator. Viết bài kiểm tra đơn vị cho người trang trí Tránh các phụ thuộc bên ngoài trong chính trình trang trí (e. g. không dựa vào tệp, ổ cắm, kết nối cơ sở dữ liệu, v.v. ), vì chúng có thể không khả dụng khi trình trang trí chạy (tại thời điểm nhập, có thể từ 220 hoặc các công cụ khác). Một trình trang trí được gọi với các tham số hợp lệ phải (càng nhiều càng tốt) được đảm bảo thành công trong mọi trường hợpTrình trang trí là trường hợp đặc biệt của “mã cấp cao nhất” - xem phần chính để thảo luận thêm Không bao giờ sử dụng 215 trừ khi bị buộc phải tích hợp với API được xác định trong thư viện hiện có. Thay vào đó hãy viết một hàm cấp mô-đunChỉ sử dụng 216 khi viết hàm tạo có tên hoặc quy trình dành riêng cho lớp để sửa đổi trạng thái chung cần thiết, chẳng hạn như bộ đệm trên toàn quy trình2. 18 luồngKhông dựa vào tính nguyên tử của các loại tích hợp Mặc dù các kiểu dữ liệu tích hợp sẵn của Python, chẳng hạn như từ điển, dường như có các hoạt động nguyên tử, nhưng có một số trường hợp chúng không phải là nguyên tử (e. g. nếu 223 hoặc 224 được triển khai dưới dạng phương thức Python) và không nên dựa vào tính nguyên tử của chúng. Bạn cũng không nên dựa vào phép gán biến nguyên tử (vì điều này lại phụ thuộc vào từ điển)Sử dụng kiểu dữ liệu 225 của mô-đun Hàng đợi làm cách ưu tiên để giao tiếp dữ liệu giữa các luồng. Nếu không, hãy sử dụng mô-đun luồng và các nguyên hàm khóa của nó. Ưu tiên các biến điều kiện và 226 thay vì sử dụng các khóa cấp thấp hơn2. 19 Tính năng nguồnTránh các tính năng này 2. 19. 1 Định nghĩaPython là một ngôn ngữ cực kỳ linh hoạt và cung cấp cho bạn nhiều tính năng ưa thích như siêu dữ liệu tùy chỉnh, quyền truy cập vào mã byte, biên dịch nhanh, kế thừa động, sửa chữa đối tượng, hack nhập, phản chiếu (e. g. một số cách sử dụng của 227), sửa đổi nội bộ hệ thống, phương pháp 228 thực hiện dọn dẹp tùy chỉnh, v.v.2. 19. 2 Ưu điểmĐây là những tính năng ngôn ngữ mạnh mẽ. Họ có thể làm cho mã của bạn gọn hơn 2. 19. 3 nhược điểmRất hấp dẫn khi sử dụng những tính năng “hay ho” này khi chúng không thực sự cần thiết. Khó đọc, hiểu và gỡ lỗi mã đang sử dụng các tính năng bất thường bên dưới. Thoạt đầu có vẻ không phải như vậy (đối với tác giả gốc), nhưng khi xem lại mã, nó có xu hướng khó hơn mã dài hơn nhưng đơn giản 2. 19. 4 Quyết địnhTránh các tính năng này trong mã của bạn Các mô-đun và lớp thư viện tiêu chuẩn sử dụng nội bộ các tính năng này đều được phép sử dụng (ví dụ: 229, 230 và 231)2. 20 con trăn hiện đại. từ __future__ nhập khẩuCác thay đổi ngữ nghĩa của phiên bản ngôn ngữ mới có thể được kiểm soát sau quá trình nhập đặc biệt trong tương lai để kích hoạt chúng trên cơ sở từng tệp trong thời gian chạy trước đó 2. 20. 1 Định nghĩaCó thể bật một số tính năng hiện đại hơn thông qua câu lệnh 232 cho phép sử dụng sớm các tính năng từ các phiên bản Python dự kiến trong tương lai2. 20. 2 Ưu điểmĐiều này đã được chứng minh là giúp nâng cấp phiên bản thời gian chạy mượt mà hơn vì các thay đổi có thể được thực hiện trên cơ sở từng tệp trong khi khai báo tính tương thích và ngăn chặn hồi quy trong các tệp đó. Mã hiện đại dễ bảo trì hơn vì ít có khả năng tích lũy nợ kỹ thuật sẽ gây ra sự cố trong quá trình nâng cấp thời gian chạy trong tương lai 2. 20. 3 nhược điểmMã như vậy có thể không hoạt động trên các phiên bản thông dịch viên rất cũ trước khi đưa ra câu lệnh tương lai cần thiết. Nhu cầu này phổ biến hơn trong các dự án hỗ trợ rất nhiều môi trường 2. 20. 4 Quyết địnhtừ __future__ nhập khẩuViệc sử dụng các câu lệnh 232 được khuyến khích. Nó cho phép một tệp nguồn nhất định bắt đầu sử dụng các tính năng cú pháp Python hiện đại hơn ngày nay. Sau khi bạn không còn cần chạy trên phiên bản có các tính năng bị ẩn đằng sau lần nhập 234, vui lòng xóa các dòng đóTrong mã có thể thực thi trên các phiên bản cũ như 3. 5 thay vì >= 3. 7, nhập khẩu 22For more information read the Python future statement definitions documentation Vui lòng không xóa các mục nhập này cho đến khi bạn tin rằng mã này chỉ được sử dụng trong một môi trường đủ hiện đại. Ngay cả khi bạn hiện không sử dụng tính năng mà một tính năng nhập cụ thể trong tương lai cho phép trong mã của bạn hôm nay, thì việc giữ nguyên tính năng này trong tệp sẽ ngăn việc vô tình sửa đổi mã sau này tùy thuộc vào hành vi cũ hơn Sử dụng các báo cáo nhập khẩu 235 khác khi bạn thấy phù hợp2. 21 Loại Mã chú thíchBạn có thể chú thích mã Python bằng gợi ý loại theo PEP-484 và kiểm tra loại mã khi xây dựng bằng công cụ kiểm tra loại như pytype Chú thích loại có thể có trong nguồn hoặc trong tệp pyi còn sơ khai. Bất cứ khi nào có thể, chú thích nên ở trong nguồn. Sử dụng tệp pyi cho bên thứ ba hoặc mô-đun mở rộng 2. 21. 1 Định nghĩaChú thích kiểu (hoặc “gợi ý kiểu”) dành cho các đối số của hàm hoặc phương thức và giá trị trả về 23Bạn cũng có thể khai báo loại biến bằng cú pháp PEP-526 tương tự 2. 21. 2 Ưu điểmLoại chú thích cải thiện khả năng đọc và khả năng bảo trì mã của bạn. Trình kiểm tra loại sẽ chuyển đổi nhiều lỗi thời gian chạy thành lỗi thời gian xây dựng và giảm khả năng sử dụng các Tính năng mạnh mẽ của bạn 2. 21. 3 nhược điểmBạn sẽ phải cập nhật các khai báo kiểu. Bạn có thể thấy lỗi loại mà bạn nghĩ là mã hợp lệ. Việc sử dụng trình kiểm tra loại có thể làm giảm khả năng sử dụng các Tính năng Nguồn của bạn 2. 21. 4 Quyết địnhBạn được khuyến khích bật phân tích kiểu Python khi cập nhật mã. Khi thêm hoặc sửa đổi API công khai, hãy bao gồm các chú thích loại và cho phép kiểm tra qua pytype trong hệ thống xây dựng. Vì phân tích tĩnh còn tương đối mới đối với Python, chúng tôi thừa nhận rằng các tác dụng phụ không mong muốn (chẳng hạn như các loại được suy luận sai) có thể ngăn một số dự án áp dụng. Trong những trường hợp đó, các tác giả được khuyến khích thêm nhận xét bằng TODO hoặc liên kết đến lỗi mô tả (các) sự cố hiện đang ngăn cản việc áp dụng chú thích loại trong tệp BUILD hoặc trong chính mã nếu phù hợp 3 quy tắc kiểu Python3. 1 dấu chấm phẩyKhông kết thúc dòng của bạn bằng dấu chấm phẩy và không sử dụng dấu chấm phẩy để đặt hai câu lệnh trên cùng một dòng 3. 2 Chiều dài dòngĐộ dài dòng tối đa là 80 ký tự Ngoại lệ rõ ràng đối với giới hạn 80 ký tự
Không sử dụng tiếp tục dòng gạch chéo ngược ngoại trừ các câu lệnh 237 yêu cầu ba trình quản lý ngữ cảnh trở lênTận dụng cách nối dòng ẩn của Python bên trong dấu ngoặc đơn, dấu ngoặc và dấu ngoặc nhọn. Nếu cần, bạn có thể thêm một cặp dấu ngoặc đơn xung quanh một biểu thức 24Khi một chuỗi ký tự không vừa trên một dòng, hãy sử dụng dấu ngoặc đơn để nối dòng ẩn 25Trong các nhận xét, hãy đặt các URL dài trên dòng riêng của chúng nếu cần 26 27Có thể sử dụng tiếp tục dấu gạch chéo ngược khi xác định câu lệnh 237 có biểu thức kéo dài từ ba dòng trở lên. Đối với hai dòng biểu thức, hãy sử dụng câu lệnh 237 lồng nhau 28 29 30Lưu ý về sự thụt đầu dòng của các phần tử trong các ví dụ tiếp tục dòng ở trên; Trong tất cả các trường hợp khác khi một dòng vượt quá 80 ký tự và trình định dạng tự động yapf không giúp đưa dòng xuống dưới giới hạn, thì dòng đó được phép vượt quá mức tối đa này. Các tác giả được khuyến khích ngắt dòng theo cách thủ công theo ghi chú ở trên khi thấy hợp lý 3. 3 dấu ngoặc đơnUse parentheses sparingly Nó là tốt, mặc dù không bắt buộc, để sử dụng dấu ngoặc đơn xung quanh bộ dữ liệu. Không sử dụng chúng trong các câu lệnh trả về hoặc câu lệnh có điều kiện trừ khi sử dụng dấu ngoặc đơn để tiếp tục dòng ngụ ý hoặc để chỉ ra một bộ 31 323. 4 Thụt đầu dòngThụt lề các khối mã của bạn với 4 dấu cách Không bao giờ sử dụng các tab. Việc tiếp tục dòng ngụ ý phải căn chỉnh các phần tử được bao theo chiều dọc (xem ví dụ về độ dài dòng) hoặc sử dụng thụt lề 4 khoảng trắng treo. Dấu ngoặc đóng (tròn, vuông hoặc cong) có thể được đặt ở cuối biểu thức hoặc trên các dòng riêng biệt, nhưng sau đó phải được thụt vào giống như dòng có dấu ngoặc mở tương ứng 33 343. 4. 1 Dấu phẩy ở cuối dãy các mục?Dấu phẩy ở cuối trong chuỗi các mục chỉ được khuyến nghị khi mã thông báo vùng chứa đóng 240, 241 hoặc 242 không xuất hiện trên cùng một dòng với phần tử cuối cùng. Sự hiện diện của dấu phẩy ở cuối cũng được sử dụng như một gợi ý cho trình định dạng tự động mã Python YAPF của chúng tôi để hướng dẫn nó tự động định dạng vùng chứa các mục thành một mục trên mỗi dòng khi có ____ ______3243 sau phần tử cuối cùng 353. 5 dòng trốngHai dòng trống giữa các định nghĩa cấp cao nhất, có thể là định nghĩa hàm hoặc lớp. Một dòng trống giữa các định nghĩa phương thức và giữa dòng 244 và phương thức đầu tiên. Không có dòng trống nào sau dòng 245. Sử dụng các dòng trống đơn khi bạn đánh giá phù hợp trong các hàm hoặc phương thứcCác dòng trống không cần phải được neo vào định nghĩa. Ví dụ: các nhận xét liên quan ngay trước các định nghĩa hàm, lớp và phương thức có thể có ý nghĩa. Cân nhắc xem nhận xét của bạn có thể hữu ích hơn như một phần của chuỗi tài liệu không 3. 6 Khoảng trắngThực hiện theo các quy tắc đánh máy tiêu chuẩn để sử dụng khoảng trắng xung quanh dấu chấm câu Không có khoảng trắng bên trong dấu ngoặc đơn, dấu ngoặc hoặc dấu ngoặc nhọn 36 37Không có khoảng trắng trước dấu phẩy, dấu chấm phẩy hoặc dấu hai chấm. Sử dụng khoảng trắng sau dấu phẩy, dấu chấm phẩy hoặc dấu hai chấm, ngoại trừ ở cuối dòng 38 39Không có khoảng trắng trước dấu ngoặc đơn/ngoặc mở bắt đầu danh sách đối số, lập chỉ mục hoặc cắt 40 41Không có khoảng trắng ở cuối Bao quanh các toán tử nhị phân với một khoảng trắng ở hai bên để gán ( 246), so sánh ( 247) và Booleans ( 248). Sử dụng phán đoán tốt hơn của bạn để chèn khoảng trắng xung quanh các toán tử số học ( 249, 250, 251, 252, 253, 254, 255, 217)Không bao giờ sử dụng khoảng trắng xung quanh 246 khi chuyển đối số từ khóa hoặc xác định giá trị tham số mặc định, với một ngoại lệ. khi có chú thích loại, hãy sử dụng khoảng trắng xung quanh 246 cho giá trị tham số mặc định 42 43Không sử dụng khoảng trắng để sắp xếp theo chiều dọc mã thông báo trên các dòng liên tiếp, vì nó sẽ trở thành gánh nặng bảo trì (áp dụng cho 259, 260, 246, v.v. ) 44 453. 7 dòng ShebangHầu hết các tệp 262 không cần bắt đầu bằng dòng 263. Bắt đầu tệp chính của chương trình với 264 (để hỗ trợ virtualenv) hoặc 265 mỗi PEP-394Dòng này được nhân sử dụng để tìm trình thông dịch Python, nhưng bị Python bỏ qua khi nhập mô-đun. Nó chỉ cần thiết trên một tệp dự định được thực thi trực tiếp Đảm bảo sử dụng đúng kiểu cho mô-đun, hàm, chuỗi tài liệu phương thức và nhận xét nội tuyến 3. 8. 1 tài liệuPython sử dụng docstrings để viết mã tài liệu. Chuỗi tài liệu là một chuỗi là câu lệnh đầu tiên trong gói, mô-đun, lớp hoặc hàm. Các chuỗi này có thể được trích xuất tự động thông qua thành viên 266 của đối tượng và được sử dụng bởi 220. (Hãy thử chạy 220 trên mô-đun của bạn để xem nó trông như thế nào. ) Always use the three double-quote 269 format for docstrings (per PEP 257). Chuỗi tài liệu phải được tổ chức dưới dạng một dòng tóm tắt (một dòng vật lý không quá 80 ký tự) được kết thúc bằng dấu chấm, dấu chấm hỏi hoặc dấu chấm than. Khi viết thêm (khuyến khích), dòng này phải được theo sau bởi một dòng trống, tiếp theo là phần còn lại của chuỗi tài liệu bắt đầu ở cùng vị trí con trỏ với trích dẫn đầu tiên của dòng đầu tiên. Có nhiều hướng dẫn định dạng hơn cho các tài liệu bên dưới3. 8. 2 mô-đunMỗi tệp phải chứa giấy phép soạn sẵn. Chọn bản soạn sẵn thích hợp cho giấy phép được dự án sử dụng (ví dụ: Apache 2. 0, BSD, LGPL, GPL) Các tệp phải bắt đầu bằng một chuỗi tài liệu mô tả nội dung và cách sử dụng mô-đun 463. 8. 3 Hàm và Phương thứcTrong phần này, "hàm" có nghĩa là một phương thức, chức năng hoặc trình tạo Một hàm phải có một chuỗi tài liệu, trừ khi nó đáp ứng tất cả các tiêu chí sau
Một chuỗi tài liệu phải cung cấp đủ thông tin để viết lệnh gọi đến hàm mà không cần đọc mã của hàm. Chuỗi tài liệu phải mô tả cú pháp gọi của hàm và ngữ nghĩa của nó, nhưng nói chung không phải là chi tiết triển khai của nó, trừ khi những chi tiết đó có liên quan đến cách sử dụng hàm. Ví dụ: một hàm thay đổi một trong các đối số của nó dưới dạng tác dụng phụ cần lưu ý rằng trong chuỗi tài liệu của nó. Mặt khác, các chi tiết tinh tế nhưng quan trọng về việc triển khai chức năng không liên quan đến người gọi sẽ được thể hiện dưới dạng nhận xét bên cạnh mã tốt hơn là trong chuỗi tài liệu của chức năng Chuỗi tài liệu phải là kiểu mô tả (______3270) thay vì kiểu mệnh lệnh ( 271). Chuỗi tài liệu cho bộ mô tả dữ liệu 86 phải sử dụng cùng kiểu với chuỗi tài liệu cho thuộc tính hoặc đối số hàm ( 273, thay vì 274)Một phương thức ghi đè một phương thức từ một lớp cơ sở có thể có một chuỗi tài liệu đơn giản gửi trình đọc đến chuỗi tài liệu của phương thức được ghi đè, chẳng hạn như 275. Cơ sở lý luận là không cần phải lặp lại ở nhiều nơi tài liệu đã có trong chuỗi tài liệu của phương thức cơ sở. Tuy nhiên, nếu hành vi của phương thức ghi đè về cơ bản khác với phương thức bị ghi đè hoặc cần cung cấp thông tin chi tiết (e. g. , ghi lại các tác dụng phụ bổ sung), một chuỗi tài liệu có ít nhất những điểm khác biệt đó là bắt buộc đối với phương thức ghi đèMột số khía cạnh của một chức năng nên được ghi lại trong các phần đặc biệt, được liệt kê bên dưới. Mỗi phần bắt đầu bằng một dòng tiêu đề, kết thúc bằng dấu hai chấm. Tất cả các phần không phải là tiêu đề nên duy trì thụt lề treo hai hoặc bốn khoảng trắng (nhất quán trong một tệp). Các phần này có thể được bỏ qua trong trường hợp tên và chữ ký của hàm đủ thông tin để có thể mô tả chính xác bằng cách sử dụng chuỗi tài liệu một dòng lập luận. Liệt kê từng tham số theo tên. Mô tả phải theo sau tên và được phân tách bằng dấu hai chấm, sau đó là khoảng trắng hoặc xuống dòng. Nếu mô tả quá dài để vừa với một dòng 80 ký tự, hãy sử dụng thụt lề treo nhiều hơn 2 hoặc 4 khoảng trắng so với tên tham số (nhất quán với phần còn lại của chuỗi tài liệu trong tệp). Mô tả phải bao gồm (các) loại bắt buộc nếu mã không chứa chú thích loại tương ứng. Nếu một hàm chấp nhận 276 (danh sách đối số có độ dài thay đổi) và/hoặc 277 (đối số từ khóa tùy ý), thì chúng phải được liệt kê là 276 và 277. trả lại. (hoặc Sản lượng. cho trình tạo) Mô tả loại và ngữ nghĩa của giá trị trả về. Nếu hàm chỉ trả về Không thì không cần phần này. Nó cũng có thể được bỏ qua nếu chuỗi tài liệu bắt đầu bằng Returns hoặc Yields (e. g. 280) và câu mở đầu đủ để mô tả giá trị trả về. Không bắt chước 'kiểu NumPy' (ví dụ), kiểu này thường ghi lại giá trị trả về của bộ dữ liệu như thể đó là nhiều giá trị trả về với các tên riêng lẻ (không bao giờ đề cập đến bộ dữ liệu). Thay vào đó, hãy mô tả một giá trị trả về như. “Trả về. Một bộ (mat_a, mat_b), trong đó mat_a là …, và…”. Các tên phụ trợ trong chuỗi tài liệu không nhất thiết phải tương ứng với bất kỳ tên nội bộ nào được sử dụng trong thân hàm (vì chúng không phải là một phần của API). tăng. Liệt kê tất cả các ngoại lệ có liên quan đến giao diện theo sau là mô tả. Sử dụng tên ngoại lệ tương tự + dấu hai chấm + dấu cách hoặc dòng mới và kiểu thụt lề treo như được mô tả trong Args. Bạn không nên ghi lại các trường hợp ngoại lệ được nêu ra nếu API được chỉ định trong chuỗi tài liệu bị vi phạm (vì điều này nghịch lý sẽ tạo ra hành vi vi phạm phần API của API) 47Tương tự, biến thể này trên 281 có ngắt dòng cũng được cho phép 483. 8. 4 ClassesClasses should have a docstring below the class definition describing the class. If your class has public attributes, they should be documented here in an 282 section and follow the same formatting as a function’s 283 section 49All class docstrings should start with a one-line summary that describes what the class instance represents. This implies that subclasses of 56 should also describe what the exception represents, and not the context in which it might occur. The class docstring should not repeat unnecessary information, such as that the class is a class 70 713. 8. 5 Block and Inline CommentsThe final place to have comments is in tricky parts of the code. If you’re going to have to explain it at the next code review, you should comment it now. Complicated operations get a few lines of comments before the operations commence. Non-obvious ones get comments at the end of the line 72To improve legibility, these comments should start at least 2 spaces away from the code with the comment character 260, followed by at least one space before the text of the comment itselfOn the other hand, never describe the code. Assume the person reading the code knows Python (though not what you’re trying to do) better than you do 733. 8. 6 Punctuation, Spelling, and GrammarPay attention to punctuation, spelling, and grammar; it is easier to read well-written comments than badly written ones Comments should be as readable as narrative text, with proper capitalization and punctuation. In many cases, complete sentences are more readable than sentence fragments. Shorter comments, such as comments at the end of a line of code, can sometimes be less formal, but you should be consistent with your style Although it can be frustrating to have a code reviewer point out that you are using a comma when you should be using a semicolon, it is very important that source code maintain a high level of clarity and readability. Proper punctuation, spelling, and grammar help with that goal 3. 10 StringsUse an f-string, the 254 operator, or the 287 method for formatting strings, even when the parameters are all strings. Use your best judgment to decide between 249 and string formatting 74 75Avoid using the 249 and 290 operators to accumulate a string within a loop. In some conditions, accumulating a string with addition can lead to quadratic rather than linear running time. Although common accumulations of this sort may be optimized on CPython, that is an implementation detail. The conditions under which an optimization applies are not easy to predict and may change. Instead, add each substring to a list and 291 the list after the loop terminates, or write each substring to an 292 buffer. These techniques consistently have amortized-linear run time complexity 76 77Be consistent with your choice of string quote character within a file. Pick 293 or 294 and stick with it. It is okay to use the other quote character on a string to avoid the need to backslash-escape quote characters within the string 78 79Prefer 269 for multi-line strings rather than 296. Projects may choose to use 296 for all non-docstring multi-line strings if and only if they also use 293 for regular strings. Docstrings must use 269 regardlessMulti-line strings do not flow with the indentation of the rest of the program. If you need to avoid embedding extra space in the string, use either concatenated single-line strings or a multi-line string with 300 to remove the initial space on each line 50 51 52 53 543. 10. 1 LoggingFor logging functions that expect a pattern-string (with %-placeholders) as their first argument. Always call them with a string literal (not an f-string. ) as their first argument with pattern-parameters as subsequent arguments. Some logging implementations collect the unexpanded pattern-string as a queryable field. It also prevents spending time rendering a message that no logger is configured to output 55 56 573. 10. 2 Error MessagesError messages (such as. message strings on exceptions like 50, or messages shown to the user) should follow three guidelines
58 593. 11 Files, Sockets, and similar Stateful ResourcesExplicitly close files and sockets when done with them. This rule naturally extends to closeable resources that internally use sockets, such as database connections, and also other resources that need to be closed down in a similar fashion. To name only a few examples, this also includes mmap mappings, h5py File objects, and matplotlib. pyplot figure windows Leaving files, sockets or other such stateful objects open unnecessarily has many downsides
Furthermore, while files and sockets (and some similarly behaving resources) are automatically closed when the object is destructed, coupling the lifetime of the object to the state of the resource is poor practice
Relying on finalizers to do automatic cleanup that has observable side effects has been rediscovered over and over again to lead to major problems, across many decades and multiple languages (see e. g. this article for Java) The preferred way to manage files and similar resources is using the 237 statement 60For file-like objects that do not support the 237 statement, use 305 61In rare cases where context-based resource management is infeasible, code documentation must explain clearly how resource lifetime is managed Use 306 comments for code that is temporary, a short-term solution, or good-enough but not perfectA 306 comment begins with the word 306 in all caps, and a parenthesized context identifier. Ideally a bug reference, sometimes a username. A bug reference like 309 is preferable, because bugs are tracked and have follow-up comments, whereas individuals move around and may lose context over time. The 306 is followed by an explanation of what there is to doThe purpose is to have a consistent 306 format that can be searched to find out how to get more details. A 306 is not a commitment that the person referenced will fix the problem. Do đó, khi bạn tạo một 306 với tên người dùng, thì hầu như tên người dùng của bạn luôn được cung cấp 62Nếu 306 của bạn có dạng “Vào một ngày trong tương lai, hãy làm điều gì đó”, hãy đảm bảo rằng bạn bao gồm một ngày rất cụ thể (“Khắc phục trước tháng 11 năm 2009”) hoặc một sự kiện rất cụ thể (“Xóa mã này khi tất cả khách hàng có thể xử lý phản hồi XML. ”) that future code maintainers will comprehend3. 13 Nhập định dạngNhập khẩu nên được trên các dòng riêng biệt; E. g 63Imports are always put at the top of the file, just after any module comments and docstrings and before module globals and constants. Nhập khẩu nên được nhóm từ chung chung nhất đến ít chung chung nhất
Within each grouping, imports should be sorted lexicographically, ignoring case, according to each module’s full package path (the 317 in 318). Code may optionally place a blank line between import sections 673. 14 StatementsGenerally only one statement per line However, you may put the result of a test on the same line as the test only if the entire statement fits on one line. In particular, you can never do so with 59/ 60 since the 59 and 60 can’t both fit on the same line, and you can only do so with an 323 if there is no 324 683. 15 Getters and SettersGetter and setter functions (also called accessors and mutators) should be used when they provide a meaningful role or behavior for getting or setting a variable’s value In particular, they should be used when getting or setting the variable is complex or the cost is significant, either currently or in a reasonable future If, for example, a pair of getters/setters simply read and write an internal attribute, the internal attribute should be made public instead. By comparison, if setting a variable means some state is invalidated or rebuilt, it should be a setter function. The function invocation hints that a potentially non-trivial operation is occurring. Alternatively, properties may be an option when simple logic is needed, or refactoring to no longer need getters and setters Getters and setters should follow the Naming guidelines, such as 325 and 326If the past behavior allowed access through a property, do not bind the new getter/setter functions to the property. Any code still attempting to access the variable by the old method should break visibly so they are made aware of the change in complexity 3. 16 Naming 327, 328, 329, 330, 331, 332, 333, 334, 335, 336, 337, 338, 339Function names, variable names, and filenames should be descriptive; avoid abbreviation. In particular, do not use abbreviations that are ambiguous or unfamiliar to readers outside your project, and do not abbreviate by deleting letters within a word Always use a 262 filename extension. Never use dashes3. 16. 1 Names to Avoid
3. 16. 2 Naming Conventions
3. 16. 3 File NamingPython filenames must have a 262 extension and must not contain dashes ( 250). This allows them to be imported and unittested. If you want an executable to be accessible without the extension, use a symbolic link or a simple bash wrapper containing 3663. 16. 4 Guidelines derived from Guido’s RecommendationsTypePublicInternalPackages 367Modules 367 369Classes 370 371Exceptions 370Functions 373 374Global/Class Constants 375 376Global/Class Variables 367 369Instance Variables 367 369 (protected)Method Names 373 374 (protected)Function/Method Parameters 367Local Variables 3673. 16. 5 Mathematical NotationFor mathematically heavy code, short variable names that would otherwise violate the style guide are preferred when they match established notation in a reference paper or algorithm. When doing so, reference the source of all naming conventions in a comment or docstring or, if the source is not accessible, clearly document the naming conventions. Prefer PEP8-compliant 385 for public APIs, which are much more likely to be encountered out of context3. 17 MainIn Python, 220 as well as unit tests require modules to be importable. If a file is meant to be used as an executable, its main functionality should be in a 387 function, and your code should always check 388 before executing your main program, so that it is not executed when the module is importedWhen using absl, use 389 69Otherwise, use 90All code at the top level will be executed when the module is imported. Be careful not to call functions, create objects, or perform other operations that should not be executed when the file is being 220ed3. 18 Function lengthPrefer small and focused functions We recognize that long functions are sometimes appropriate, so no hard limit is placed on function length. If a function exceeds about 40 lines, think about whether it can be broken up without harming the structure of the program Even if your long function works perfectly now, someone modifying it in a few months may add new behavior. This could result in bugs that are hard to find. Keeping your functions short and simple makes it easier for other people to read and modify your code You could find long and complicated functions when working with some code. Do not be intimidated by modifying existing code. if working with such a function proves to be difficult, you find that errors are hard to debug, or you want to use a piece of it in several different contexts, consider breaking up the function into smaller and more manageable pieces 3. 19 Type Annotations3. 19. 1 General Rules
3. 19. 2 Line BreakingTry to follow the existing indentation rules After annotating, many function signatures will become “one parameter per line”. To ensure the return type is also given its own line, a comma can be placed after the last parameter 92Always prefer breaking between variables, and not, for example, between variable names and type annotations. However, if everything fits on the same line, go for it 93If the combination of the function name, the last parameter, and the return type is too long, indent by 4 in a new line. When using line breaks, prefer putting each parameter and the return type on their own lines and aligning the closing parenthesis with the 245 94Optionally, the return type may be put on the same line as the last parameter 95 14 allows you to move the closing parenthesis to a new line and align with the opening one, but this is less readable 96As in the examples above, prefer not to break types. However, sometimes they are too long to be on a single line (try to keep sub-types unbroken) 97If a single name and type is too long, consider using an alias for the type. The last resort is to break after the colon and indent by 4 98 993. 19. 3 Forward DeclarationsIf you need to use a class name from the same module that is not yet defined – for example, if you need the class inside the class declaration, or if you use a class that is defined below – either use 398 for simple cases or use a string for the class name 003. 19. 4 Default ValuesAs per PEP-008, use spaces around the 246 only for arguments that have both a type annotation and a default value 01 023. 19. 5 NoneTypeIn the Python type system, 400 is a “first class” type, and for typing purposes, 93 is an alias for 400. If an argument can be 93, it has to be declared. You can use 404, but if there is only one other type, use 405Use explicit 405 instead of implicit 405. Earlier versions of PEP 484 allowed 408 to be interpreted as 409, but that is no longer the preferred behavior 03 043. 19. 6 Type AliasesYou can declare aliases of complex types. The name of an alias should be CapWorded. If the alias is used only in this module, it should be _Private For example, if the name of the module together with the name of the type is too long 05Other examples are complex nested types and multiple return variables from a function (as a tuple) 3. 19. 7 Ignoring TypesYou can disable type checking on a line with the special comment 410 411 has a disable option for specific errors (similar to lint) 063. 19. 8 Typing VariablesAnnotated AssignmentsIf an internal variable has a type that is hard or impossible to infer, specify its type with an annotated assignment - use a colon and type between the variable name and value (the same as is done with function arguments that have a default value) 07Type CommentsThough you may see them remaining in the codebase (they were necessary before Python 3. 6), do not add any more uses of a 412 comment on the end of the line 083. 19. 9 Tuples vs ListsTyped lists can only contain objects of a single type. Typed tuples can either have a single repeated type or a set number of elements with different types. The latter is commonly used as the return type from a function 093. 19. 10 TypeVarsThe Python type system has generics. The factory function 349 is a common way to use themExample 00A TypeVar can be constrained 01A common predefined type variable in the 315 module is 415. Use it for multiple annotations that can be 416 or 417 and must all be the same type 02A TypeVar must have a descriptive name, unless it meets all of the following criteria
03 043. 19. 11 String types
Use 417 for string/text data. For code that deals with binary data, use 416 05If all the string types of a function are always the same, for example if the return type is the same as the argument type in the code above, use AnyStr 3. 19. 12 Imports For TypingFor symbols from the 315 and 316 modules used to support static analysis and type checking, always import the symbol itself. This keeps common annotations more concise and matches typing practices used around the world. You are explicitly allowed to import multiple specific classes on one line from the 315 and 316 modules. Ex 06Given that this way of importing adds items to the local namespace, names in 315 or 316 should be treated similarly to keywords, and not be defined in your Python code, typed or not. If there is a collision between a type and an existing name in a module, import it using 427 073. 19. 13 Conditional ImportsUse conditional imports only in exceptional cases where the additional imports needed for type checking must be avoided at runtime. This pattern is discouraged; alternatives such as refactoring the code to allow top level imports should be preferred Imports that are needed only for type annotations can be placed within an 428 block
3. 19. 14 Circular DependenciesCircular dependencies that are caused by typing are code smells. Such code is a good candidate for refactoring. Although technically it is possible to keep circular dependencies, various build systems will not let you do so because each module has to depend on the other Replace modules that create circular dependency imports with 395. Set an alias with a meaningful name, and use the real type name from this module (any attribute of Any is Any). Alias definitions should be separated from the last import by one line 093. 19. 15 thuốc gốcKhi chú thích, ưu tiên chỉ định tham số loại cho các loại chung; 10 11If the best type parameter for a generic is 395, make it explicit, but remember that in many cases 349 might be more appropriate 12 134 Parting WordsBE CONSISTENT If you’re editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too Mục đích của việc có các hướng dẫn về phong cách là có một vốn từ vựng chung về viết mã để mọi người có thể tập trung vào những gì bạn đang nói hơn là vào cách bạn nói. We present global style rules here so people know the vocabulary, but local style is also important. Nếu mã bạn thêm vào một tệp trông khác hẳn so với mã hiện có xung quanh nó, nó sẽ khiến người đọc mất nhịp khi họ đọc nó. Tránh điều này |