缩进

每个缩进级别使用 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 个空格。本 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 的编辑器中换行，即使工具在换行时在最后一列放置了标记符号。一些基于网络的工具可能根本不提供动态换行。

有些团队强烈倾向于更长的行长。对于仅由一个团队维护或主要由一个团队维护的代码，如果团队能就此问题达成一致，可以将行长限制增加到 99 个字符，但注释和文档字符串仍应在 72 个字符处换行。

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

包装长行的首选方法是使用 Python 在括号、方括号和大括号内隐式行连续。长行可以通过将表达式包装在括号中来分解为多行。这应该优先于使用反斜杠进行行连续。

反斜杠有时仍然是合适的。例如，长的、多行的 with 语句在 Python 3.10 之前无法使用隐式连续，因此反斜杠在这种情况下是可以接受的

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 在他的《计算机与排版》系列中解释了传统规则：“尽管段落中的公式总是在二元运算和关系之后换行，但显示的公式总是在二元运算之前换行” [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 字符作为数据，请避免使用嘈杂的 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__ 导入之外的任何导入语句之前。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

个人偏好

在以下情况下避免多余的空白符

• 紧靠括号、方括号或大括号内

  # 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

文档字符串

编写良好文档字符串（也称为“docstring”）的约定已永久记录在 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() 函数返回一个元组，其项目传统上具有 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 中推荐的注解风格实验不再受到鼓励。
• 但是，在标准库之外，现在鼓励在 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）。

脚注