Hướng dẫn python programming style - phong cách lập trình python

Vết lõm

Sử dụng 4 không gian trên mỗi cấp độ thụt.

Các dòng tiếp tục nên căn chỉnh các phần tử được bọc theo chiều dọc bằng cách sử dụng đường thẳng của Python, nối bên trong dấu ngoặc đơn, dấu ngoặc và niềng răng hoặc sử dụng thụt lề treo [1]. Khi sử dụng thụt lề treo sau đây nên được xem xét; Không nên có đối số trên dòng đầu tiên và nên sử dụng thụt thêm để phân biệt rõ ràng là một dòng tiếp tục:

# Correct:

# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# Add 4 spaces (an extra level of indentation) to distinguish arguments from the rest.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

# Hanging indents should add a level.
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

Quy tắc 4 không gian là tùy chọn cho các dòng tiếp tục.

Optional:

# Hanging indents *may* be indented to other than 4 spaces.
foo = long_function_name(
  var_one, var_two,
  var_three, var_four)

Khi phần có điều kiện của ____ ____ 66-statement đủ dài để yêu cầu nó được viết trên nhiều dòng, điều đáng chú ý là sự kết hợp của một từ khóa hai ký tự (tức là

with open('/path/to/some/file/you/want/to/read') as file_1, \
     open('/path/to/some/file/being/written', 'w') as file_2:
    file_2.write(file_1.read())

# No extra indentation.
if (this_is_one_thing and
    that_is_another_thing):
    do_something()

# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
    that_is_another_thing):
    # Since both conditions are true, we can frobnicate.
    do_something()

# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

(Cũng xem các cuộc thảo luận về việc nên phá vỡ trước hay sau các nhà khai thác nhị phân bên dưới.)

Đóng nẹp/giá đỡ/dấu ngoặc đơn trên các cấu trúc đa dòng có thể xếp theo ký tự không phải là màu đầu tiên của dòng danh sách cuối cùng, như trong:

my_list = [
    1, 2, 3,
    4, 5, 6,
    ]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
    )

Hoặc nó có thể được xếp hàng dưới ký tự đầu tiên của dòng bắt đầu cấu trúc đa dòng, như trong:

my_list = [
    1, 2, 3,
    4, 5, 6,
]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
)

Tab hoặc không gian?

Không gian là phương pháp thụt đầu tiên ưa thích.

Các tab chỉ nên được sử dụng để duy trì sự phù hợp với mã đã được thụt vào với các tab.

Python không hoàn toàn trộn lẫn các tab và không gian để thụt vào.

Chiều dài đường tối đa

Giới hạn tất cả các dòng ở mức tối đa 79 ký tự.

Đối với các khối văn bản dài với các hạn chế cấu trúc ít hơn (tài liệu hoặc nhận xét), độ dài dòng phải được giới hạn ở 72 ký tự.

Giới hạn chiều rộng cửa sổ Trình soạn thảo cần thiết cho phép có một số tệp mở cạnh nhau và hoạt động tốt khi sử dụng các công cụ đánh giá mã trình bày hai phiên bản trong các cột liền kề.

Việc gói mặc định trong hầu hết các công cụ phá vỡ cấu trúc trực quan của mã, khiến nó khó hiểu hơn. Các giới hạn được chọn để tránh bọc trong các trình chỉnh sửa với chiều rộng cửa sổ được đặt thành 80, ngay cả khi công cụ đặt một glyph điểm trong cột cuối cùng khi các dòng gói. Một số công cụ dựa trên web có thể không cung cấp kết thúc dòng động.

Một số đội thích mạnh mẽ một dòng dài hơn. Đối với mã được duy trì độc quyền hoặc chủ yếu bởi một nhóm có thể đạt được thỏa thuận về vấn đề này, có thể tăng giới hạn độ dài dòng lên tới 99 ký tự, với điều kiện là nhận xét và tài liệu vẫn được gói ở 72 ký tự.

Thư viện tiêu chuẩn Python là bảo thủ và yêu cầu giới hạn các dòng cho 79 ký tự (và tài liệu/nhận xét đến 72).

Cách ưa thích để gói các đường dài là bằng cách sử dụng sự tiếp tục dòng ngụ ý của Python, bên trong ngoặc đơn, ngoặc và thanh giằng. Các đường dài có thể được phá vỡ trên nhiều dòng bằng cách gói các biểu thức trong ngoặc đơn. Chúng nên được sử dụng theo sở thích để sử dụng dấu gạch chéo ngược để tiếp tục dòng.

Backslashes vẫn có thể phù hợp đôi khi. Ví dụ, dài, nhiều ____ 70 không thể sử dụng tiếp tục ngầm trước Python 3.10, do đó, dấu gạch chéo ngược được chấp nhận cho trường hợp đó:

with open('/path/to/some/file/you/want/to/read') as file_1, \
     open('/path/to/some/file/being/written', 'w') as file_2:
    file_2.write(file_1.read())

.

Một trường hợp khác là với các tuyên bố

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

Hãy chắc chắn để thụt dòng dòng tiếp tục một cách thích hợp.

Có nên phá vỡ dòng trước hoặc sau khi vận hành nhị phân?

Trong nhiều thập kỷ, phong cách được đề xuất là phá vỡ sau khi các nhà khai thác nhị phân. Nhưng điều này có thể làm tổn thương khả năng đọc theo hai cách: các nhà khai thác có xu hướng nằm rải rác trên các cột khác nhau trên màn hình và mỗi toán tử được chuyển ra khỏi toán hạng của nó và vào dòng trước. Ở đây, mắt phải làm thêm để cho biết mục nào được thêm vào và cái nào được trừ:

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

Để giải quyết vấn đề dễ đọc này, các nhà toán học và các nhà xuất bản của họ tuân theo quy ước ngược lại. Donald Knuth giải thích quy tắc truyền thống trong các máy tính và loạt sắp xếp của mình: Mặc dù các công thức trong một đoạn văn luôn bị phá vỡ sau các hoạt động và quan hệ nhị phân, các công thức hiển thị luôn bị phá vỡ trước khi hoạt động nhị phân [3].

Theo truyền thống từ toán học thường dẫn đến mã dễ đọc hơn:

# Correct:
# easy to match operators with operands
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

Trong mã Python, được phép phá vỡ trước hoặc sau một toán tử nhị phân, miễn là quy ước là nhất quán tại địa phương. Đối với phong cách mới Knuth Knuth được đề xuất.

Các dòng trống

Chức năng cấp cao nhất và định nghĩa lớp với hai dòng trống.

Các định nghĩa phương pháp bên trong một lớp được bao quanh bởi một dòng trống duy nhất.

Các dòng trống có thể được sử dụng (một cách tiết kiệm) để tách các nhóm chức năng liên quan. Các dòng trống có thể được bỏ qua giữa một loạt các lớp lót liên quan (ví dụ: một tập hợp các triển khai giả).

Sử dụng các dòng trống trong các chức năng, một cách tiết kiệm, để chỉ ra các phần logic.

Python chấp nhận ký tự thức ăn điều khiển-l (tức là ^l) là khoảng trắng; Nhiều công cụ coi các ký tự này là dấu phân cách trang, vì vậy bạn có thể sử dụng chúng để tách các trang liên quan đến tệp của mình. Lưu ý, một số trình chỉnh sửa và người xem mã dựa trên web có thể không nhận ra Control-L là nguồn cấp dữ liệu biểu mẫu và sẽ hiển thị một glyph khác ở vị trí của nó.

Mã hóa tập tin nguồn

Mã trong phân phối Python cốt lõi phải luôn luôn sử dụng UTF-8 và không nên có khai báo mã hóa.

Trong thư viện tiêu chuẩn, các mã hóa không phải UTF-8 chỉ nên được sử dụng cho mục đích thử nghiệm. Sử dụng các ký tự không phải ASCII một cách tiết kiệm, tốt nhất là chỉ để biểu thị địa điểm và tên người. Nếu sử dụng các ký tự không phải ASCII làm dữ liệu, hãy tránh các ký tự unicode ồn ào như z̯̯͡a̧͎̺l̡͓̫g̹̲o̡̼̘ và các dấu lệnh byte.

Tất cả các định danh trong thư viện tiêu chuẩn Python phải sử dụng các định danh chỉ ASCII-ASCII và nên sử dụng các từ tiếng Anh ở bất cứ nơi nào khả thi (trong nhiều trường hợp, viết tắt và thuật ngữ kỹ thuật được sử dụng mà aren tiếng Anh).

Các dự án nguồn mở với khán giả toàn cầu được khuyến khích áp dụng chính sách tương tự.

Nhập khẩu

• Nhập khẩu thường phải ở trên các dòng riêng biệt:

  # Correct:
  import os
  import sys
  

  Nó có thể nói điều này mặc dù:

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  0

• Nhập khẩu luôn được đặt ở đầu tệp, ngay sau khi bất kỳ bình luận và tài liệu mô -đun nào, và trước khi mô -đun toàn cầu và hằng số.

  Nhập khẩu phải được nhóm theo thứ tự sau:

  1. Nhập khẩu thư viện tiêu chuẩn.
  2. Nhập khẩu của bên thứ ba liên quan.
  3. Ứng dụng cục bộ/Thư viện nhập khẩu cụ thể.

  Bạn nên đặt một dòng trống giữa mỗi nhóm nhập khẩu.

• Nhập khẩu tuyệt đối được khuyến nghị, vì chúng thường dễ đọc hơn và có xu hướng hoạt động tốt hơn (hoặc ít nhất là đưa ra thông báo lỗi tốt hơn) nếu hệ thống nhập được cấu hình không chính xác (chẳng hạn như khi thư mục bên trong gói kết thúc trên

  # Wrong:
  # operators sit far away from their operands
  income = (gross_wages +
            taxable_interest +
            (dividends - qualified_dividends) -
            ira_deduction -
            student_loan_interest)
  

  3):

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  1

  Tuy nhiên, nhập khẩu tương đối rõ ràng là một sự thay thế có thể chấp nhận được đối với nhập khẩu tuyệt đối, đặc biệt là khi xử lý các bố cục gói phức tạp trong đó sử dụng nhập khẩu tuyệt đối sẽ là dòng chảy không cần thiết:

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  2

  Mã thư viện tiêu chuẩn nên tránh bố cục gói phức tạp và luôn sử dụng nhập khẩu tuyệt đối.

• Khi nhập một lớp từ một mô-đun chứa lớp, nó thường ổn khi đánh vần điều này:

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  3

  Nếu chính tả này gây ra tiếng vang địa phương, thì hãy đánh vần chúng một cách rõ ràng:

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  4

  và sử dụng các loại myclass.myclass và và foo.bar.yourclass.yourclass.

• Nên tránh nhập khẩu ký tự đại diện (

  # Wrong:
  # operators sit far away from their operands
  income = (gross_wages +
            taxable_interest +
            (dividends - qualified_dividends) -
            ira_deduction -
            student_loan_interest)
  

  4), vì chúng làm cho nó không rõ tên nào có trong không gian tên, gây nhầm lẫn cho cả người đọc và nhiều công cụ tự động. Có một trường hợp sử dụng có thể phòng thủ để nhập thẻ đại diện, đó là tái xuất bản giao diện nội bộ như một phần của API công khai (ví dụ, ghi đè lên việc triển khai Python thuần túy của giao diện với các định nghĩa từ mô -đun tăng tốc tùy chọn và chính xác định nghĩa nào sẽ là Ghi đè không được biết trước).

  Khi xuất bản lại tên theo cách này, các hướng dẫn dưới đây liên quan đến giao diện công cộng và nội bộ vẫn được áp dụng.

Tên Dunder cấp độ mô -đun

Mức độ mô -đun, Dunders Dunders (tức là tên có hai dấu gạch dưới và hai dấu gạch ngang), chẳng hạn như

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

Thói xấu

Tránh khoảng trắng bên ngoài trong các tình huống sau:

• Ngay bên trong dấu ngoặc đơn, ngoặc hoặc niềng răng:

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  6

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  7

• Giữa dấu phẩy kéo dài và dấu ngoặc đơn sau:
• Ngay trước dấu phẩy, dấu chấm phẩy hoặc đại tràng:

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  8

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  9

• Tuy nhiên, trong một lát cắt, ruột kết hoạt động giống như một toán tử nhị phân và nên có số lượng bằng nhau ở hai bên (coi nó là người vận hành có mức độ ưu tiên thấp nhất). Trong một lát mở rộng, cả hai dấu chấm đều phải có cùng một khoảng cách được áp dụng. Ngoại lệ: Khi một tham số lát cắt bị bỏ qua, không gian bị bỏ qua:

  # Hanging indents *may* be indented to other than 4 spaces.
  foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
  

  0

  # Hanging indents *may* be indented to other than 4 spaces.
  foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
  

  1

• Ngay trước khi dấu ngoặc đơn khởi động danh sách đối số của một cuộc gọi chức năng:
• Ngay trước dấu ngoặc đơn mở ra một chỉ mục hoặc cắt:

  # Hanging indents *may* be indented to other than 4 spaces.
  foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
  

  2

  # Hanging indents *may* be indented to other than 4 spaces.
  foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
  

  3

• Nhiều hơn một không gian xung quanh một toán tử chuyển nhượng (hoặc khác) để căn chỉnh nó với một toán tử khác:

  # Hanging indents *may* be indented to other than 4 spaces.
  foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
  

  4

  # Hanging indents *may* be indented to other than 4 spaces.
  foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
  

  5

Các khuyến nghị khác

• Tránh kéo theo khoảng trắng ở bất cứ đâu. Bởi vì nó thường vô hình, nó có thể gây nhầm lẫn: ví dụ: Một dấu gạch chéo ngược theo sau là một không gian và một dòng mới không được tính là điểm đánh dấu tiếp tục dòng. Một số biên tập viên don don bảo tồn nó và nhiều dự án (như chính Cpython) có các móc tiền trước từ chối nó.
• Luôn bao quanh các toán tử nhị phân này với một không gian duy nhất ở hai bên: gán (

  # Wrong:
  # operators sit far away from their operands
  income = (gross_wages +
            taxable_interest +
            (dividends - qualified_dividends) -
            ira_deduction -
            student_loan_interest)
  

  9), gán tăng cường (

  # Correct:
  # easy to match operators with operands
  income = (gross_wages
            + taxable_interest
            + (dividends - qualified_dividends)
            - ira_deduction
            - student_loan_interest)
  

  0,

  # Correct:
  # easy to match operators with operands
  income = (gross_wages
            + taxable_interest
            + (dividends - qualified_dividends)
            - ira_deduction
            - student_loan_interest)
  

  1, v.v.), so sánh (

  # Correct:
  # easy to match operators with operands
  income = (gross_wages
            + taxable_interest
            + (dividends - qualified_dividends)
            - ira_deduction
            - student_loan_interest)
  

  2,

  # Correct:
  # easy to match operators with operands
  income = (gross_wages
            + taxable_interest
            + (dividends - qualified_dividends)
            - ira_deduction
            - student_loan_interest)
  

  3,

  # Correct:
  # easy to match operators with operands
  income = (gross_wages
            + taxable_interest
            + (dividends - qualified_dividends)
            - ira_deduction
            - student_loan_interest)
  

  4,

  # Correct:
  # easy to match operators with operands
  income = (gross_wages
            + taxable_interest
            + (dividends - qualified_dividends)
            - ira_deduction
            - student_loan_interest)
  

  5

  # Correct:
  import os
  import sys
  

  2), Booleans (

  # Correct:
  import os
  import sys
  

  3,

  # Correct:
  import os
  import sys
  

  4,

  # Correct:
  import os
  import sys
  

  5).
• Nếu các nhà khai thác có các ưu tiên khác nhau được sử dụng, hãy xem xét thêm khoảng trắng xung quanh các nhà khai thác với mức độ ưu tiên thấp nhất (IES). Sử dụng phán đoán của riêng bạn; Tuy nhiên, không bao giờ sử dụng nhiều hơn một không gian và luôn có cùng một lượng khoảng trắng ở cả hai bên của toán tử nhị phân:

  # Hanging indents *may* be indented to other than 4 spaces.
  foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
  

  6

  # Hanging indents *may* be indented to other than 4 spaces.
  foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
  

  7

• Chú thích chức năng nên sử dụng các quy tắc thông thường cho các dấu chấm và luôn có khoảng trống xung quanh mũi tên

  # Correct:
  import os
  import sys
  

  6 nếu có. (Xem các chú thích chức năng bên dưới để biết thêm về chú thích chức năng.):

  # Hanging indents *may* be indented to other than 4 spaces.
  foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
  

  8

  # Hanging indents *may* be indented to other than 4 spaces.
  foo = long_function_name(
    var_one, var_two,
    var_three, var_four)
  

  9

• Don Tiết sử dụng các khoảng trống xung quanh dấu hiệu

  # Wrong:
  # operators sit far away from their operands
  income = (gross_wages +
            taxable_interest +
            (dividends - qualified_dividends) -
            ira_deduction -
            student_loan_interest)
  

  9 khi được sử dụng để chỉ ra đối số từ khóa hoặc khi được sử dụng để chỉ ra giá trị mặc định cho tham số hàm không được bảo vệ:

  # No extra indentation.
  if (this_is_one_thing and
      that_is_another_thing):
      do_something()
  
  # Add a comment, which will provide some distinction in editors
  # supporting syntax highlighting.
  if (this_is_one_thing and
      that_is_another_thing):
      # Since both conditions are true, we can frobnicate.
      do_something()
  
  # Add some extra indentation on the conditional continuation line.
  if (this_is_one_thing
          and that_is_another_thing):
      do_something()
  

  0

  # No extra indentation.
  if (this_is_one_thing and
      that_is_another_thing):
      do_something()
  
  # Add a comment, which will provide some distinction in editors
  # supporting syntax highlighting.
  if (this_is_one_thing and
      that_is_another_thing):
      # Since both conditions are true, we can frobnicate.
      do_something()
  
  # Add some extra indentation on the conditional continuation line.
  if (this_is_one_thing
          and that_is_another_thing):
      do_something()
  

  1

  Tuy nhiên, khi kết hợp chú thích đối số với giá trị mặc định, hãy sử dụng các khoảng trống xung quanh dấu hiệu

  # Wrong:
  # operators sit far away from their operands
  income = (gross_wages +
            taxable_interest +
            (dividends - qualified_dividends) -
            ira_deduction -
            student_loan_interest)
  

  9:

  # No extra indentation.
  if (this_is_one_thing and
      that_is_another_thing):
      do_something()
  
  # Add a comment, which will provide some distinction in editors
  # supporting syntax highlighting.
  if (this_is_one_thing and
      that_is_another_thing):
      # Since both conditions are true, we can frobnicate.
      do_something()
  
  # Add some extra indentation on the conditional continuation line.
  if (this_is_one_thing
          and that_is_another_thing):
      do_something()
  

  2

  # No extra indentation.
  if (this_is_one_thing and
      that_is_another_thing):
      do_something()
  
  # Add a comment, which will provide some distinction in editors
  # supporting syntax highlighting.
  if (this_is_one_thing and
      that_is_another_thing):
      # Since both conditions are true, we can frobnicate.
      do_something()
  
  # Add some extra indentation on the conditional continuation line.
  if (this_is_one_thing
          and that_is_another_thing):
      do_something()
  

  3

• Các câu lệnh ghép (nhiều câu lệnh trên cùng một dòng) thường không được khuyến khích:

  # No extra indentation.
  if (this_is_one_thing and
      that_is_another_thing):
      do_something()
  
  # Add a comment, which will provide some distinction in editors
  # supporting syntax highlighting.
  if (this_is_one_thing and
      that_is_another_thing):
      # Since both conditions are true, we can frobnicate.
      do_something()
  
  # Add some extra indentation on the conditional continuation line.
  if (this_is_one_thing
          and that_is_another_thing):
      do_something()
  

  4

  Thay vì không:

  # No extra indentation.
  if (this_is_one_thing and
      that_is_another_thing):
      do_something()
  
  # Add a comment, which will provide some distinction in editors
  # supporting syntax highlighting.
  if (this_is_one_thing and
      that_is_another_thing):
      # Since both conditions are true, we can frobnicate.
      do_something()
  
  # Add some extra indentation on the conditional continuation line.
  if (this_is_one_thing
          and that_is_another_thing):
      do_something()
  

  5

• Mặc dù đôi khi, nó có thể đặt một if/for/trong khi có một cơ thể nhỏ trên cùng một dòng, không bao giờ làm điều này cho các câu lệnh đa điểm. Cũng tránh gấp những dòng dài như vậy!

  Thay vì không:

  # No extra indentation.
  if (this_is_one_thing and
      that_is_another_thing):
      do_something()
  
  # Add a comment, which will provide some distinction in editors
  # supporting syntax highlighting.
  if (this_is_one_thing and
      that_is_another_thing):
      # Since both conditions are true, we can frobnicate.
      do_something()
  
  # Add some extra indentation on the conditional continuation line.
  if (this_is_one_thing
          and that_is_another_thing):
      do_something()
  

  6

  Mặc dù đôi khi, nó có thể đặt một if/for/trong khi có một cơ thể nhỏ trên cùng một dòng, không bao giờ làm điều này cho các câu lệnh đa điểm. Cũng tránh gấp những dòng dài như vậy!

  # No extra indentation.
  if (this_is_one_thing and
      that_is_another_thing):
      do_something()
  
  # Add a comment, which will provide some distinction in editors
  # supporting syntax highlighting.
  if (this_is_one_thing and
      that_is_another_thing):
      # Since both conditions are true, we can frobnicate.
      do_something()
  
  # Add some extra indentation on the conditional continuation line.
  if (this_is_one_thing
          and that_is_another_thing):
      do_something()
  

  7

Các quy ước đặt tên của thư viện Python, có một chút lộn xộn, vì vậy chúng tôi sẽ không bao giờ có được sự nhất quán hoàn toàn này - tuy nhiên, đây là các tiêu chuẩn đặt tên hiện đang được khuyến nghị. Các mô -đun và gói mới (bao gồm các khung của bên thứ ba) nên được ghi vào các tiêu chuẩn này, nhưng trong đó một thư viện hiện tại có một phong cách khác, tính nhất quán nội bộ được ưu tiên.

Nguyên tắc ghi đè

Các tên có thể nhìn thấy cho người dùng là các phần công khai của API nên tuân theo các quy ước phản ánh việc sử dụng thay vì thực hiện.

Mô tả: Kiểu đặt tên

Có rất nhiều phong cách đặt tên khác nhau. Nó giúp có thể nhận ra phong cách đặt tên đang được sử dụng, độc lập với những gì chúng được sử dụng.

• Các kiểu đặt tên sau đây thường được phân biệt:

• # Correct:
  import os
  import sys
  

  9 (chữ thường đơn)

• # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  01

• # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  02

• # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  03

• # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  04

• # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  00 (chữ hoa đơn)

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  05 (hoặc capwords, hoặc Camelcase - được đặt tên như vậy vì vẻ ngoài gập ghềnh của các chữ cái của nó [4]). Điều này đôi khi cũng được gọi là nghiên cứu.

• Lưu ý: Khi sử dụng các từ viết tắt trong Capwords, viết hoa tất cả các chữ cái của từ viết tắt. Do đó, httpservererror tốt hơn httpservererror.

• # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  06 (khác với chữ viết hoa bằng ký tự viết thường ban đầu!)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

Ngoài ra, còn có phong cách sử dụng một tiền tố ngắn độc đáo để nhóm liên quan đến nhóm lại với nhau. Điều này không được sử dụng nhiều trong Python, nhưng nó được đề cập để hoàn thiện. Ví dụ: hàm

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

Thư viện X11 sử dụng X hàng đầu cho tất cả các chức năng công cộng của nó. Trong Python, phong cách này thường được coi là không cần thiết bởi vì tên thuộc tính và phương thức được đặt trước với một đối tượng và tên hàm được đặt trước với một tên mô -đun.

• Ngoài ra, các hình thức đặc biệt sau đây sử dụng dấu gạch dưới hàng đầu hoặc dấu vết được công nhận (chúng thường có thể được kết hợp với bất kỳ quy ước nào):

• # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  12: Chỉ báo sử dụng nội bộ yếu. Ví dụ.

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  13 không nhập các đối tượng có tên bắt đầu bằng dấu gạch dưới.

  my_list = [
      1, 2, 3,
      4, 5, 6,
      ]
  result = some_function_that_takes_arguments(
      'a', 'b', 'c',
      'd', 'e', 'f',
      )
  

  2

• # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  14: Được sử dụng bởi quy ước để tránh xung đột với từ khóa Python, ví dụ:

• # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  15: Khi đặt tên cho một thuộc tính lớp, gọi tên Mangling (bên trong lớp foobar,

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  16 trở thành

  # Wrong:
  
  # Arguments on first line forbidden when not using vertical alignment.
  foo = long_function_name(var_one, var_two,
      var_three, var_four)
  
  # Further indentation required as indentation is not distinguishable.
  def long_function_name(
      var_one, var_two, var_three,
      var_four):
      print(var_one)
  

  17; xem bên dưới).

# Wrong: # Arguments on first line forbidden when not using vertical alignment. foo = long_function_name(var_one, var_two, var_three, var_four) # Further indentation required as indentation is not distinguishable. def long_function_name( var_one, var_two, var_three, var_four): print(var_one) 18: Các đối tượng hoặc thuộc tính của Magic Magic sống trong các không gian tên do người dùng điều khiển. Ví dụ. # Wrong: # Arguments on first line forbidden when not using vertical alignment. foo = long_function_name(var_one, var_two, var_three, var_four) # Further indentation required as indentation is not distinguishable. def long_function_name( var_one, var_two, var_three, var_four): print(var_one) 19, # Wrong: # Arguments on first line forbidden when not using vertical alignment. foo = long_function_name(var_one, var_two, var_three, var_four) # Further indentation required as indentation is not distinguishable. def long_function_name( var_one, var_two, var_three, var_four): print(var_one) 20 hoặc # Wrong: # Arguments on first line forbidden when not using vertical alignment. foo = long_function_name(var_one, var_two, var_three, var_four) # Further indentation required as indentation is not distinguishable. def long_function_name( var_one, var_two, var_three, var_four): print(var_one) 21. Không bao giờ phát minh ra những cái tên như vậy; Chỉ sử dụng chúng như tài liệu.

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

my_list = [
    1, 2, 3,
    4, 5, 6,
    ]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
    )

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

Giao diện công khai và nội bộ

Bất kỳ đảm bảo khả năng tương thích ngược chỉ áp dụng cho giao diện công cộng. Theo đó, điều quan trọng là người dùng có thể phân biệt rõ ràng giữa các giao diện công cộng và nội bộ.

Các giao diện được ghi nhận được coi là công khai, trừ khi tài liệu tuyên bố rõ ràng chúng là giao diện tạm thời hoặc nội bộ được miễn trừ khỏi các đảm bảo khả năng tương thích ngược thông thường. Tất cả các giao diện không có giấy tờ nên được coi là nội bộ.

Để hỗ trợ nội tâm tốt hơn, các mô -đun nên khai báo rõ ràng các tên trong API công khai của họ bằng thuộc tính

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

Ngay cả với

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

Một giao diện cũng được coi là nội bộ nếu bất kỳ không gian tên nào (gói, mô -đun hoặc lớp) được coi là nội bộ.

Tên nhập khẩu phải luôn được coi là một chi tiết thực hiện. Các mô -đun khác không được dựa vào quyền truy cập gián tiếp vào các tên đã nhập như vậy trừ khi chúng là một phần được ghi chép rõ ràng của API mô -đun có chứa API, chẳng hạn như

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

# Wrong:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

Chú thích chức năng

Với sự chấp nhận của PEP 484, các quy tắc phong cách cho các chú thích chức năng đã thay đổi.

• Chú thích chức năng nên sử dụng cú pháp PEP 484 (có một số đề xuất định dạng cho các chú thích trong phần trước).
• Thử nghiệm với các phong cách chú thích được khuyến nghị trước đây trong PEP này không còn được khuyến khích nữa.
• Tuy nhiên, bên ngoài stdlib, các thí nghiệm trong các quy tắc của PEP 484 hiện được khuyến khích. Ví dụ, đánh dấu một thư viện hoặc ứng dụng của bên thứ ba lớn với các chú thích kiểu kiểu PEP 484, xem xét mức độ dễ dàng để thêm các chú thích đó và quan sát xem sự hiện diện của chúng có tăng khả năng hiểu của mã hay không.
• Thư viện tiêu chuẩn Python phải bảo thủ trong việc áp dụng các chú thích như vậy, nhưng việc sử dụng chúng được cho phép cho mã mới và cho các chất tái cấu trúc lớn.
• Đối với mã muốn sử dụng các chú thích chức năng khác, nên đặt nhận xét của biểu mẫu:

  gần đầu tập tin; Điều này bảo kiểm tra loại để bỏ qua tất cả các chú thích. (Có thể tìm thấy nhiều cách khác để vô hiệu hóa khiếu nại từ người kiểm tra loại trong PEP 484.)

• Giống như linter, người kiểm tra loại là các công cụ riêng biệt, riêng biệt. Theo mặc định, các phiên dịch viên Python không nên phát hành bất kỳ tin nhắn nào do kiểm tra loại và không nên thay đổi hành vi của họ dựa trên các chú thích.
• Người dùng không muốn sử dụng người kiểm tra loại có thể tự do bỏ qua chúng. Tuy nhiên, người dùng của các gói thư viện bên thứ ba có thể muốn chạy trình kiểm tra loại qua các gói đó. Đối với mục đích này, PEP 484 khuyến nghị sử dụng các tệp sơ khai: Các tệp .pyi được đọc bởi Trình kiểm tra loại theo sở thích của các tệp .py tương ứng. Các tệp sơ khai có thể được phân phối với một thư viện hoặc riêng biệt (với quyền của tác giả thư viện) thông qua repo được đánh máy [5].

Chú thích biến

PEP 526 giới thiệu các chú thích thay đổi. Các đề xuất về kiểu cho chúng tương tự như các chú thích chức năng được mô tả ở trên:

• Chú thích cho các biến cấp mô -đun, các biến lớp và thể hiện và các biến cục bộ phải có một không gian duy nhất sau đại tràng.
• Không nên có không gian trước đại tràng.
• Nếu một nhiệm vụ có phía bên tay phải, thì dấu hiệu bình đẳng sẽ có chính xác một khoảng trống ở cả hai bên:

  with open('/path/to/some/file/you/want/to/read') as file_1, \
       open('/path/to/some/file/being/written', 'w') as file_2:
      file_2.write(file_1.read())
  

  4

  with open('/path/to/some/file/you/want/to/read') as file_1, \
       open('/path/to/some/file/being/written', 'w') as file_2:
      file_2.write(file_1.read())
  

  5

• Mặc dù PEP 526 được chấp nhận cho Python 3.6, cú pháp chú thích thay đổi là cú pháp ưa thích cho các tệp sơ khai trên tất cả các phiên bản của Python (xem PEP 484 để biết chi tiết).

Chú thích