PEP8 -- Python代码样式指南（中文版）
PEP8 – Python代码样式指南（中文版）
1. Introduction
本文档给出了包含主要Python发行版中的标准库的Python代码的编码约定。请参阅Python[1]的C实现中C代码的伴随信息PEP描述样式指南。
本文和PEP 257 (Docstring约定)是从Guido的原始Python风格指南文章改编而来的，还有一些来自Barry的风格指南[2]。
随着时间的推移，随着更多的约定被识别，过去的约定被语言本身的变化所淘汰，这种风格指南也在不断发展。
2. Code Lay-out
2.1 Indentation
每个缩进需要使用4个空格。
延续行应该使用Python的隐式行在括号、括号和大括号内进行垂直对齐，或者使用悬挂缩进[7]。使用悬挂缩进时，应考虑以下因素：第一行不应该有任何参数，进一步的缩进应该被用来清楚地区分自己作为一个延续行。
Yes:
# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
var_three, var_four)
# More indentation included to distinguish this 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)
No:
# 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个空格的规则是可选使用的。
Optional:
# Hanging indents *may* be indented to other than 4 spaces.
foo = long_function_name(
var_one, var_two,
var_three, var_four
当条件一个 if 语句的一部分足够长要求编写跨多个行,值得注意的是,两个字符的组合关键字(即如果),加上一个空格,加上开括号创建一个自然4空间缩进的后续行多行条件。这可能会与嵌套在 if-语句 中的缩进代码集产生视觉冲突，后者也会自然缩进到 4 个空格中。对于如何(或是否)进一步在视觉上区分这些条件行和 ne 没有明确的立场。
# 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',
)
2.2 Tabs or Spaces?
空格是首选的缩进方法。
Tabs应该仅用于与已经用tabs缩进的代码保持一致。
Python 3不允许混合使用制表符和空格来缩进。
python 2使用tabs和空格的组合缩进方式应该转换为专门使用空格缩进。
2.3 Maximum Line Length
将所有行限制为最多79个字符。
对于具有较少结构限制的长文本块(文档字符串或注释)，行长度应该限制为72个字符。
限制所需的编辑器窗口宽度可以让多个文件并排打开，并且在使用在相邻列中显示两个版本的代码审查工具时工作得很好。
大多数工具中的默认包装破坏了代码的视觉结构，使其更难理解。选择这些限制是为了避免在窗口宽度设置为80的编辑器中换行，即使工具在换行时在最后一列中放置了标记符号。一些基于web的工具可能根本不提供动态换行。
有些队强烈喜欢较长的线路长度。对于专门或主要由一个团队维护的、能够就这个问题达成一致的代码，可以将标称行长度从80个字符增加到100个字符(有效地将最大长度增加到99个字符)，只要注释和文档字符串仍然包装在72个字符。
Python标准库是保守的，要求限制行为79个字符(文档字符串/注释为72个)。
最好的换行方式是在括号、括号和大括号中使用Python的隐含的行延续。通过在括号中包装表达式，可以在多行中打断长行。与使用反斜杠进行行延续相比，应该优先使用它们。
反斜杠有时仍然是合适的。例如，长而多的with-statement不能使用隐式延续，因此可以接受反斜杠
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-statements的讨论，以进一步了解此类多行if-statements的缩进。)
另一种情况是断言语句。
确保适当缩进连续行。
2.4 Should a Line Break Before or After a Binary Operator?
几十年来，推荐的样式是在二进制运算符之后换行。但这可能在两方面破坏代码的可读性:操作符往往分散在屏幕上的不同列上，每个操作符都在其操作数的上一行。因此，眼睛必须分辨哪些操作数被加，哪些被减：
# No: operators sit far away from their operands
income = (gross_wages +
taxable_interest +
(dividends - qualified_dividends) -
ira_deduction -
student_loan_interest)
为了解决这个可读性问题，数学家和他们的出版商遵循了相反的惯例。Donald Knuth解释了他的计算机和排版系列中的传统规则:“虽然一个段落中的公式总是在二进制操作和关系之后换行，但是显示的公式总是在二进制操作之前进行换行”[3]
遵循数学的传统，通常会产生更易读的代码：
# Yes: easy to match operators with operands
income = (gross_wages
+ taxable_interest
+ (dividends - qualified_dividends)
- ira_deduction
- student_loan_interest)
在Python代码中，允许在二进制操作符之前或之后换行，只要约定在本地是一致的。
2.5 Blank Lines
用两个空行包围顶级函数和类定义。
类中定义的方法（函数）通过一个空行隔开。
可以(少量地)使用额外的空行来隔开相关函数组。在一组相关的一行程序(例如一组虚拟实现)之间可以省略空行。
在函数中尽量使用空行来指明逻辑部分。
Python接受control-L(例如^ L)换页空白字符;许多工具将这些字符视为页面分隔符，因此您可以使用它们来分隔文件中相关部分的页面。注意，一些编辑器和基于web的代码查看器可能不会将control-L识别为表单提要，而会在其位置显示另一个符号。
2.6 Source File Encoding
核心Python发行版中的代码应该始终使用UTF-8(或Python 2中的ASCII)格式。
使用ASCII(在Python 2中)或UTF-8(在Python 3中)的文件不应该有编码声明。
在标准库中，非默认编码只能用于测试目的，或者当注释或文档字符串需要提到包含非ascii字符的作者名时。否则，使用\x、\u、\u或\N转义是在字符串文本中包含非ascii数据的首选方法。
对于Python 3.0及以上版本，标准库规定了以下策略(请参阅PEP 3131)： Python标准库中的所有标识符必须仅使用ascii标识符，并且应该在可行的情况下使用英语单词(在许多情况下，使用的是非英语的缩写词和技术术语)。此外，字符串文字和注释也必须是ASCII格式的。唯一的例外是：(a) 测试用例测试非ascii特性，(b) 作者的名字。不以拉丁字母(Latin alphabet -1, ISO/IEC 8859-1字符集)为基础的作者必须在这个字符集中提供他们名字的音译。
鼓励具有全球受众的开源项目采用类似的策略。
2.7 Imports
导入操作通常按行分开，例：
Yes: import os
import sys
No: import sys, os
不过也可以这样操作：
from subprocess import Popen, PIPE
import 操作总是放在文件的顶部，在任何模块注释文档之后，在模块全局和常量之前进行。
import 操作应按以下顺序进行:
import标准库import相关第三方库import本地自建库
且不同类型的库以空行分割。
建议绝对导入，因为它们通常更易于阅读，并且在导入路径错误时，表现的更友好(至少能给出更友好的错误消息)：
import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example
但是，相对于绝对导入，显式的相对导入也是一种可接受的替代方法，特别是在处理复杂的包布局时，使用绝对导入会不不可避免的冗长，例如：
from . import sibling
from .sibling import example
一个标准的库代码应该避免复杂的包布局，并始终使用绝对导入。
在python3中，隐式的相对导入操作不能被使用并且已被删除。
从类包模块中import 一个类时，通常可以这样操作：
from myclass import MyClass
from foo.bar.yourclass import YourClass
:如果这个 import 方法与本地名有冲突，那么就用下面显示的 import 方法：
import myclass
import foo.bar.yourclass
并使用 "myclass.MyClass" 和 "foo.bar.yourclass.YourClass" 操作需要的类。
应该避免通配符导入操作(from )，因为它们容易混淆哪些变量名是导入的，哪些是命名空间中出现的。
有一个站得住脚的通配符导入用例,这是重新发布的公共API的一个内部接口(例如，使用可选的accelerator模块中的定义重写接口的纯Python实现，以及哪些定义将被重写，这些都是事先不知道的)。当以这种方式重新发布名称时，关于公共和内部接口的准则仍然适用。
2.8 Module level dunder names
模块级"dunders"(即名称前后各有两个下划线)，如__all__、__author__、__version__等，应在模块注释之后且任何导模块语句之前写入，除了 from __future__ 。
Python要求__future__ 的 import 操作必须优先于除了模块注释之外的其他任何操作。例如：
"""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
3. String Quotes
在Python中，单引号字符串和双引号字符串是相同的。PEP8不会对此提出建议。选择一个规则并坚持它。然而，当字符串里包含单引号或双引号字符时，使用另一个字符来避免字符串中的反斜杠。它提高了可读性（不太理解）。
对于三引号字符串，始终使用双引号字符以符合PEP 257中的docstring约定。
4. Whitespace in Expressions and Statements
4.1 Pet Peeves
在以下情况下避免使用多余的空格：
在括号，括号或大括号内
Yes: spam(ham[1], {eggs: 2})
No: spam( ham[ 1 ], { eggs: 2 } )
在括号内的逗号后面和逗号后面的右括号之间
Yes: foo = (0,)
No: bar = (0, )
紧跟在逗号、分号或冒号之前：
Yes: if x == 4: print x, y; x, y = y, x
No: if x == 4 : print x , y ; x , y = y , x
然而，在一个切片中，冒号就像一个二进制操作符，并且两边的数量应该相等(把它当作优先级最低的操作符对待)。在扩展切片中，两个冒号必须具有相同的间距。例外:当切片参数被省略时，空格空间被省略。
Yes:
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]
No:
ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : upper]
ham[ : upper]
在启动函数调用的参数列表的左括号之前：
Yes: spam(1)
No: spam (1)
在开始索引或切片的开括号之前:
Yes: dct['key'] = lst[index]
No: dct ['key'] = lst [index]
一个赋值(或其他)操作符周围的多个空格，以便与另一个操作符对齐。
Yes:
x = 1
y = 2
long_variable = 3
No:
x = 1
y = 2
long_variable = 3
4.2 Other Recommendations
避免尾随空格。因为它通常是不可见的，所以它可能会令人困惑：例如，反斜杠后跟空格和换行符不算作行延续标记。有些编辑器不保存它，许多项目(比如CPython本身)都有拒绝它的pre-commit hooks
这些二进制操作符两边通常都会用一个空格：赋值(=)，增广赋值(+=，-=等)，比较(==，<，>，!=，<>，<=，>=，in, not in, is, not)，布尔值(and, or, not)
如果使用不同优先级的操作符，请考虑在优先级最低的操作符周围添加空格。但是，永远不要使用超过一个空格，并且总是在二进制运算符的两边有相同数量的空格。
Yes:
i = i + 1
submitted += 1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)
No:
i=i+1
submitted +=1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
不要在 = 符号周围使用空格来表示关键字参数或默认参数值。
Yes:
def complex(real, imag=0.0):
return magic(r=real, i=imag)
No:
def complex(real, imag = 0.0):
return magic(r = real, i = imag)
函数注释应该使用冒号的常规规则，如果存在的话，在->箭头周围总是有空格。(有关函数注释的更多信息，请参阅下面的函数注释。)
Yes:
def munge(input: AnyStr): ...
def munge() -> AnyStr: ...
No:
def munge(input:AnyStr): ...
def munge()->PosInt: ...
将参数注释与默认值组合在一起时，在=符号周围使用空格(但仅限于那些同时具有注释和默认值的参数)。
Yes:
def munge(sep: AnyStr = None): ...
def munge(input: AnyStr, sep: AnyStr = None, limit=1000): ...
No:
def munge(input: AnyStr=None): ...
def munge(input: AnyStr, limit = 1000): ...
复合语句(同一行的多个语句)通常不鼓励使用。
Yes:
if foo == 'blah':
do_blah_thing()
do_one()
do_two()
do_three()
Rather not:
if foo == 'blah': do_blah_thing()
do_one(); do_two(); do_three()
虽然有时候在一行中加上if /for / While，但是对于多子句的语句永远不要这样做。也要避免折叠如此长的行：
Rather not:
if foo == 'blah': do_blah_thing()
for x in lst: total += x
while t < 10: t = delay()
Definitely not:
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()
5. When to Use Trailing Commas
结尾的逗号通常是可选的，除了在构成一个元素的元组时是强制性需要的(在Python 2中，它们对print语句有语义)。为了清晰起见，建议将后者用括号括起来(在技术上是多余的)。
Yes:
FILES = ('setup.cfg',)
OK, but confusing:
FILES = 'setup.cfg',
当末尾逗号是冗余时，当使用版本控制系统时，当一列值、参数或导入项预期会随着时间的推移而增加时，逗号通常是有用的。模式是将每个值(等等)单独放在一行上，总是添加一个逗号，并在下一行添加右括号/括号/括号。然而，在同一行中使用逗号作为结束分隔符是没有意义的(除了在上面的单例元组中)。
Yes:
FILES = [
'setup.cfg',
'tox.ini',
]
initialize(FILES,
error=True,
)
No:
FILES = ['setup.cfg', 'tox.ini',]
initialize(FILES, error=True,)
6. Comments
与代码功能相矛盾的注释比没有注释更糟糕。当代码发生变化时，一定要优先保证注释的更新!
注释应该是完整的句子。第一个单词应该大写，除非它是以小写字母开头的标识符(千万不要改变标识符的大小写!)
块注释通常由完整句子组成的一个或多个段落组成，每个句子以句号结尾。
在多句注释中，除了最后一句之外，在一个句子结束后应该使用两个空格。
来自非英语国家的Python程序员：请用英语写你的注释，除非你有120%的把握知道代码不会被不懂你语言的人读到。
6.1 Block Comments
块注释通常适用于跟随它们的一些(或所有)代码，并且缩进到与代码相同的级别。块注释的每一行都以#和单个空格开头(除非它是注释内部缩进的文本)。
块注释中的段落由包含单个#的行分隔。
6.2 Inline Comments
有节制的使用内联注释。
内联注释是与语句同一行的注释。内联注释应该与语句至少分隔两个空格。它们应该从一个#和一个空格开始。
如果代码陈述了明显的内容，那么内联注释是不必要的，实际上内联注释还会分散注意力。不要这样做：
x = x + 1 # Increment x
# But sometimes, this is useful:
x = x + 1 # Compensate for border
6.3 Documentation Strings
对已经编写好的文档字符串的约定（a.k.a. “docstring”）在PEP 257中哟永久保留。
所有公共模块、函数、类和方法需要编写文档字符串。非公共方法不需要编写文档字符串，但是应该有一个注释来描述该方法的功能。这个注释应该出现在def行之后。
PEP 257描述了良好的文档字符串约定。最重要的是，结束多行文档字符串的""" 应该单独在一行上:。
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
对于一个行文档字符串，请保持结束注释时的 “”" 在同一行。
7. Naming Conventions
Python库的命名约定有点混乱，因此我们永远不会得到完全一致的命名约定——不过，下面是当前推荐的命名标准。应该根据这些标准编写新的模块和包(包括第三方框架)，但如果现有库具有不同的风格，则首选内部一致性。
7.1 Overriding Principle
作为API的公共部分，对用户可见的库命名应该遵循反映使用情况而不是实现的约定。
7.2 Descriptive: Naming Styles
有很多不同的命名方式。它有助于识别正在使用的命名风格，独立于它们的用途。
以下命名风格通常是可以区分的：
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系统调用struct的字段的对应关系，这有助于程序员熟悉这些字段。)
X11库的所有公共功能都使用一个前导X。在Python中，这种样式通常被认为是不必要的，因为属性和方法名的前缀是对象，函数名的前缀是模块名。（不理解）
此外，我们还了解到以下使用前导或后导下划线的特殊形式(这些通常可以与任何例子约定结合使用):
_single_leading_underscore: weak “internal use” indicator. E.g. from M import * 不会import 任何以下划线开头的对象
single_trailing_underscore_: 用于避免与Python关键字冲突的约定, e.g.
Tkinter.Toplevel(master, class_='ClassName')
__double_leading_underscore：在命名类属性时，调用名称管理(inside class FooBar, __boo becomes _FooBar__boo; see below).
double_leading_and_trailing_underscore: “magic” 对象或来自于用户控制的命名空间中的属性. E.g. __init__, __import__ or __file__. 从来没有发明这样的名字;只在文档中使用它们。
8. Prescriptive: Naming Conventions
8.1 Names to Avoid
千万不要把“l”(小写字母el)、“O”(大写字母oh)或“I”(大写字母eye)作为单个字符变量名。
在某些字体中，这些字符与数字1和0没有区别。当你想用“l”的时候，用“L”代替。
8.2 ASCII Compatibility
标准库中使用的标识符必须与ASCII兼容，如PEP 3131的策略部分所述。
8.3 Package and Module Names
模块应该有简短的、全小写的名称。如果能提高可读性，可以在模块名中使用下划线。Python包也应该有简短的、全小写的名称，尽管不鼓励使用下划线。
当用C或c++编写的扩展模块有一个附带的Python模块，该模块提供更高级别的接口(例如，更面向对象的接口)时，C/ c++模块有一个前导下划线(例如_socket)。
8.4 Class Names
类名通常应该使用CapWords约定。
The naming convention for functions may be used instead in cases where the interface is documented and used primarily as a callable.
注意，内建名称有一个单独的约定:大多数内建名称是单个单词(或两个单词一起运行)，而CapWords约定仅用于异常名称和内建常量。
8.5 Type Variable Names
在PEP 484中引入的类型变量的名称通常更倾向于使用简短名称的标题:T, AnyStr, Num.建议在用于声明协变或逆变行为的变量中添加后缀_co或_contra：
from typing import TypeVar
VT_co = TypeVar('VT_co', covariant=True)
KT_contra = TypeVar('KT_contra', contravariant=True)
8.6 Exception Names
因为异常应该是类，所以这里使用类命名约定。但是，您应该在异常名称上使用后缀“Error”(如果异常实际上是一个错误)。
8.7 Global Variable Names
(我们希望这些变量只在一个模块中使用。)这些约定与函数的约定大致相同。
具有 from M import * 设计的模块应该使用__all__机制来防止导出全局变量，或者使用旧的将这些全局变量加上下划线作为前缀的惯例(您可能希望这样做以表明这些全局变量是“模块非公共的”)。
8.8 Function and Variable Names
函数名应该是小写的，需要用下划，线分隔单词以提高可读性。
变量名与函数名遵循相同的约定。
mixedCase只能在已经流行的样式(例如thread .py)的上下文中使用，以保持向后兼容性。
8.9 Function and Method Arguments
使用self作为第一个参数来实例化方法。
使用cls作为类方法的第一个参数
如果函数参数的名称与保留关键字冲突，通常最好是附加一个单后置下划线，而不是使用缩写或拼写错误。因此class_比clss好。(最好是使用同义词来避免这种冲突。)
8.10 Method Names and Instance Variables
使用函数命名规则：必须用下划线分隔单词的小写字母来提高可读性。
仅对非公共方法和实例变量使用一个前导下划线。
为了避免与子类的名称冲突，使用两个前导下划线来调用Python的名称管理规则。
Python用类名来处理这些名称:如果类Foo有一个名为__a的属性，Foo.__a就不能访问它。(坚持不懈的用户仍然可以通过调用Foo._Foo__a获得访问权限。)通常，双前导下划线应该仅用于避免名称与设计为子类的类中的属性冲突。
注意:关于使用__name存在一些争议(见下文)。
8.11 Constants
常量通常在模块级别上定义，用所有大写字母和下划线分隔单词。示例包括MAX_OVERFLOW和TOTAL。
8.12 Designing for Inheritance
决定类的方法和实例变量(统称为“属性”)应该是公共的还是非公共的。如有疑问，选择非公开;晚些时候将其公开比将公共属性非公开要容易得多。
公共属性是您期望类中不相关的客户端使用的属性，并承诺避免向后不兼容的更改。非公共属性是指不打算由第三方使用的属性;您不能保证非公共属性不会更改，甚至不会被删除。
这里我们不使用术语“private”，因为Python中没有真正的私有属性(没有通常不必要的工作量)。
另一类属性属于“子类API”(在其他语言中通常称为“受保护”)。有些类的设计是为了继承，或者扩展或者修改类的行为。在设计这样的类时，要明确地决定哪些属性是公共的，哪些属性是子类API的一部分，哪些属性仅供基类使用。
考虑到这一点，下面是python的指导方法：
公共属性应该没有前导下划线。
如果公共属性名与保留关键字冲突，则在属性名后面附加一个下划线。这比缩写或错误的拼写更可取。(然而，尽管有这个规则，“cls”是任何已知为类的变量或参数的首选拼写，特别是类方法的第一个参数)。
注意1：关于类方法，请参阅上面的参数名建议。
对于简单的公共数据属性，最好只公开属性名，而不使用复杂的访问器/变量方法。请记住，如果您发现一个简单的数据属性需要增长功能行为，Python提供了一条通向未来增强的简单路径。在这种情况下，使用属性将函数实现隐藏在简单的数据属性访问语法后面。
注意1：属性只适用于新样式的类。
注意2：尽量避免函数行为的副作用，尽管缓存之类的副作用一般都很好。
注意3：避免将属性用于昂贵的计算操作;属性符号使调用者认为访问(相对)便宜。
如果您的类是要被子类化的，并且您有不希望子类使用的属性，请考虑使用双前导下划线和无尾随下划线来命名它们。这将调用Python的名称管理算法，其中类的名称将被划分为属性名。这有助于避免属性名冲突，因为子类可能无意中包含同名的属性。
注意1：请注意，在混乱的名称中只使用简单的类名，因此如果子类同时选择相同的类名和属性名，您仍然可以得到名称冲突。
注意2：名称管理可能会使某些用途(如调试和__getattr__())变得不方便。但是，名称管理算法有很好的文档记录，并且很容易手工执行。
注意3：不是每个人都喜欢拼名字。尽量在避免意外名称冲突与高级调用程序潜在使用之间保持平衡。
8.13 Public and Internal Interfaces
任何向后兼容保证只适用于公共接口。因此，重要的是用户能够清楚地区分公共接口和内部接口。
文档化的接口被认为是公共的，除非文档显式地声明它们是临时的或内部接口，而不受通常向后兼容保证的约束。所有未文档化的接口都应该假定为内部接口。
为了更好地支持内省，模块应该使用__all__属性显式地声明其公共API中的名称。将__all__设置为空列表表示该模块没有公共API。
即使正确设置了__all__，内部接口(包、模块、类、函数、属性或其他名称)仍然应该以一个前导下划线作为前缀。
如果任何包含名称空间(包、模块或类)被认为是内部的，那么接口也被认为是内部的。
导入的名称应该始终被视为实现细节。其他模块不能依赖对这些导入名称的间接访问，除非它们是包含模块API(如os)的显式文档部分。路径或包的__init__模块，该模块公开子模块的功能。
9. Programming Recommendations
代码的编写方式应该不影响Python的其他实现(PyPy、Jython、IronPython、Cython、Psyco等等)。
例如,不依赖CPython的高效实现就地字符串连接的语句形式+ = b或a = a + b。这种优化即使在CPython中也是脆弱的(它只适用于某些类型)，并且在不使用refcount的实现中根本不存在。在库的性能敏感部分，应该使用" .join()表单。这将确保连接在各个变量之间的线性时间内发生。
像None这样的单例比较操作应该使用is或not来做，永远不要用等式运算符。
另，要注意写if x ，当你真正的意思 if x is not None -- e.g测试一个默认为None的变量或参数是否被设置为其他值时。另一个值可能有一个类型(比如容器)，在布尔上下文中可能为false !
使用is not 操作，而不是 not ... is是多少。虽然这两个表达式在功能上是相同的，但前者更易于阅读，更受青睐。
Yes:
if foo is not None:
No:
if not foo is None:
在实现具有丰富比较的排序操作时，最好实现所有的六个操作(__eq__、__ne__、__lt__、__le__、__gt__、__ge__)，而不是依赖其他代码来执行特定的比较操作。
为了尽量减少工作，functools. total_ordered()装饰器提供了一个工具来生成缺少的比较方法。
PEP 207表示Python假定了自反性规则。因此,解释器可能交换 y > x 及x < y, y >= x 及 x <= y, 可能交换参数x == y和! = y。sort ()和min ()操作保证使用<操作符和max()函数使用>操作符。但是，最好实现所有六个操作，这样在其他上下文中就不会出现混淆。
始终使用def语句，而不是将lambda表达式直接绑定到标识符的赋值语句
Yes:
def f(x): return 2*x
No:
f = lambda x: 2*x
第一种形式表示生成的函数对象的名称是“f”，而不是通用的“。这对于一般的回溯和字符串表示更有用。赋值语句的使用消除了lambda表达式相对于显式def语句所能提供的唯一好处(即它可以嵌入到更大的表达式中)
从异常而不是基异常中派生异常。来自BaseException的直接继承保留给异常，在这些异常中，捕获它们几乎总是错误的。
根据捕获异常的代码可能需要的区别来设计异常层次结构，而不是异常产生的位置。以编程的方式回答“哪里出错了?”，而不是仅仅说明“发生了问题”(请参阅PEP 3151，以获得关于内置异常层次结构的这一课的示例)
类命名约定适用于此，但如果异常是错误的，则应该将后缀“Error”添加到异常类中。用于非本地流控制或其他信令形式的非错误异常不需要特殊后缀。
适当地使用异常链接。在python3中，“raise X from Y”应该被用来表示显式的替换而不丢失原始回溯。
当故意更换内部异常(使用Python 2中“raise X”或在Python 3.3 +中使用“raise X from None“),确保相关信息转移到新异常(如保护属性名称转换KeyError AttributeError时,或嵌入的文本原始异常在新的异常消息)。
在Python 2中引发异常时，使用raise ValueError('message')而不是较老的表单raise ValueError('message')。
后一种形式不是合法的Python 3语法。
使用参数的形式还意味着，当异常参数很长或包含字符串格式时，由于包含括号，您不需要使用行延续字符。
当捕捉异常时，尽可能提及特定的异常，而不是使用一个简单的except:子句:
try:
import platform_specific_module
except ImportError:
platform_specific_module = None
一个简单的except：子句将捕获SystemExit和KeyboardInterrupt异常，使得用Control-C中断一个程序变得更加困难，并且可以掩盖其他问题。如果你想捕获所有的异常，那就使用except Exception:：(除了等于 except BaseException:)。
一个好的经验法则是将“except”子句的使用限制在两种情况下:
如果异常处理程序将打印或记录回溯;至少用户会知道发生了错误。
如果代码需要做一些清理工作，请使用raise. try...finally 向上传播抛出异常。
当将捕获的异常绑定到名称时，最好使用Python 2.6中添加的显式名称绑定语法:
try:
process_data()
except Exception as exc:
raise DataProcessingFailedError(str(exc))
这是Python 3中唯一支持的语法，并避免了与旧的基于逗号的语法相关的歧义问题。
在捕获操作系统错误时，优先选择Python 3.3中引入的显式异常层次结构，而不是errno值的自省。
此外，对于所有try/except子句，将try子句限制为所需代码的绝对最小数量。同样，这可以避免掩盖bug。
Yes:
try:
value = collection[key]
except KeyError:
return key_not_found(key)
else:
return handle_value(value)
No:
try:
# Too broad!
return handle_value(collection[key])
except KeyError:
# Will also catch KeyError raised by handle_value()
return key_not_found(key)
当资源是特定代码段的本地资源时，使用with语句确保在使用后能够迅速、可靠地清理资源。try/finally语句也是可以接受的。
上下文管理器应该通过单独的函数或方法调用，只要它们做的不是获取和释放资源：
Yes:
with conn.begin_transaction():
do_stuff_in_transaction(conn)
No:
with conn:
do_stuff_in_transaction(conn)
后一个示例没有提供任何信息来表明__enter__和__exit__方法在执行事务后关闭连接之外的其他操作。在这种情况下，明确是很重要的。
在返回语句中保持一致。函数中的所有返回语句都应该返回表达式，或者它们都不应该返回表达式。如果任何return语句返回一个表达式，任何没有返回值的return语句都应该显式地将其声明为return None，并且在函数末尾应该显示显式的return语句(如果可达的话)。
Yes:
def foo(x):
if x >= 0:
return math.sqrt(x)
else:
return None
def bar(x):
if x < 0:
return None
return math.sqrt(x)
No:
def foo(x):
if x >= 0:
return math.sqrt(x)
def bar(x):
if x < 0:
return
return math.sqrt(x)
使用string方法而不是string模块。
字符串方法总是快得多，并且与unicode字符串共享相同的API。如果需要向后兼容大于2.0的python，则重写此规则。
使用" .startswith()和" .endswith()代替字符串切片检查前缀或后缀。
startswith()和endswith()更干净，更不容易出错：
Yes: if foo.startswith('bar'):
No: if foo[:3] == 'bar':
对象类型比较应该始终使用isinstance()，而不是直接比较类型。
Yes: if isinstance(obj, int):
No: if type(obj) is type(1):
当检查对象是否为字符串时，请记住它可能也是unicode字符串!在Python 2中，str和unicode有一个公共基类basestring，因此您可以这样做:
if isinstance(obj, basestring):
注意，在Python 3中，unicode和basestring不再存在(只有str)， bytes对象不再是某种字符串(而是整数序列)。
对于序列(字符串、列表、元组)，使用空序列为假的事实。
Yes: if not seq:
if seq:
No: if len(seq):
if not len(seq):
不要写依赖于重要的尾随空格的字符串文字。这样的结尾空格在视觉上难以区分，一些编辑器(或者最近的reindent.py)会对它们进行修剪。
不要使用==将布尔值与真值或假值进行比较。
Yes: if greeting:
No: if greeting == True:
Worse: if greeting is True:
9.1 Function Annotations
随着PEP 484的验收，函数注释的样式规则正在发生变化。
为了向前兼容，Python 3代码中的函数注释最好使用PEP 484语法。(在前一节中有一些注释格式建议。)
以前在这个PEP中推荐的注释样式的实验不再被鼓励。
然而，在stdlib之外，现在鼓励使用PEP 484规则进行实验。例如，使用PEP 484样式类型注释标记大型第三方库或应用程序，检查添加这些注释有多么容易，并观察它们的存在是否增加了代码的可理解性。
Python标准库在采用这种注释时应该是保守的，但是对于新代码和大型重构，允许使用这些注释。
对于想要使用不同功能注释的代码，建议使用以下形式的注释:
# type: ignore
接近文件顶部；这告诉类型检查器忽略所有注释。(在PEP 484中可以找到更细粒度的方法来禁用类型检查程序的投诉。)
与linters一样，类型检查器也是可选的、独立的工具。Python解释器默认情况下不应该因为类型检查而发出任何消息，也不应该基于注释改变它们的行为。
不想使用类型检查器的用户可以随意忽略它们。但是，第三方库包的用户可能希望在这些包上运行类型检查程序。为此，PEP 484建议使用存根文件:.pyi文件，类型检查器优先读取相应的.py文件。存根文件可以通过一个库进行分发，也可以通过类型化的repo[5]单独(在库作者的允许下)进行分发。
对于需要向后兼容的代码，可以以注释的形式添加类型注释。请参阅PEP 484[6]的相关部分。
9.2 Variable Annotations
PEP 526引入了变量注释。它们的的书写风格建议参考上面描述的函数注释:
模块级变量、类和实例变量以及局部变量的注释应该在冒号后面有一个空格。
冒号前面应该没有空格。
如果一个任务有有右边，那么等号两边应该只有一个空格。
Yes:
code: int
class Point:
coords: Tuple[int, int]
label: str = ''
No:
code:int # No space after colon
code : int # Space before colon
class Test:
result: int=0 # No spaces around equality sign
虽然Python 3.6接受PEP 526约束，但是对于所有Python版本的存根文件，变量注释语法是首选语法(详细信息请参阅PEP 484)。
附注：
挂缩进是一种类型设置样式，其中除了第一行以外，段落中的所有行都缩进。在Python的上下文中，这个术语用于描述这样一种样式:圆括号语句的开头括号是行的最后一个非空格字符，后面的行缩进直到结束括号。