谷歌python规范|PEP 8 - Python 代码风格指南

PEP 8 - Python 代码风格指南

简介

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

美其名曰:入乡随俗,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)
```

* 相对于 string 模块,使用 string 方法要快的多并且与 unicode strings 共享相同的 API。当然了,除了需要考虑 2.0 版本之前 python 代码向后兼容性的情况。

* 使用 ''.startswith() 和 ''.endswith() 而不是字符串切片来检查前缀或后缀,例如:

```python
是: if foo.startswith('bar'):
否: if foo[:3] == 'bar':
```

* 对象类型比较应该使用isinstance() 而不是直接比较:

```python
是: if isinstance(obj, int):
否: if type(obj) is type(1):
```

当检查一个对象是否为字符串时,一定要注意这个对象也可能是 unicode 字符串!在 Python 2 中,string 和 unicode 拥有一个公共基类 basestring,因此可以这么的:

```python
if isinstance(obj, basestring):
```

在 Python 3 中,unicode 和 basestring 已然不复存在(there's only str),并且 bytes object 也不再视为一种 string 了,而是一个整形序列。

* 对于序列(字符串,列表,元组)的判空操作:
```python
是:
if not seq:
if seq:

否:
if len(seq):
if not len(seq):
```

* 不要使用尾随空格。

* 不要使用 == 验证布尔值为 Ture 或 False:

```python
是:
    if greeting:
否:
    if greeting == True:
虾扯蛋:
    if greeting is True:
```

来源:https://github.com/tedyli/PEP8-Style-Guide-for-Python-Code

原创内容,禁止转载
程序员知识精选 » 谷歌python规范|PEP 8 - Python 代码风格指南