python代码风格指南:pep8 中文版

时间:2022-04-11 06:40:38

本文档所提供的编码规范,适用于主要的Python发行版中组成标准库的Python代码。请参阅PEP关于Python的C实现的C编码风格指南的描述。

本文档和PEP257(文档字符串规范)改编自Guido的《Python Style Guide》一文,并从《Barry's style guide》添加了部分内容作为补充。

这篇风格指南随着时间的推移而逐渐演变,随着语言本身的变化,一些过去的约定已经过时,并确定了更多新的约定。

许多项目都有自己的编码风格指南。如果有任何冲突,优先使用该项目特定的指南。

愚蠢地坚持一致性是无知的妖怪

Guido的一个重要的见解是,代码阅读的次数比编写的次数多。这里提供的指南旨在提高代码的可读性,并使各种不同的Python代码一致。如PEP20所说,“可读性很重要”。

风格指南是关于一致性的。与本风格指南一致很重要。项目中的一致性更重要。一个模块或函数中的一致性最重要。

最重要的是:知道何时会不一致——有时风格指南就不适用了。怀疑时,作出你最佳的判断。看看其他的例子,并决定什么是最好的。不要犹豫,尽管发问!

特别地:不要只为遵从这个PEP而打破向后兼容性!

可以忽略部分风格指南的好理由,不要只为遵从这个PEP而打破向后兼容性!

忽视既定指南的一些其他的好理由:

  1. 当应用指南会降低代码的可读性,即使对于那些习惯遵照这个PEP来阅读代码的人来说。
  2. 与周围的代码保持一致也会破坏它(可能是历史原因)——虽然这也是收拾别人烂摊子的好机会(在真正的XP风格中)。
  3. 因为问题代码先于指南,又没有其它的修改理由。
  4. 代码需要兼容老版本,本风格指南不建议使用的Python特性。

代码布局

缩进

  每级缩进用4个空格。

括号中使用垂直隐式缩进或使用悬挂缩进。当使用悬挂缩进时,应考虑以下内容:第一行上没有参数,后续行要有缩进。

·Yes:

# 与起始定界符对齐:
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)

# 悬挂缩进,必须增加一层缩进
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

No:

# 不使用垂直参数时,第一行不能有参数。
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# 参数的缩进与print()函数缩进相同。
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 语句跨行时,两个字符关键字加上一个空格,再加上左括号构成了很好的缩进。后续行暂时没有规定,以下有三种格式,建议用三种:

# 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()

也请参阅下面的二进制操作符之前或之后是否要中断的讨论。

右边括号也可以另起一行。有两种格式,建议第2种。

# 右括号不回退,个人不推荐
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',
)

空格或Tab?

  • 空格是首选的缩进方法。

  • Tab仅仅在已经使用tab缩进的代码中为了保持一致性而使用。

  • Python 3中不允许混合使用Tab和空格缩进。

  • Python 2的包含空格与Tab和空格缩进的应该全部转为空格缩进。

Python2命令行解释器使用-t选项时有非法混合Tab和空格的情况会告警。当使用-tt警告提升为错误。强烈推荐这些选项!另外个人推荐pep8和autopep8模块。

最大行宽

限制所有行的最大行宽为79字符。

文本长块,比如文档字符串或注释,行长度应限制为72个字符。

多数工具默认的续行功能会破坏代码结构,使它更难理解,不推荐使用。但是超过80个字符加以提醒是必要的。一些工具可能根本不具备动态换行功能。

一些团队强烈希望更长的行宽。如果能达成一致,可以从从80提高到100个字符(最多99个字符)增加了标称线的长度,不过依旧建议文档字符串和注释保持在72的长度。

Python标准库比较保守,限制行宽79个字符(文档字符串/注释72)。

续行的首选方法是使用小括号、中括号和大括号反斜线仍可能在适当的时候。其次是反斜杠。比如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())

类似的还有assert。

应该在二进制操作符之前或之后续行吗?

几十年来,推荐的样式是在二进制运算符之后中断。但这可能会以两种方式损害可读性:操作员倾向于分散在屏幕上的不同列上,并且每个运算符从其操作数移动到上一行。在这里,眼睛必须做额外的工作,告诉哪些项目被添加,哪些被减去。

# No: operators sit far away from their operands.操作员坐在远离操作数的地方
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

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

遵循数学传统,通常会产生更多可读代码。

# Yes: easy to match operators with operands.易于与操作数匹配的运算符
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

在Python代码中,允许在二进制操作符之前或之后中断,只要约定在本地是一致的。对于新代码,Knuth的风格被提出。

空行

  • 两行空行分割顶层函数和类的定义。

  • 类的方法定义用单个空行分割。

  • 额外的空行可以必要的时候用于分割不同的函数组,但是要尽量节约使用。

  • 额外的空行可以必要的时候在函数中用于分割不同的逻辑块,但是要尽量节约使用。

  • Python接 contol-L作为空白符;许多工具视它为分页符,这些要因编辑器而异。

源文件编码

在核心Python发布的代码应该总是使用UTF-8(ASCII在Python 2)。

ASCII文件(Python 2)或UTF-8(Python 3)不应有编码声明。

标准库中非默认的编码应仅用于测试或当注释或文档字符串,比如包含非ASCII字符的作者姓名,尽量使用\x , \u , \U , or \N。

Python 3.0及以后版本,PEP 3131可供参考,部分内容如下:在Python标准库必须使用ASCII标识符,并尽量只使用英文字母。此外字符串和注释也必须用ASCII。唯一的例外是:(a)测试非ASCII的功能,和(b)作者的名字不是拉丁字母。

导入

  • 导入在单独行

Yes: import os
     import sys

No:  import sys, os

这样说也可以

from subprocess import Popen, PIPE
  • 导入始终在文件的顶部,在模块注释和文档字符串之后,在模块全局变量和常量之前。

导入顺序如下:标准库进口,相关的第三方库,本地库。各组的导入之间要有空行。

相关的all放在导入之后。

  • 推荐绝对路径导入,因为它们通常更可读,而且往往是表现更好的(或至少提供更好的错误消息。

    import mypkg.sibling
    from mypkg import sibling
    from mypkg.sibling import example

在绝对路径比较长的情况下,也可以使用相对路径:

from . import sibling
from .sibling import example

标准库代码应该避免复杂的包布局,并且总是使用绝对的导入。

在Python 3中不应该使用和删除隐式相对导入。

导入类的方法:

from myclass import MyClass
from foo.bar.yourclass import YourClass

如果和本地名字有冲突:

import myclass
import foo.bar.yourclass

禁止使用通配符导入。

  通配符导入(from <module> import *)应该避免,因为它不清楚命名空间有哪些名称存,混淆读者和许多自动化的工具。唯一的例外是重新发布对外的API时可以考虑使用。

字符串引用

Python中单引号字符串和双引号字符串都是相同的。注意尽量避免在字符串中的反斜杠以提高可读性。

根据PEP 257, 三个引号都使用双引号。

表达式和语句中的空格

强制要求

  括号里边避免空格

# 括号里边避免空格
# 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)
dct['key'] = lst[index]

# No
spam (1)
dct ['key'] = lst [index]

  赋值等操作符前后不能因为对齐而添加多个空格

# Yes
x = 1
y = 2
long_variable = 3

# No
x             = 1
y             = 2
long_variable = 3

其他建议