python代码风格指南：pep8 中文翻译

Posted 2020-08-02 编程浪子-Yiutto

摘要

本文给出主Python版本标准库的编码约定。CPython的C代码风格参见?PEP7。本文和?PEP 257 文档字符串标准改编自Guido最初的《Python Style Guide》, 并增加了Barry的?GNU Mailman Coding Style Guide的部分内容。本文会随着语言改变等而改变。许多项目都有自己的编码风格指南，冲突时自己的指南为准。

本文给出主Python版本标准库的编码约定。CPython的C代码风格参见PEP7。

本文和PEP 257 文档字符串标准改编自Guido最初的《Python Style Guide》, 并增加了Barry的GNU Mailman Coding Style Guide的部分内容。

本文会随着语言改变等而改变。

许多项目都有自己的编码风格指南，冲突时自己的指南为准。

一致性考虑

Guido的关键点之一是：代码更多是用来读而不是写。本指南旨在改善Python代码的可读性，即PEP 20所说的"可读性计数"(Readability counts)。

风格指南强调一致性。项目、模块或函数保持一致都很重要。

最重要的是知道何时不一致, 有时风格指南并不适用。当有疑惑时运用你的最佳判断，参考其他例子并多问！

特别注意：不要因为遵守本PEP而破坏向后兼容性！

部分可以违背指南情况：

• 遵循指南会降低可读性。
• 与周围其他代码不一致。
• 代码在引入指南完成，暂时没有理由修改。
• 旧版本兼容。

代码布局

缩进

每级缩进用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)

 

# 参数的缩进和后续内容缩进不能区别。

def long_function_name(

    var_one, var_two, var_three,

    var_four):

    print(var_one)

4个空格的规则是对续行可选的。

# 悬挂缩进不一定是4个空格

foo = long_function_name(

  var_one, var_two,

  var_three, var_four)

if语句跨行时，两个字符关键字(比如if)加上一个空格，再加上左括号构成了很好的缩进。后续行暂时没有规定，至少有如下三种格式，建议使用第3种。

# 没有额外缩进，不是很好看，个人不推荐.

if (this_is_one_thing and

    that_is_another_thing):

    do_something()

 

# 添加注释

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。

注意续行要尽量不影响可读性。比如通常在二元运算符之后续行：

class Rectangle(Blob):

 

    def __init__(self, width, height,

                 color=‘black‘, emphasis=None, highlight=0):

        if (width == 0 and height == 0 and

                color == ‘red‘ and emphasis == ‘strong‘ or

                highlight > 100):

            raise ValueError("sorry, you lose")

        if width == 0 and height == 0 and (color == ‘red‘ or

                                           emphasis is None):

            raise ValueError("I don‘t think so -- values are %s, %s" %

                             (width, height))

        Blob.__init__(self, width, height,

                      color, emphasis, highlight)

空行

• 两行空行分割顶层函数和类的定义。
• 类的方法定义用单个空行分割。
• 额外的空行可以必要的时候用于分割不同的函数组，但是要尽量节约使用。
• 额外的空行可以必要的时候在函数中用于分割不同的逻辑块，但是要尽量节约使用。
• 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

from subprocess import Popen, PIPE

No:

import sys, os

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

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

相关的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

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

其他建议

• 二元运算符两边放置一个空格:

涉及 =、符合操作符 ( += , -=等)、比较( == , < , > , != , <> , <= , >= , in , not in , is , 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(sep: AnyStr = None):

def munge() -> AnyStr:

def munge(input: AnyStr, sep: AnyStr = None, limit=1000):

 

# No

def munge(input: AnyStr=None):

def munge(input:AnyStr):

def munge(input: AnyStr)->PosInt:

• 通常不推荐复合语句(Compound statements: 多条语句写在同一行)。

# Yes

if foo == ‘blah‘:

    do_blah_thing()

do_one()

do_two()

do_three()

 

# No

if foo == ‘blah‘: do_blah_thing()

do_one(); do_two(); do_three()

• 尽管有时可以在if/for/while 的同一行跟一小段代码，但绝不要跟多个子句，并尽量避免换行。

# No

if foo == ‘blah‘: do_blah_thing()

for x in lst: total += x

while t < 10: t = delay()

更不是：

# No

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

注释

与代码自相矛盾的注释比没注释更差。修改代码时要优先更新注释！

注释是完整的句子。如果注释是断句，首字母应该大写，除非它是小写字母开头的标识符(永远不要修改标识符的大小写)。

如果注释很短，可以省