谷歌翻译Python PEP8编码规范《Style Guide for Python Code》

介绍
本文档提供了Python代码的编码约定，包括主Python发行版中的标准库。请参阅Python的C实现中描述C代码样式指南的配套信息PEP [1]。
本文和PEP 257（Docstring Conventions）改编自Guido的原始Python风格指南文章，还有一些来自Barry风格指南[2]的补充。
随着时间的推移，这种风格指南会随着时间的推移逐渐发展，并且过去的约定会因语言本​​身的变化而过时。
许多项目都有自己的编码风格指南。如果发生任何冲突，此类项目特定指南优先于该项目。
愚蠢的一致性是小思想的大人物
Guido的一个重要见解是，代码的读取频率远高于编写代码。此处提供的准则旨在提高代码的可读性，并使其在各种Python代码中保持一致。正如PEP 20所说，“可读性很重要”。
风格指南是关于一致性的。与此风格指南的一致性非常重要。项目的一致性更为重要。一个模块或功能内的一致性是最重要的。
但是，知道何时不一致 - 有时风格指南建议不适用。如有疑问，请使用您的最佳判断。查看其他示例并确定最佳效果。并且不要犹豫！
特别是：不要为了遵守这个PEP而破坏向后兼容性！
忽略特定指南的其他一些好理由：
1.在应用指南时，即使是习惯于阅读此PEP之后的代码的人，也会使代码的可读性降低。
2.为了与周围的代码保持一致（也许是出于历史原因） - 虽然这也是一个清理别人的混乱的机会（真正的XP风格）。
3.因为有问题的代码早于指南的引入，所以没有其他理由可以修改该代码。
4.当代码需要与不支持样式指南推荐的功能的旧版Python兼容时。
代码布局
缩进
每个缩进级别使用4个空格。
延续线应垂直对齐包裹元素，使用Python的隐含线连接括号，括号和括号内，或使用悬挂缩进 [7]。使用悬挂式凹痕时，应考虑以下因素; 第一行应该没有参数，应该使用进一步的缩进来明确区分自己作为延续线。
是：
＃与开口分隔符对齐。
foo = long_function_name（var_one，var_two，
var_three，var_four）
＃添加4个空格（额外的缩进级别）以区分参数与其余参数。
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
＃悬挂缩进应该添加一个级别。
foo = long_function_name(
var_one, var_two,
var_three, var_four)
没有：
＃不使用垂直对齐时禁止第一行上的参数。
foo = long_function_name(var_one, var_two,
var_three, var_four)
＃由于缩进无法区分，因此需要进一步缩进。
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
对于连续线，4空间规则是可选的。
可选的：
#Hall indents 可以缩进到4个空格以外的其他位置。
foo = long_function_name(
var_one, var_two,
var_three, var_four)
当if语句的条件部分足够长以要求它跨多行写入时，值得注意的是两个字符关键字（即if）的组合，加上一个空格，加上一个左括号创建一个自然的多行条件的后续行的4空格缩进。这可以与嵌套在if -statement中的缩进代码集产生视觉冲突，该代码集自然也会缩进到4个空格。该PEP没有明确地说明如何（或是否）进一步在视觉上将这些条件线与if-statement 内的嵌套套件区分开来。在这种情况下可接受的选择包括但不限于：
＃没有额外的缩进。
if (this_is_one_thing and
that_is_another_thing):
do_something()
＃添加注释，这将在编辑器中提供一些区别
＃支持语法高亮显示。

if (this_is_one_thing and
that_is_another_thing):
＃由于这两个条件都是正确的，我们可以讨厌。
do_something()

＃在条件连续行上添加一些额外的缩进。
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 3不允许混合使用制表符和空格来缩进。
使用制表符和空格的混合缩进的Python 2代码应该转换为仅使用空格。
当使用-t选项调用Python 2命令行解释器时，它会发出有关非法混合制表符和空格的代码的警告。使用-tt时，这些警告会出错。强烈推荐这些选项！
最大线长
将所有行限制为最多79个字符。
对于流动具有较少结构限制（文档字符串或注释）的长文本块，行长度应限制为72个字符。
限制所需的编辑器窗口宽度可以使多个文件并排打开，并且在使用在相邻列中显示两个版本的代码审查工具时可以正常工作。
大多数工具中的默认包装会破坏代码的可视化结构，使其更难理解。选择限制是为了避免在窗口宽度设置为80的情况下包装在编辑器中，即使工具在包装线时在最后一列中放置标记符号。某些基于Web的工具可能根本不提供动态换行。
一些团队强烈倾向于更长的线路长度。对于专门或主要由可以就此问题达成一致的团队维护的代码，可以将行长度限制增加到99个字符，前提是评论和文档字符串仍然包含72个字符。
Python标准库是保守的，需要将行限制为79个字符（文档字符串/注释限制为72个）。
包装长行的首选方法是在括号，括号和括号内使用Python隐含的行继续。通过在括号中包装表达式，可以在多行中分割长行。这些应该优先使用反斜杠来继续行。
反斜杠有时可能仍然合适。例如，long，multiple with -statements不能使用隐式延续，因此可以接受反斜杠：
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 进行此类多行缩进的进一步思考。）
另一个这样的情况是断言语句。
确保适当缩进续行。
应该在二元运算符之前或之后换行吗？
几十年来，推荐的风格是在二元运算符之后打破。但这会以两种方式损害可读性：运算符往往分散在屏幕上的不同列中，并且每个运算符都从其操作数移到前一行。在这里，眼睛必须做额外的工作来分辨哪些项目被添加以及哪些项目被减去：
#No：操作员远离操作员
income = (gross_wages +
taxable_interest +
(dividends - qualified_dividends) -
ira_deduction -
student_loan_interest)
为了解决这个可读性问题，数学家和他们的出版商遵循相反的惯例。Donald Knuth在他的计算机和排版系列中解释了传统规则：“虽然段落中的公式总是在二元运算和关系之后中断，但显示的公式总是在二元运算之前中断” [3]。
遵循数学传统通常会产生更易读的代码：
#Yes：易于将操作符与操作数匹配
income = (gross_wages
+ taxable_interest
+ (dividends - qualified_dividends)
- ira_deduction
- student_loan_interest)
在Python代码中，只要约定在本地一致，就允许在二元运算符之前或之后中断。对于新代码，建议使用Knuth的样式。
空白行
使用两个空行环绕顶级函数和类定义。
类中的方法定义由单个空行包围。
可以使用额外的空白行（谨慎地）来分离相关功能组。在一堆相关的单行（例如，一组虚拟实现）之间可以省略空行。
在函数中使用空行，谨慎地指示逻辑部分。
Python接受control-L（即^ L）换页