python PEP8 编码规范

python PEP8 编码规范

代码布局

缩进

• 每一级缩进使用4个空格。
• 续行应该与其包裹元素对齐，或者使用 挂行缩进1 对齐
  
  • 当使用挂行缩进时，应该考虑到第一行不应该有参数，以及使用缩进以区分自己是续行

# 与左括号对齐
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)

• if 语句的条件部分长到需要换行写的时候，注意可以在两个字符关键字的连接处（比如 if ），增加一个空格，再增加一个左括号来创造一个4空格缩进的多行条件。这会与if语句内同样使用4空格缩进的代码产生视觉冲突。

# 没有额外的缩进
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',
)

制表符还是空格？

空格是首选的缩进方式。
制表符只能用于与同样使用制表符缩进的代码保持一致。
Python3不允许同时使用空格和制表符的缩进。
混合使用制表符和空格缩进的Python2代码应该统一转成空格。
当在命令行加入-t选项执行Python2时，它会发出关于非法混用制表符与空格的警告。当使用–tt时，这些警告会变成错误。强烈建议使用这样的参数。

行的最大长度

所有行限制的最大字符数为79。
没有结构化限制的大块文本（文档字符或者注释），每行的最大字符数限制在72。

较长的代码行选择Python在小括号，中括号以及大括号中的隐式续行方式。通过小括号内表达式的换行方式将长串折成多行。这种方式应该优先使用，而不是使用反斜杠续行。

反斜杠有时依然很有用。比如，比较长的，多个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())

在二元运算符之前应该换行吗？

二元运算符之前中断

# 推荐：运算符和操作数很容易进行匹配
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

空行

• 顶层函数和类的定义，前后用两个空行隔开。
• 类里的方法定义用一个空行隔开。
• 相关的功能组可以用额外的空行（谨慎使用）隔开。一堆相关的单行代码之间的空白行可以省略（例如，一组虚拟实现 dummy implementations）。
• 在函数中使用空行来区分逻辑段（谨慎使用）。
• Python接受control-L（即^L）换页符作为空格；许多工具把这些字符当作页面分隔符，所以你可以在文件中使用它们来分隔相关段落。请注意，一些编辑器和基于Web的代码阅读器可能无法识别control-L为换页，将在其位置显示另一个字形。

源文件编码

Python核心发布版本中的代码总是以UTF-8格式编码（或者在Python2中用ASCII编码）。

使用ASCII（在Python2中）或UTF-8（在Python3中）编码的文件不应具有编码声明。

在标准库中，非默认的编码应该只用于测试，或者当一个注释或者文档字符串需要提及一个包含内ASCII字符编码的作者名字的时候；否则，使用\x,\u,\U , 或者 \N 进行转义来包含非ASCII字符。

对于Python 3和更高版本，标准库规定了以下策略（参见 PEP 3131）：Python标准库中的所有标识符必须使用ASCII标识符，并在可行的情况下使用英语单词（在许多情况下，缩写和技术术语是非英语的）。此外，字符串文字和注释也必须是ASCII。
唯一的例外是（a）测试非ASCII特征的测试用例，以及（b）作者的名称。作者的名字如果不使用拉丁字母拼写，必须提供一个拉丁字母的音译。

Imports 导入

• 导入通常在分开的行

推荐: import os
     import sys

不推荐:  import sys, os

• 但是可以这样：

from subprocess import Popen, PIPE

• 导入总是位于文件的顶部，在模块注释和文档字符串之后，在模块的全局变量与常量之前。导入应该按照以下顺序分组：

  1. 标准库导入
  2. 相关第三方库导入
  3. 本地应用/库特定导入
     你应该在每一组导入之间加入空行。

• 推荐使用绝对路径导入，如果导入系统没有正确的配置（比如包里的一个目录在sys.path里的路径后），使用绝对路径会更加可读并且性能更好（至少能提供更好的错误信息）:

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 import *），因为这样做会不知道命名空间中存在哪些名字，会使得读取接口和许多自动化工具之间产生混淆。对于通配符的导入，有一个防御性的做法，即将内部接口重新发布为公共API的一部分（例如，用可选加速器模块的定义覆盖纯Python实现的接口，以及重写那些事先不知道的定义）。
  当以这种方式重新发布名称时，以下关于公共和内部接口的准则仍然适用。

模块级的“呆”名

像__all__ , __author__ , __version__ 等这样的模块级“呆名“（也就是名字里有两个前缀下划线和两个后缀下划线），应该放在文档字符串的后面，以及除from __future__ 之外的import表达式前面。Python要求将来在模块中的导入，必须出现在除文档字符串之外的其他代码之前。
比如：

"""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中，单引号和双引号字符串是相同的。PEP不会为这个给出建议。选择一条规则并坚持使用下去。当一个字符串中包含单引号或者双引号字符的时候，使用和最外层不同的符号来避免使用反斜杠，从而提高可读性。
对于三引号字符串，总是使用双引号字符来与PEP 257中的文档字符串约定保持一致。

表达式和语句中的空格

不能忍受的事情

在下列情况下，避免使用无关的空格：

• 紧跟在小括号，中括号或者大括号后。

Yes: spam(ham[1], {eggs: 2})
No:  spam( ham[ 1 ], { eggs: 2 } )12

• 紧贴在逗号、分号或者冒号之前。

Yes: if x == 4: print x, y; x, y = y, x
No:  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]

• 紧贴在函数参数的左括号之前。

Yes: spam(1)
No:  spam (1)12

• 紧贴索引或者切片的左括号之前。

Yes: dct['key'] = lst[index]
No:  dct ['key'] = lst [index]12

• 为了和另一个赋值语句对齐，在赋值运算符附件加多个空格。
  推荐：

x = 1
y = 2
long_variable = 3123

不推荐：

x             = 1
y             = 2
long_variable = 3

其他建议

• 避免在尾部添加空格。因为尾部的空格通常都看不见，会产生混乱：比如，一个反斜杠后面跟一个空格的换行符，不算续行标记。有些编辑器不会保留尾空格，并且很多项目（像CPython）在pre-commit的挂钩调用中会过滤掉尾空格。
• 总是在二元运算符两边加一个空格：赋值（=），增量赋值（+=，-=），比较（==,<,>,!=,<>,<=,>=,in,not,in,is,is not），布尔（and, or, not）。
• 如果使用具有不同优先级的运算符，请考虑在具有最低优先级的运算符周围添加空格。有时需要通过自己来判断；但是，不要使用一个以上的空格，并且在二元运算符的两边使用相同数量的空格。
  推荐：

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)

• 在制定关键字参数或者默认参数值的时候，不要在=附近加上空格。
  推荐：

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

• 功能型注释应该使用冒号的一般性规则，并且在使用->的时候要在两边加空格。（参考下面的功能注释得到能够多信息）
  推荐：

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

不推荐：

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

• 当给有类型备注的参数赋值的时候，在=两边添加空格（仅针对那种有类型备注和默认值的参数）。
  推荐：

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

• 复合语句(同一行中的多个语句)通常是不允许的。
  推荐：

if foo == 'blah':
    do_blah_thing()
do_one()
do_two()
do_three()

• 虽然有时候将小的代码块和 if/for/while 放在同一行没什么问题，多行语句块的情况不要这样用，同样也要避免代码行太长！
  最好别这样：

if foo == 'blah': do_blah_thing()
for x in lst: total += x
while t < 10: t = delay()123

绝对别这样：

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

注释

与代码相矛盾的注释比没有注释还糟，当代码更改时，优先更新对应的注释！
注释应该是完整的句子。如果一个注释是一个短语或句子，它的第一个单词应该大写，除非它是以小写字母开头的标识符(永远不要改变标识符的大小写！)。
如果注释很短，结尾的句号可以省略。块注释一般由完整句子的一个或多个段落组成，并且每句话结束有个句号。
在句尾结束的时候应该使用两个空格。
当用英文书写时，遵循Strunk and White （译注：《Strunk and White, The Elements of Style》）的书写风格。
在非英语国家的Python程序员，请使用英文写注释，除非你120%的确信你的代码不会被使用其他语言的人阅读。

块注释

块注释通常适用于跟随它们的某些（或全部）代码，并缩进到与代码相同的级别。块注释的每一行开头使用一个#和一个空格（除非块注释内部缩进文本）。
块注释内部的段落通过只有一个#的空行分隔。

行内注释

有节制地使用行内注释。
行内注释是与代码语句同行的注释。行内注释和代码至少要有两个空格分隔。注释由#和一个空格开始。
事实上，如果状态明显的话，行内注释是不必要的，反而会分散注意力。比如说下面这样就不需要：

x = x + 1                 # Increment x1

但有时，这样做很有用：

x = x + 1                 # Compensate for border

文档字符串

编写好的文档说明（也叫“docstrings”）的约定在PEP 257中永恒不变。

• 要为所有的公共模块，函数，类以及方法编写文档说明。非公共的方法没有必要，但是应该有一个描述方法具体作用的注释。这个注释应该在def那一行之后。
• PEP 257 描述了写出好的文档说明相关的约定。特别需要注意的是，多行文档说明使用的结尾三引号应该自成一行，例如：

"""Return a foobang

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

• 对于单行的文档说明，尾部的三引号应该和文档在同一行。

命名规范

Python库的命名规范很乱，从来没能做到完全一致。但是目前有一些推荐的命名标准。新的模块和包（包括第三方框架）应该用这套标准，但当一个已有库采用了不同的风格，推荐保持内部一致性。

最重要的原则

那些暴露给用户的API接口的命名，应该遵循反映使用场景而不是实现的原则。

描述：命名风格

有许多不同的命名风格。这里能够帮助大家识别正在使用什么样的命名风格，而不考虑他们为什么使用。
以下是常见的命名方式：

• b（单个小写字母）
• B（单个大写字母）
• lowercase 小写字母
• lower_case_with_underscores 使用下划线分隔的小写字母
• UPPERCASE 大写字母
• UPPER_CASE_WITH_UNDERSCORES 使用下划线分隔的大写字母
• CapitalizedWords（或者叫 CapWords，或者叫CamelCase 驼峰命名法 —— 这么命名是因为字母看上去有起伏的外观）。有时候也被称为StudlyCaps。
  注意：当在首字母大写的风格中用到缩写时，所有缩写的字母用大写，因此，HTTPServerError 比 HttpServerError 好。
• mixedCase（不同于首字母大写，第一个单词的首字母小写）
• Capitalized_Words_With_Underscores（巨丑无比！）

也有用唯一的短前缀把相关命名组织在一起的方法。这在Python中不常用，但还是提一下。比如，os.stat()函数中包含类似以st_mode，st_size，st_mtime这种传统命名方式命名的变量。（这么做是为了与 POSIX 系统的调用一致，以帮助程序员熟悉它。）

X11库的所有公共函数都加了前缀X。在Python里面没必要这么做，因为属性和方法在调用的时候都会用类名做前缀，函数名用模块名做前缀。
另外，下面这种用前缀或结尾下划线的特殊格式是被认可的（通常和一些约定相结合）：

• _single_leading_underscore：（单下划线开头）弱“内部使用”指示器。比如 from M import * 是不会导入以下划线开始的对象的。
• single_trailing_underscore_：（单下划线结尾）这是避免和Python内部关键词冲突的一种约定，比如：Tkinter.Toplevel(master, class_=’ClassName’)
• __double_leading_underscore：（双下划线开头）当这样命名一个类的属性时，调用它的时候名字会做矫正（在类FooBar中，__boo变成了_FooBar__boo；见下文）。
• __double_leading_and_trailing_underscore__：（双下划线开头，双下划线结尾）“magic”对象或者存在于用户控制的命名空间内的属性，例如：__init__,__import__或者__file__。除了作为文档之外，永远不要命这样的名。

约定俗成：命名约定

应避免的名字

永远不要使用字母‘l’（小写的L），‘O’（大写的O），或者‘I’（大写的I）作为单字符变量名。
在有些字体里，这些字符无法和数字0和1区分，如果想用‘l’，用‘L’代替。

包名和模块名

模块应该用简短全小写的名字，如果为了提升可读性，下划线也是可以用的。Python包名也应该使用简短全小写的名字，但不建议用下划线。
当使用C或者C++编写了一个依赖于提供高级（更面向对象）接口的Python模块的扩展模块，这个C/C++模块需要一个下划线前缀（例如：_socket）

　类名

类名一般使用首字母大写的约定。
在接口被文档化并且主要被用于调用的情况下，可以使用函数的命名风格代替。
注意，对于内置的变量命名有一个单独的约定：大部分内置变量是单个单词（或者两个单词连接在一起），首字母大写的命名法只用于异常名或者内部的常量。

异常名

因为异常一般都是类，所有类的命名方法在这里也适用。然而，你需要在异常名后面加上“Error”后缀（如果异常确实是一个错误）。

全局变量名

（我们希望这一类变量只在模块内部使用。）约定和函数命名规则一样。
通过 from M import * 导入的模块应该使用all机制去防止内部的接口对外暴露，或者使用在全局变量前加下划线的方式（表明这些全局变量是模块内非公有）。

函数名

函数名应该小写，如果想提高可读性可以用下划线分隔。
大小写混合仅在为了兼容原来主要以大小写混合风格的情况下使用（比如 threading.py），保持向后兼容性。

函数和方法参数

始终要将 self 作为实例方法的的第一个参数。
始终要将 cls 作为类静态方法的第一个参数。
如果函数的参数名和已有的关键词冲突，在最后加单一下划线比缩写或随意拼写更好。因此 class_ 比 clss 更好。（也许最好用同义词来避免这种冲突）

方法名和实例变量

遵循这样的函数命名规则：使用下划线分隔小写单词以提高可读性。
在非共有方法和实例变量前使用单下划线。
通过双下划线前缀触发Python的命名转换规则来避免和子类的命名冲突。
Python通过类名对这些命名进行转换：如果类 Foo 有一个叫 __a 的成员变量， 它无法通过 Foo.__a 访问。（执着的用户可以通过 Foo._Foo__a 访问。）一般来说，前缀双下划线用来避免类中的属性命名与子类冲突的情况。
注意：关于__names的用法存在争论（见下文）。

常量

常量通常定义在模块级，通过下划线分隔的全大写字母命名。例如： MAX_OVERFLOW 和 TOTAL。

参考

---

1. 挂行缩进是一种类型设置样式，其中除第一行之外，段落中的所有行都缩进。在Python中，这个术语是用来描述一种风格：在被括号括起来的语句中，左括号是这一行最后一个非空格字符，随后括号内的内容每一行进行缩进，直到遇到右括号 ↩