缩进

每个缩进级别使用 4 个空格。

延续行应通过 Python 在括号、方括号和花括号内的隐式行连接，或使用 *悬挂缩进* [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 语句的条件部分足够长，需要跨多行编写时，值得注意的是，2 个字符的关键字（即 if）、加上一个空格、加上一个左括号会为后续的 multiline 条件行创建自然的 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',
)

制表符还是空格？

空格是首选的缩进方法。

制表符应该只用于保持与已经使用制表符缩进的代码一致。

Python 禁止混合使用制表符和空格进行缩进。

最大行长

将所有行限制为最多 79 个字符。

对于结构限制较少的长文本块（文档字符串或注释）的流动，行长应限制为 72 个字符。

限制所需的编辑器窗口宽度可以让几个文件并排打开，并且在使用将两个版本显示在相邻列中的代码审查工具时效果很好。

大多数工具中的默认换行会破坏代码的视觉结构，从而难以理解。选择这些限制是为了避免在编辑器窗口宽度设置为 80 时换行，即使该工具在换行时会在最后一列放置一个标记符号。一些基于 Web 的工具可能根本不提供动态换行。

一些团队强烈偏好更长的行长。对于专门或主要由可以就这个问题达成一致的团队维护的代码，可以将行长限制增加到 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())

（请参阅之前关于 多行 if 语句 的讨论，以进一步了解此类多行 with 语句的缩进。）

另一个例子是 assert 语句。

确保正确缩进延续行。

二元运算符之前还是之后换行？

几十年来，推荐的风格是在二元运算符之后换行。但这会从两个方面影响可读性：运算符往往分散在屏幕的不同列中，并且每个运算符都被移离其操作数并转移到上一行。这里，眼睛需要做额外的工作来判断哪些项目被加了，哪些项目被减了

# Wrong:
# operators sit far away from their 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)

在 Python 代码中，可以在二元运算符之前或之后换行，只要约定在本地保持一致即可。对于新代码，建议使用克努斯风格。

空行

用两个空行包围顶层函数和类定义。

类内部的方法定义用一个空行包围。

可以使用额外的空行（适度地）来分隔相关函数组。在许多相关的单行代码（例如一组虚拟实现）之间可以省略空行。

在函数中适度地使用空行来指示逻辑部分。

Python 接受 control-L（即 ^L）换页符作为空格；许多工具将这些字符视为页面分隔符，因此你可以使用它们来分隔文件相关部分的页面。注意，某些编辑器和基于 Web 的代码查看器可能不识别 control-L 作为换页符，并会在其位置显示另一个符号。

源文件编码

核心 Python 发行版中的代码应该始终使用 UTF-8，并且不应该有编码声明。

在标准库中，非 UTF-8 编码只应用于测试目的。谨慎使用非 ASCII 字符，最好只用于表示地点和人名。如果使用非 ASCII 字符作为数据，请避免使用嘈杂的 Unicode 字符，如 z̯̯͡a̧͎̺l̡͓̫g̹̲o̡̼̘ 和字节顺序标记。

Python 标准库中的所有标识符都必须使用 ASCII 标识符，并且应该尽可能使用英文单词（在许多情况下，会使用非英文的缩写和专业术语）。

鼓励面向全球受众的开源项目采用类似的策略。

导入

• 导入通常应该在单独的行上

  # 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 实现，并且事先不知道将覆盖哪些确切定义）。

  以这种方式重新发布名称时，以下关于公共和内部接口的指南仍然适用。

模块级双下划线名称

模块级“双下划线”（即以两个前导下划线和两个尾随下划线开头的名称），例如 __all__、__author__、__version__ 等，应放在模块文档字符串之后，但在任何导入语句之前，除了 from __future__ 导入语句。

"""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

个人偏好

在以下情况下避免多余的空格

• 在括号、方括号或花括号的内部

  # 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
  

• 但是，在切片中，冒号充当二元运算符，两侧应具有相同数量的空格（将其视为优先级最低的运算符）。在扩展切片中，两个冒号必须应用相同的空格量。例外：当切片参数省略时，空格也会省略。

  # 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 本身）都有预提交钩子来拒绝它。
• 始终在以下二元运算符两侧使用单个空格：赋值（=）、增强赋值（+=、-= 等）、比较（==、<、>、!=、<>、<=、>=、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

文档字符串

编写良好文档字符串（又称“docstrings”）的约定在 PEP 257 中永垂不朽。

• 为所有公共模块、函数、类和方法编写文档字符串。非公共方法不需要文档字符串，但您应该有一个注释来描述该方法的功能。此注释应出现在 def 行之后。
• PEP 257 描述了良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的 """ 应位于单独的一行上。

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

• 对于单行文档字符串，请将结束的 """ 保持在同一行上。

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

首要原则

对用户可见的 API 公共部分的名称应遵循反映用法而不是实现的约定。

描述性：命名风格

有很多不同的命名风格。能够识别正在使用哪种命名风格是有帮助的，而这与它们的使用目的无关。

以下命名风格通常有所区分

• b（单个小写字母）
• B（单个大写字母）
• 小写
• 带下划线的_小写
• 大写
• 带下划线的_大写
• CapitalizedWords（或 CapWords 或 CamelCase——因此得名，因为它的字母看起来像驼峰 [4]）。这有时也被称为 StudlyCaps。

  注意：在 CapWords 中使用缩写时，将缩写的所有字母都大写。因此 HTTPServerError 比 HttpServerError 更好。

• mixedCase（与 CapitalizedWords 的区别在于第一个字符是小写！）
• Capitalized_Words_With_Underscores（难看！）

还有一种风格是使用简短的唯一前缀将相关的名称分组在一起。这在 Python 中使用不多，但为了完整性而提及。例如，os.stat() 函数返回一个元组，其项目传统上具有 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: 在命名类属性时，会触发名称混淆（在类 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)

公共和内部接口

任何向后兼容性保证仅适用于公开接口。因此，用户能够清楚地区分公开接口和内部接口非常重要。

已记录的接口被认为是公开的，除非文档明确声明它们是暂时的或内部接口，免除通常的向后兼容性保证。所有未记录的接口都应被视为内部接口。

为了更好地支持内省，模块应该使用 __all__ 属性明确声明其公开 API 中的名称。将 __all__ 设置为空列表表示该模块没有公开 API。

即使 __all__ 设置得当，内部接口（包、模块、类、函数、属性或其他名称）也应在前面加上一个前导下划线。

如果任何包含命名空间（包、模块或类）被视为内部命名空间，则接口也被视为内部接口。

导入的名称应始终被视为实现细节。其他模块不应依赖于对这些导入名称的间接访问，除非它们是包含模块 API 中明确记录的一部分，例如 os.path 或包的 __init__ 模块，该模块会公开来自子模块的功能。

函数注解

随着 PEP 484 的接受，函数注释的样式规则已更改。

• 函数注释应使用 PEP 484 语法（之前部分中有一些针对注释的格式建议）。
• 以前在此 PEP 中推荐的注释样式的实验不再鼓励。
• 但是，在 stdlib 之外，鼓励在 PEP 484 规则范围内进行实验。例如，使用 PEP 484 样式类型注释标记大型第三方库或应用程序，查看添加这些注释的难易程度，以及观察它们的存在是否提高了代码的可理解性。
• Python 标准库应谨慎采用这些注释，但允许在新代码和大型重构中使用它们。
• 对于希望对函数注释进行不同使用的代码，建议添加以下形式的注释

  # type: ignore
  

  在文件顶部附近；这告诉类型检查器忽略所有注释。（在 PEP 484 中可以找到更细粒度的禁用类型检查器抱怨的方法）。

• 与 linter 一样，类型检查器是可选的、独立的工具。Python 解释器默认情况下不应因类型检查而发出任何消息，也不应根据注释更改其行为。
• 不想使用类型检查器的用户可以自由地忽略它们。但是，预计第三方库包的用户可能希望对这些包运行类型检查器。为此，PEP 484 建议使用存根文件：.pyi 文件，类型检查器优先于相应的 .py 文件读取这些文件。存根文件可以与库一起分发，也可以单独分发（在库作者的许可下）通过 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 版本的存根文件的首选语法（有关详细信息，请参见 PEP 484）。

脚注