PEP 8 - Python 代码风格指南

Introduction - 简介
A Foolish Consistency is the Hobgoblin of Little Minds - 愚蠢的一致性是小心灵的大地精
Code lay-out - 代码布局
String Quotes - 字符串引号
Whitespace in Expressions and Statements - 表达式和语句中的空格
- Pet Peeves - 心理藏的小烦恼
- Other Recommendations - 其他建议
When to use trailing commas - 何时使用逗号结尾
Comments - 注释
Naming Conventions - 命名约定

简介

很多项目都有自己独有的编码风格。如果和本文规则发生任何冲突，优先与项目级别的代码风格保持一致。

美其名曰：入乡随俗，Do what Romans do in Rome，到罗马咱就烤马肉吃。

愚蠢的一致性是小心灵的大地精

代码风格一致性当然重要，想象一下空姐的制服诱惑，是不是赏心悦目呢。但也要有自己的主观判断。

例如以下场景：

1、遵循此风格写的一小片代码看起来和项目内其他代码格格不入，看到就想抠出来喂猪，人人见而曰日之。

2、遵循此风格后和其他 python 版本不兼容，甚至出现错误，这就尴尬了。

3、遵循此风格中的某些条目使代码更不易读，简单说就是丑。

代码布局

缩进

一个缩进级别四个空格。

连续行使用两种方式使封装元素成为一行：括号内垂直隐式连接 & 悬挂式缩进。使用悬挂式缩进应该注意第一行不应该有参数，连续行要使用进一步的缩进来区分。


是：

# 括号内隐式连接，垂直对齐
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)

否：

# 括号内隐式连接，没有垂直对齐时，第一行的参数被禁止
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)

当 if 语句过长时，可选的处理方式，但不限于此：

# 不使用额外缩进
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()

# 条件连续行额外缩进
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',
)

A 罩杯还是 E 罩杯？

A 罩杯。

Python 3 不允许 tab 和 space 混用，同时混用了 tab 和 space 的 Python 2 代码应该被转换为仅使用 space。

代码行最大长度

将所有行限制为最多79个字符。

对于具有较少结构限制（文档字符串或注释）的长文本块，行长度应限制为72个字符。

当然了，不要问为啥非得是 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 语句也是如此。

在二元运算符之前还是之后断行?

算法和程序设计技术先驱，计算机排版系统 TEX 和 METAFONT 的发明者 Donald Knuth，推荐使用以下形式：

# 是： easy to match operators with operands
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

只要保持本地一致性，在二元运算符之前和之后断开都是允许的，但是新的 Python 代码推荐使用 Knuth 形式。

空行

顶层函数和类定义间使用两个空行。

类内方法定义间使用一个空行。

不同函数组之间使用两个空行隔离。

总之，空行的作用就是隔离不同函数类等，使层次分明。

源文件编码

Python 2 默认ASCII，Python 3 默认UTF-8。

使用 ASCII 的 Python 2 源文件或使用 UTF-8 的 Python 3 源文件不应该有编码声明。

源文件最好只使用 ASCII 字符，即使是蹩脚的 Chinglish 亦可，家和万事兴。

模块导入

是：
    from subprocess import Popen, PIPE
    import os
    import sys

否：
    import sys, os

模块导入总是位于文件顶部，在模块注释和文档字符串之后，模块全局变量和常量之前。

导入应该按照以下顺序分组，不同组间用空行隔离。

标准库 imports
相关第三方 imports
本地特定应用／库 imports

推荐使用绝对导入，标准库代码应总是使用绝对导入。

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

然后使用 myclass.MyClass 和 foo.bar.yourclass.YourClass。

请不要使用以下方式：

from <module> import *

模块级别 dunder 名称

模块级别 “dunders”(即具有两个前导和两个后缀下划线的名称)，例如 __all__，__author__，__version__ 等应放在模块 docstring 之后，但在任何 import 语句之前，但是除了 __future__ 导入。 Python 强制 future-imports 必须在除了 docstrings 之外的任何其他代码之前出现在模块中。
例如：

"""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

字符串引号

在 Python 中，单引号和双引号是等价的，只需要坚持使用一种并保持一致即可。

在双引号中使用单引号，单引号中使用双引号。三引号中使用双引号。

表达式和语句中的空格

心理藏的小烦恼

在以下场景避免不必要的空格

```Python
是： spam(ham[1], {eggs: 2})
否： spam( ham[ 1 ], { eggs: 2 } )

是： foo = (0,)
否： bar = (0, )

是： if x == 4: print x, y; x, y = y, x
否： if x == 4 : print x , y ; x , y = y , x

是：
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]

否：
ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : upper]
ham[ : upper]

是： spam(1)
否： spam (1)

是： dct['key'] = lst[index]
否： dct ['key'] = lst [index]

是：
x = 1
y = 2
long_variable = 3

否：
x = 1
y = 2
long_variable = 3

```

其他建议

在任何地方避免使用尾随空格。

在二元运算符周围使用空格：

```python
是：

i = i + 1
submitted += 1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)

否：

i=i+1
submitted +=1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
```
表示关键字参数或默认参数值时，不要使用空格：

```python
是：

def complex(real, imag=0.0):
return magic(r=real, i=imag)
否：

def complex(real, imag = 0.0):
return magic(r = real, i = imag)
```
函数注解的场景：

```python
是：

def munge(input: AnyStr): ...
def munge() -> AnyStr: ...

否：

def munge(input:AnyStr): ...
def munge()->PosInt: ...
```

当参数注释和默认值共存时：

```python
是：

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

否：

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

同行多语句不建议使用：

```python
是：

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

下面这种丑就不多说了：

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

何时使用逗号结尾

单元素元组强制使用逗号：

```python
是：

FILES = ('setup.cfg',)

OK, but confusing:

FILES = 'setup.cfg',
```
当使用版本控制系统时，一组希望后续扩展的值/参数/改善的条目使用以下形式：
```python
是：

FILES = [
'setup.cfg',
'tox.ini',
]
initialize(FILES,
error=True,
)
否：

FILES = ['setup.cfg', 'tox.ini',]
initialize(FILES, error=True,)
```

注释

糟糕的注释不如没有注释，一定要用 English 注释。

块注释

同等级别的一块代码的注释，块注释内每行注释以 \# 开头，内部注释段落之间使用以 \# 开头的空行注释隔开。

行注释

行注释和代码声明间至少间隔两个空格，不要使用无聊的行注释，例如：

```python
Don't do this:

x = x + 1 # Increment x

But sometimes, this is useful:

x = x + 1 # Compensate for border
```

文档字符串

为所有公共模块，函数，类和方法编写文档字符串。对于非公共方法，文本字符串不是必需的，但应该有一个描述该方法的注释。例如：
```python
"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""

"""only one single docstring line"""
```

注意当注释为多行时，最终的 """ 单独起一行。

命名约定

圣经戒律

对用户可见的公共 API 部分的命名应该遵从反应如何使用而不是怎么实现。

描述性: 命名风格

以下命名风格通常区分彼此使用：

* b (单个小写字母)

* B (单个大写字母)

* lowercase（小写）

* lower\_case\_with_underscores（带下划线的小写）

* UPPERCASE（大写）

* UPPER\_CASE\_WITH\_UNDERSCORES（带下划线的大写）

* CapitalizedWords（驼峰式，蒙古包式 whatever.）

Note: 使用驼峰式时，缩写全部大写，例如：HTTPServerError 好于 HttpServerError

* mixedCase (乌鬼头)

* Capitalized_Words_With_Underscores (丑！不解释！)

* \_single\_leading\_underscore : 弱地 "内部使用" 指示器. 例如，from M import * 不会导入下划线开头的对象-

文档说明的接口一般认为是公共接口，除非文档明确声明为临时或内部接口（为了兼容性等其他原因），所有非文档说明的接口一般为内部接口。

模块应该使用 \_\_all\_\_ 属性明确声明公共 API 名，如果 \_\_all\_\_ 为空，则表明模块没有公共 API。

尽管使用了 \_\_all\_\_ 属性，内部接口（packages, modules, classes, functions, attributes or other names）仍然需要使用前缀下划线。

如果包含的任何一个命名空间（package, module or class）是内部的，那么这个接口也被认为是内部接口。

导入名应该总是被视为实现细节。其他导入模块一定不能依赖对此导入名的间接访问，除非它们是包含模块 API 的显式文档说明的部分，例如 os.path 或者一个 package 向子模块暴露函数的 \_\_init\_\_ 模块。

编码建议

* 代码不应该以一种不利于其他 python 实现（PyPy, Jython, IronPython, Cython, Psyco 诸如此类）的方式编写。例如：不要使用 a += b 或 a = a + b 来实现就地字符串连接，在库的性能敏感部分，应该使用 ''.join() 的形式，这就能保证在不同的 python 实现中，连接动作可以在线性时间内完成。

* 和例如 None 这类 singleton 的比较，应该使用 is 或 is not 而不是 ==。另外，小心使用 if x 如果你的本意是 if x is not None，如果 x 是个布尔变量值 false，那可就完蛋了。

* 尽管功能相同，从可读性上考虑：

```python
是：

if foo is not None:

否：

if not foo is None:
```
* 当使用 rich comparisons 实现排序操作时，最好是实现所有六种操作(\_\_eq\_\_,\_\_ne\_\_, \_\_lt\_\_, \_\_le\_\_, \_\_gt\_\_, \_\_ge\_\_)而不要依赖其他的代码去单独实现某一类比较。为了减少劳动，functools.total_ordering() decorator 提供了一个生成缺失比较方法的工具。

* 使用 def 语句而不要使用赋值语句去直接绑定一个 lambda 表达式到标识符上：

```python
是：

def f(x): return 2*x

否：

f = lambda x: 2*x
```

赋值语句的使用消除了 lambda 表达式相对于显式 def 语句的唯一好处，那就是它能够嵌入到一个更大的表达式里面。

* 捕获的异常要说明 "错误出在哪里了？" 而不是仅仅说明 "哎呀！出问题了！"。

* 正确使用异常链接。在 Python 3 中，应该使用 "raise X from Y" 来表示显式替换并且不会丢失原始追溯。

当有意替换一个内部异常(Python 2: "raise X", Python 3.3+: raise X from Non)时，请确保将相关的详细信息转移到新的异常(例如，将 KeyError 转换为 AttributeError 时保留属性名称，或将原始异常的文本嵌入到新的异常消息中)。

* 当在 Python 2 中抛出异常时，使用 raise ValueError('message') 而不是老式的 raise ValueError, 'message'，后者已经在 Python 3 中废弃。由于使用了括号，可以避免行连续符的使用。

* 当捕获异常时，尽可能提及具体的异常而不是使用一个赤裸裸的 except 子句。一个裸露的 except: 子句将捕获 SystemExit 和 KeyboardInterrupt 异常，这样的话就难于使用 control-c 中断程序，并可能掩盖其他问题。如果想要捕获标志程序错误的所有异常的话，用 except Exception:(裸露的 except 子句等同于 except BaseException:)：

```python
try:
import platform_specific_module
except ImportError:
platform_specific_module = None
```

一个很好的经验法则是将裸露的 except 子句仅用于以下两种情况：

1、If the exception handler will be printing out or logging the traceback; at least the user will be aware that an error has occurred.

2、If the code needs to do some cleanup work, but then lets the exception propagate upwards with raise . try...finally can be a better way to handle this case.

* 当对捕获的异常重命名时，使用 2.6 版本引入的语法：

```python
try:
process_data()
except Exception as exc:
raise DataProcessingFailedError(str(exc))
```

* 当捕获操作系统错误时，相对于内置的 errno 值，最好是使用 Python 3.3 中介绍的显式异常层次结构。

* 对于所有的 try/except 子句，将 try 子句限制为必需的绝对最小代码量避免隐藏 bug：

```python
是：

try:
value = collection[key]
except KeyError:
return key_not_found(key)
else:
return handle_value(value)

否：

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 也可以。

* 除了申请和释放资源，任何时候都应该使用单独的函数和方法调用 Context managers，例如：

```python
是：

with conn.begin_transaction():
do_stuff_in_transaction(conn)

否：

with conn:
do_stuff_in_transaction(conn)
```

* 函数返回语句要一致。在一个函数内的所有返回语句要么都返回一个表达式，要么都不返回。如果任何一个返回语句返回了表达式，那么其他任何没有返回值的语句应该明确声明为 return None。在函数结束部分必须出现返回语句：
```python
是：

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)

否：

def foo(x):
if x >= 0:
return math.sqrt(x)

def bar(x):
if x < 0:
return
return math.sqrt(x)
```