縮排

每個縮排層級使用 4 個空白鍵。

續行應該透過以下方式對齊包裹的元素：垂直對齊（使用 Python 在括號、方括號和大括號內的隱式換行），或者使用懸掛縮排 (hanging indent) [1]。當使用懸掛縮排時，應考慮以下幾點：第一行不應包含參數，並且應使用額外的縮排來清楚地標識為續行。

# 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)

對於續行，4 個空白鍵的規則是選擇性的。

選擇性

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

當 if 語句的條件部分太長，需要跨多行書寫時，值得注意的是：兩個字元的關鍵字（即 if）加上一個空格，再加上一個左括號，會自然地為後續的多行條件行產生 4 個空白鍵的縮排。這可能會與 if 語句內部的巢狀程式碼區塊產生視覺衝突，因為後者也會自然地縮排 4 個空白鍵。本 PEP 對於如何（或是否）進一步在視覺上區分此類條件行與 if 語句內部的巢狀程式碼區塊，不採取明確立場。在此情況下，可接受的選項包括但不限於：

# 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()

（也請參閱下方關於在二元運算子之前還是之後換行的討論。）

多行結構的結尾大括號/方括號/括號可以對齊在清單最後一行的第一個非空白字元之下，如：

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

或者，它也可以對齊在開始多行結構的該行第一個字元之下，如：

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

Tab 還是空白鍵？

空白鍵是首選的縮排方式。

只有為了與已經使用 Tab 縮排的程式碼保持一致時，才應使用 Tab。

Python 禁止在縮排中混用 Tab 和空白鍵。

最大行長度

限制所有行最大為 79 個字元。

對於結構限制較少的長文本區塊（文件字串或註解），行長應限制為 72 個字元。

限制編輯器視窗所需的寬度，可以讓多個檔案並排開啟，這在程式碼審查工具將兩個版本顯示在相鄰欄位時非常有效。

大多數工具的預設自動換行會破壞程式碼的視覺結構，使理解變得困難。設定這些限制是為了避免在視窗寬度設為 80 的編輯器中換行，即使工具在換行時於最後一欄放置標記字元也是如此。某些網頁工具可能根本不提供動態換行。

有些團隊強烈偏好更長的行長。對於由能就此問題達成共識的團隊獨家或主要維護的程式碼，可以將行長限制增加到 99 個字元，前提是註解和文件字串仍維持在 72 個字元換行。

Python 標準函式庫比較保守，要求將行限制為 79 個字元（文件字串/註解為 72 個字元）。

換行長行的首選方式是使用 Python 在括號、方括號和大括號內的隱式換行。長行可以透過將運算式包裹在括號中來拆分為多行。這些方式應優先於使用反斜線進行續行。

反斜線有時仍然適用。例如，在 Python 3.10 之前，長的、多個 with 語句無法使用隱式續行，因此在該情況下反斜線是可以接受的。

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())

（關於此類多行 with 語句的縮排，請參閱先前關於 多行 if 語句 的討論。）

另一個案例是 assert 語句。

請務必適當地縮排續行。

換行應該在二元運算子之前還是之後？

幾十年來，推薦的風格是在二元運算子之後換行。但這會在兩個方面損害可讀性：運算子傾向於分散在螢幕的不同欄位，且每個運算子都與其運算元分離並移動到上一行。在這裡，眼睛必須多費力才能分辨哪些項目是相加的，哪些是相減的：

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

為了解決這個可讀性問題，數學家及其出版商遵循相反的慣例。Donald Knuth 在他的《電腦與排版》(Computers and Typesetting) 系列中解釋了傳統規則：「雖然段落內的公式總是在二元運算和關係之後換行，但顯示的公式總是在二元運算之前換行」[3]。

遵循數學傳統通常會產生更具可讀性的程式碼：

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

在 Python 程式碼中，允許在二元運算子之前或之後換行，只要在局部保持慣例一致即可。對於新程式碼，建議使用 Knuth 的風格。

空白行

在頂層函式和類別定義前後各留兩行空白。

類別內的方法定義前後留一行空白。

額外的空白行可以（節制地）用於分隔相關函式群組。在一堆相關的單行程式碼（例如一組模擬實作）之間可以省略空白行。

在函式中使用空白行時應有所節制，用以標示邏輯區段。

Python 接受 control-L（即 ^L）換頁字元作為空白；許多工具將這些字元視為頁面分隔符，因此您可以使用它們來分隔檔案中相關區段的頁面。請注意，某些編輯器和網頁程式碼檢視器可能無法識別 control-L 為換頁符，並會在該處顯示其他符號。

原始碼檔案編碼

核心 Python 發行版中的程式碼應始終使用 UTF-8，且不應包含編碼宣告。

在標準函式庫中，非 UTF-8 編碼應僅用於測試目的。節制使用非 ASCII 字元，最好僅用於標示地點和人名。若將非 ASCII 字元用作資料，請避免使用如 z̯̯͡a̧͎̺l̡͓̫g̹̲o̡̼̘ 之類的雜亂 Unicode 字元及位元組順序標記 (BOM)。

Python 標準函式庫中的所有識別字都「必須」僅使用 ASCII，並且在可行的地方「應該」使用英文單字（在許多情況下，會使用非英文的縮寫和技術術語）。

鼓勵擁有全球受眾的開源專案採取類似的政策。

匯入 (Imports)

• 匯入語句通常應分行書寫：

  # Correct:
  import os
  import sys
  

  # Wrong:
  import sys, os
  

  不過這樣寫也是可以的：

  # Correct:
  from subprocess import Popen, PIPE
  

• 匯入語句應始終放在檔案頂部，就在任何模組註解和文件字串之後，在模組全域變數和常數之前。

  匯入語句應依以下順序分組：

  1. 標準函式庫匯入。
  2. 相關的第三方匯入。
  3. 本地應用程式/函式庫特定匯入。

  您應該在每組匯入語句之間放置一個空白行。

• 建議使用絕對匯入，因為它們通常更具可讀性，且如果匯入系統配置不當（例如當套件內的目錄最終出現在 sys.path 中時），它們的行為往往更好（或者至少能提供更好的錯誤訊息）。

  import mypkg.sibling
  from mypkg import sibling
  from mypkg.sibling import example
  

  然而，明確的相對匯入是絕對匯入的可接受替代方案，特別是在處理複雜的套件佈局時，因為在這種情況下使用絕對匯入會顯得過於冗長。

  from . import sibling
  from .sibling import example
  

  標準函式庫程式碼應避免複雜的套件佈局，並始終使用絕對匯入。

• 當從包含類別的模組中匯入類別時，通常可以這樣寫：

  from myclass import MyClass
  from foo.bar.yourclass import YourClass
  

  如果這種寫法導致本地名稱衝突，則應明確寫出：

  import myclass
  import foo.bar.yourclass
  

  並使用 myclass.MyClass 和 foo.bar.yourclass.YourClass。

• 應避免使用萬用字元匯入（from <module> import *），因為這會導致命名空間中的名稱不明確，讓讀者和許多自動化工具感到困惑。萬用字元匯入有一種可辯護的用途，即將內部介面重新發佈為公開 API 的一部分（例如，用可選加速器模組的定義覆寫介面的純 Python 實作，且無法事先知道會覆寫哪些定義）。

  以這種方式重新發佈名稱時，下方關於公開與內部介面的指南仍然適用。

模組層級的雙底線名稱 (Dunder Names)

模組層級的「雙底線名稱」（即前後各兩個底線的名稱），如 __all__、__author__、__version__ 等，應放置在模組文件字串之後，但在任何匯入語句「之前」（from __future__ 匯入除外）。Python 規定 future-imports 必須出現在模組中除文件字串之外的任何其他程式碼之前。

"""This is the example module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import os
import sys

常見厭惡點 (Pet Peeves)

避免在以下情況中使用多餘的空白：

• 括號、方括號或大括號內部緊鄰處。

  # Correct:
  spam(ham[1], {eggs: 2})
  

  # Wrong:
  spam( ham[ 1 ], { eggs: 2 } )
  

• 尾隨逗號與後面的右括號之間。

  # Correct:
  foo = (0,)
  

  # Wrong:
  bar = (0, )
  

• 逗號、分號或冒號之前緊鄰處。

  # Correct:
  if x == 4: print(x, y); x, y = y, x
  

  # Wrong:
  if x == 4 : print(x , y) ; x , y = y , x
  

• 然而，在切片 (slice) 中，冒號的作用類似於二元運算子，兩側應有等量的空白（將其視為優先級最低的運算子）。在擴充切片中，兩個冒號必須應用相同的空白間距。例外：當省略切片參數時，空格也隨之省略。

  # Correct:
  ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
  ham[lower:upper], ham[lower:upper:], ham[lower::step]
  ham[lower+offset : upper+offset]
  ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
  ham[lower + offset : upper + offset]
  

  # Wrong:
  ham[lower + offset:upper + offset]
  ham[1: 9], ham[1 :9], ham[1:9 :3]
  ham[lower : : step]
  ham[ : upper]
  

• 函式呼叫的參數列表開頭的左括號前緊鄰處。

  # Correct:
  spam(1)
  

  # Wrong:
  spam (1)
  

• 索引或切片開頭的左括號前緊鄰處。

  # Correct:
  dct['key'] = lst[index]
  

  # Wrong:
  dct ['key'] = lst [index]
  

• 在指派（或其他）運算子周圍使用超過一個空格，以便與另一個對齊。

  # Correct:
  x = 1
  y = 2
  long_variable = 3
  

  # Wrong:
  x             = 1
  y             = 2
  long_variable = 3
  

其他建議

• 避免在任何地方出現尾隨空白。因為它通常是不可見的，這可能會造成混淆：例如，反斜線後接空格和換行符，並不視為續行標記。有些編輯器不會保留它，且許多專案（如 CPython 本身）都有 rejection 尾隨空白的 commit 前鉤子 (pre-commit hooks)。
• 始終在這些二元運算子兩側各使用一個空格：指派 (=)、增量指派 (+=, -= 等)、比較 (==, <, >, !=, <=, >=, in, not in, is, is not)、布林運算 (and, or, not)。
• 如果使用了不同優先級的運算子，請考慮在優先級最低的運算子周圍添加空白。請自行判斷；但是，絕對不要使用超過一個空格，且二元運算子兩側的空白量務必相同。

  # Correct:
  i = i + 1
  submitted += 1
  x = x*2 - 1
  hypot2 = x*x + y*y
  c = (a+b) * (a-b)
  

  # Wrong:
  i=i+1
  submitted +=1
  x = x * 2 - 1
  hypot2 = x * x + y * y
  c = (a + b) * (a - b)
  

• 函式註解應遵循冒號的正常規則，如果存在 -> 箭頭，箭頭兩側應始終有空格。（關於函式註解的更多資訊，請參閱下方的 函式註解。）

  # Correct:
  def munge(input: AnyStr): ...
  def munge() -> PosInt: ...
  

  # Wrong:
  def munge(input:AnyStr): ...
  def munge()->PosInt: ...
  

• 當 = 符號用於表示關鍵字參數，或用於表示「未註解」的函式參數的預設值時，不要在周圍使用空格。

  # Correct:
  def complex(real, imag=0.0):
      return magic(r=real, i=imag)
  

  # Wrong:
  def complex(real, imag = 0.0):
      return magic(r = real, i = imag)
  

  然而，當將參數註解與預設值結合使用時，確實要在 = 符號周圍使用空格。

  # Correct:
  def munge(sep: AnyStr = None): ...
  def munge(input: AnyStr, sep: AnyStr = None, limit=1000): ...
  

  # Wrong:
  def munge(input: AnyStr=None): ...
  def munge(input: AnyStr, limit = 1000): ...
  

• 通常不鼓勵使用複合語句（即同一行有多個語句）。

  # Correct:
  if foo == 'blah':
      do_blah_thing()
  do_one()
  do_two()
  do_three()
  

  最好不要這樣：

  # Wrong:
  if foo == 'blah': do_blah_thing()
  do_one(); do_two(); do_three()
  

• 雖然有時將 if/for/while 語句與簡短的本體放在同一行是可以的，但千萬不要對多子句語句這樣做。也要避免摺疊此類長行！

  最好不要這樣：

  # Wrong:
  if foo == 'blah': do_blah_thing()
  for x in lst: total += x
  while t < 10: t = delay()
  

  絕對不要這樣：

  # Wrong:
  if foo == 'blah': do_blah_thing()
  else: do_non_blah_thing()
  
  try: something()
  finally: cleanup()
  
  do_one(); do_two(); do_three(long, argument,
                               list, like, this)
  
  if foo == 'blah': one(); two(); three()
  

區塊註解

區塊註解通常適用於其後的某些（或全部）程式碼，並與該程式碼縮排在同一層級。區塊註解的每一行都以 # 和一個空格開始（註解內部的縮排文字除外）。

區塊註解內部的段落由包含單個 # 的行分隔。

行內註解

請節制使用行內註解。

行內註解是與語句在同一行的註解。行內註解與語句之間至少應分隔兩個空格。它們應以 # 和一個空格開始。

如果行內註解只是陳述顯而易見的事實，那麼它們是不必要的，甚至是干擾。不要這樣做：

x = x + 1                 # Increment x

但有時，這樣做很有用：

x = x + 1                 # Compensate for border

文件字串 (Documentation Strings)

撰寫良好文件字串（又稱「docstrings」）的慣例已在 PEP 257 中永久記錄。

• 為所有公開的模組、函式、類別和方法撰寫文件字串。非公開方法不需要文件字串，但您應該有一條描述該方法功能的註解。此註解應出現在 def 行之後。
• PEP 257 描述了良好的文件字串慣例。請注意，最重要的是，結束多行文件字串的 """ 應該單獨佔據一行：

  """Return a foobang
  
  Optional plotz says to frobnicate the bizbaz first.
  """
  

• 對於單行文件字串，請將結尾的 """ 保持在同一行。

  """Return an ex-parrot."""
  

核心原則

作為 API 公開部分對使用者可見的名稱，應遵循反映用途而非實作的慣例。

描述性：命名風格

有很多不同的命名風格。能夠識別正在使用什麼命名風格，獨立於它們的用途，會很有幫助。

以下命名風格通常被區分出來：

• b（單個小寫字母）
• B（單個大寫字母）
• lowercase (全小寫)
• lower_case_with_underscores (底線分隔小寫)
• UPPERCASE (全大寫)
• UPPER_CASE_WITH_UNDERSCORES (底線分隔大寫)
• CapitalizedWords（或 CapWords，或 CamelCase —— 因其字母的起伏外觀而得名 [4]）。這有時也被稱為 StudlyCaps。

  注意：在 CapWords 中使用縮寫時，請將縮寫的所有字母大寫。因此，HTTPServerError 比 HttpServerError 更好。

• mixedCase（與 CapitalizedWords 的區別在於首字母小寫！）
• Capitalized_Words_With_Underscores（很醜！）

還有一種使用短唯一字首將相關名稱組合在一起的風格。這在 Python 中使用不多，但為了完整性在此提及。例如，os.stat() 函式回傳一個 tuple，其項目傳統上具有如 st_mode, st_size, st_mtime 等名稱。（這樣做是為了強調與 POSIX 系統呼叫結構欄位的對應關係，這對熟悉該結構的程式設計師很有幫助。）

X11 函式庫對其所有公開函式使用字首 X。在 Python 中，這種風格通常被認為是不必要的，因為屬性和方法名稱已有物件做為字首，而函式名稱已有模組名稱做為字首。

此外，以下使用前導或尾隨底線的特殊形式是公認的（這些通常可以與任何大小寫慣例結合）：

• _single_leading_underscore：弱「內部使用」指標。例如，from M import * 不會匯入名稱以底線開頭的物件。
• single_trailing_underscore_：按慣例用於避免與 Python 關鍵字衝突，例如：

  tkinter.Toplevel(master, class_='ClassName')
  

• __double_leading_underscore：命名類別屬性時，觸發名稱改寫 (name mangling)（在類別 FooBar 內部，__boo 變為 _FooBar__boo；見下文）。
• __double_leading_and_trailing_underscore__：「魔法」物件或屬性，存在於使用者控制的命名空間中。例如 __init__, __import__ 或 __file__。切勿發明此類名稱；僅按文件說明使用它們。

規範性：命名慣例

from typing import TypeVar

VT_co = TypeVar('VT_co', covariant=True)
KT_contra = TypeVar('KT_contra', contravariant=True)

公開與內部介面

任何向後相容性保證僅適用於公開介面。因此，使用者能夠清楚區分公開介面和內部介面非常重要。

有文件的介面被視為公開的，除非文件中明確宣告它們為暫時性或不受通常向後相容性保證約束的內部介面。所有未記錄的介面都應被視為內部介面。

為了更好地支援內省 (introspection)，模組應使用 __all__ 屬性明確宣告其公開 API 中的名稱。將 __all__ 設定為空列表表示該模組沒有公開 API。

即使正確設定了 __all__，內部介面（套件、模組、類別、函式、屬性或其他名稱）仍應加上一個前導底線。

如果任何包含的命名空間（套件、模組或類別）被視為內部介面，那麼該介面也被視為內部介面。

匯入的名稱應始終被視為實作細節。其他模組不得依賴對此類匯入名稱的間接存取，除非它們是包含模組 API 中明確記錄的部分，例如 os.path 或公開子模組功能的套件 __init__ 模組。

函數標註 (Function Annotations)

隨著 PEP 484 的採納，函式註解的風格規則已經改變。

• 函式註解應使用 PEP 484 語法（上一節中有一些關於註解的格式化建議）。
• 本 PEP 先前建議的對註解風格的實驗已不再受鼓勵。
• 然而，在 stdlib 之外，現在鼓勵在 PEP 484 的規則內進行實驗。例如，使用 PEP 484 風格的型別註解標記大型第三方函式庫或應用程式，審查加入這些註解的難易程度，並觀察它們的存在是否增加了程式碼的可理解性。
• Python 標準函式庫在採用此類註解時應持保守態度，但允許在新程式碼和大型重構中使用它們。
• 對於希望對函式註解有不同用途的程式碼，建議在檔案頂部附近加上以下格式的註解：

  # type: ignore
  

  這會告知型別檢查器忽略所有註解。（更多停用型別檢查器投訴的精細方法可在 PEP 484 中找到。）

• 與 linter 一樣，型別檢查器是選擇性的、單獨的工具。Python 直譯器預設不應因型別檢查而發出任何訊息，也不應根據註解改變其行為。
• 不想使用型別檢查器的使用者可以自由忽略它們。然而，第三方函式庫套件的使用者預期可能會想要在這些套件上執行型別檢查器。為此，PEP 484 建議使用 stub 檔案：.pyi 檔案，型別檢查器會優先讀取這些檔案而非對應的 .py 檔案。Stub 檔案可以與函式庫一起散佈，或單獨（經函式庫作者許可）透過 typeshed 儲存庫散佈 [5]。

變數註解

PEP 526 引入了變數註解。它們的風格建議與上述函式註解類似：

• 模組層級變數、類別變數和實例變數，以及局部變數的註解，冒號後應有一個空格。
• 冒號前不應有空格。
• 如果指派語句有右側部分，則等號兩側應各有一個空格：

  # Correct:
  
  code: int
  
  class Point:
      coords: Tuple[int, int]
      label: str = '<unknown>'
  

  # Wrong:
  
  code:int  # No space after colon
  code : int  # Space before colon
  
  class Test:
      result: int=0  # No spaces around equality sign
  

• 雖然 PEP 526 已被 Python 3.6 採納，但變數註解語法是所有 Python 版本中 stub 檔案的首選語法（詳細資訊請參閱 PEP 484）。

附註