缩进

每个缩进级别使用 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 语句的条件部分长到需要跨行书写时，值得注意的是，两个字符的关键字（即 if ），加上一个空格，再加上一个开头的小括号，为多行条件的后续行创造了一个自然的 4 空格缩进。这可能会与嵌套在 if 语句中的缩进代码产生视觉冲突，这些代码也会自然缩进到 4 个空格。对于如何（或是否）进一步从视觉上区分这些条件行和 if 语句内的嵌套代码，本 PEP 没有采取明确的立场。这种情况下可接受的选项包括，但不限于

# 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 的编辑器中出现包装，即使工具在包装行时在最后一列放置一个标记字形。一些基于网络的工具可能根本就不提供动态换行。

有些团队强烈希望有一个较长的行。对于完全或主要由一个团队维护的代码，如果能在这个问题上达成一致，可以将行长限制增加到 99 个字符，但注释和文档字符串仍以 72 个字符包裹。

Python 标准库很保守，要求将行数限制在 79 个字符以内（文档串/注释为 72 个）。

包裹长行的首选方法是在小括号、大括号和大括号内使用 Python 的隐含续行功能。长行可以通过在小括号中包裹表达式而在多行中断开。应该优先使用这些小括号，而不是使用反斜杠进行续行。

Backslashes may still be appropriate at times. For example, long, multiple with-statements could not use implicit continuation before Python 3.10, so backslashes were acceptable for that case:

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)

为了解决这个可读性问题，数学家和他们的出版商遵循相反的惯例。Donald Knuth 在他的 计算机和排版 系列中解释了这一传统规则：“虽然一段内的公式总是在二进制运算和关系之后断开，但显示的公式总是在二进制运算之前断开” [3]。

遵循数学的传统，通常会产生更可读的代码

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

在 Python 代码中，允许在二进制运算符之前或之后断开，只要该约定在本地是一致的。对于新的代码，建议采用 Knuth 的风格。

空白行

用两行空行包围顶级函数和类的定义。

类内的方法定义被一个空行所包围。

可以使用额外的空行（少用）来分隔相关功能组。在一堆相关的单行字之间可以省略空行（例如，一组 dummy 的实现）。

在函数中少用空行，以表示逻辑部分。

Python accepts the control-L (i.e. ^L) form feed character as whitespace; many tools treat these characters as page separators, so you may use them to separate pages of related sections of your file. Note, some editors and web-based code viewers may not recognize control-L as a form feed and will show another glyph in its place.

源文件编码

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

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

Python 标准库中的所有标识符必须使用纯 ASCII 的标识符，并且在可行的情况下应该使用英文单词（在很多情况下，使用的缩写和技术术语都不是英文）。

鼓励拥有全球受众的开源项目采取类似的政策。

Imports

• 进口通常应在单独的行中进行

  # Correct:
  import os
  import sys
  

  # Wrong:
  import sys, os
  

  虽然这样说也没关系

  # Correct:
  from subprocess import Popen, PIPE
  

• import 总是放在文件的顶部，就在任何模块的注释和文档字符串说明之后，在模块全局和常量之前。

  import 应按以下顺序分组：

  1. 标准库导入。
  2. 相关的第三方导入。
  3. 本地应用程序/库的特定导入。

  你应该在每组 import 之间放一个空行。

• 推荐使用绝对导入，因为它们通常更具可读性，而且如果导入系统配置不正确（例如当包内的目录最终出现在 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 名称

模块级 的 “dunders”（即有两个前导和两个尾部下划线的名称），如 __all__，__author__，__version__，等等。应该放在模块文档串之后，但在任何导入语句之前，除了 from __future__ 导入。Python 规定，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

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
  

• 然而，在一个切片中，冒号的作用就像一个二元运算符，两边的数量应该相等（把它当作优先级最低的运算符）。在一个扩展的切片中，两个冒号都必须应用相同数量的间距。例外：当一个切片参数被省略时，空格被省略

  # 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 : : upper]
  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

文档字符串

Conventions for writing good documentation strings (a.k.a. “docstrings”) are immortalized in PEP 257.

• 为所有公共模块、函数、类和方法编写文档字符串。对于非公开的方法，不需要文档字符串，但你应该有一个注释来描述该方法的作用。这个注释应该出现在 def 行之后。
• PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself:

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

• 对于单行的文件串，请将结尾的 """ 放在同一行

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

覆盖原则

作为 API 的公共部分，对用户可见的名称应该遵循 reflect 用法而不是实现的惯例。

描述性的：命名方式

有很多不同的命名方式。能够认识到使用的是什么命名方式，与它们的用途无关，这很有帮助。

常用的命名方式有以下几种：

• 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() 函数返回一个元组，其项目传统上有 st_mode、st_size、st_mtime 等名称。（这样做是为了强调与 POSIX 系统调用结构的字段的对应关系，这有助于熟悉该结构的程序员。）

X11 库在其所有的公共函数中使用前导 X。在 Python 中，这种风格通常被认为是不必要的，因为属性和方法名的前缀是一个对象，而函数名的前缀是一个模块名。

此外，还承认以下使用前导或尾部下划线的特殊形式（这些通常可以与任何大小写惯例相结合）：

• _single_leading_underscore：weak “内部使用” 指标。例如，from M import * 不会导入名称以下划线开头的对象。
• single_trailing_underscore_：按惯例使用，以避免与 Python 关键字冲突，例如

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

• __double_leading_underscore：当命名一个类的属性时，会调用名称混用（在类 FooBar 中，__boo 变成 _FooBar__boo；见下文）。
• __double_leading_and_trailing_underscore__：实时在用户控制的命名空间中的 “magic” 对象或属性。例如：__init__，__import__ 或 __file__。不要发明这样的名字；只使用文件规定的名字。

规范性的：命名规则

from typing import TypeVar

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

公共和内部接口

任何向后兼容的保证只适用于公共接口。因此，重要的是，用户要能够明确区分公共接口和内部接口。

文档化的接口被认为是公开的，除非文档明确声明它们是临时的或内部的接口，免于通常的向后兼容性保证。所有没有记录的接口应该被认为是内部的。

为了更好地支持自省，模块应该在它们的公共 API 中使用 __all__ 属性明确地声明名称。将 __all__ 设置为一个空列表，表示该模块没有公共 API。

即使适当地设置了 __all__，内部接口（包、模块、类、函数、属性或其他名称）仍应在前缀中加入一个单引号。

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

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

函数注解

With the acceptance of PEP 484, the style rules for function annotations have changed.

• Function annotations should use PEP 484 syntax (there are some formatting recommendations for annotations in the previous section).
• 不再鼓励以前在本 PEP 中推荐的注解样式的实验。
• However, outside the stdlib, experiments within the rules of PEP 484 are now encouraged. For example, marking up a large third party library or application with PEP 484 style type annotations, reviewing how easy it was to add those annotations, and observing whether their presence increases code understandability.
• Python 标准库在采用这种注解时应该是保守的，但对于新的代码和大的重构来说，允许使用它们。
• 对于想要对函数注解进行不同使用的代码，建议放一个形式为

  # type: ignore
  

  near the top of the file; this tells type checkers to ignore all annotations. (More fine-grained ways of disabling complaints from type checkers can be found in PEP 484.)

• 就像 linter 一样，类型检查器是可选的、独立的工具。默认情况下，Python 解释器不应该因为类型检查而发出任何消息，也不应该根据注解来改变它们的行为。
• Users who don’t want to use type checkers are free to ignore them. However, it is expected that users of third party library packages may want to run type checkers over those packages. For this purpose PEP 484 recommends the use of stub files: .pyi files that are read by the type checker in preference of the corresponding .py files. Stub files can be distributed with a library, or separately (with the library author’s permission) through the typeshed repo [5].

变量注解

PEP 526 introduced variable annotations. The style recommendations for them are similar to those on function annotations described above:

• 模块级变量、类和实例变量以及局部变量的注释应该在冒号后面有一个空格。
• 冒号前不应该有空格。
• 如果一个赋值有一个右侧，那么等号符号两边应该正好有一个空格

  # 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
  

• Although the PEP 526 is accepted for Python 3.6, the variable annotation syntax is the preferred syntax for stub files on all versions of Python (see PEP 484 for details).

脚注