Python代码风格：PEP8规则 笔记

Python程序设计的代码风格应该遵循PEP8规则：

一、代码布局

1、缩进：

每级缩进4个空格，不能用Tab，更不能空格Tab混用

1、续行应该与其包裹元素对齐，要么使用圆括号、方括号和花括号内的隐式行连接来垂直对齐，要么使用悬挂式缩进对齐。当使用悬挂缩进时，应该考虑到第一行不应该有参数，以及使用缩进以区分自己是续行。

2、缩进4个空格的规则对于续行是可选的。

3、当 if 语句的条件部分长到需要换行写的时候，注意可以在两个字符关键字的连接处（比如 if ），增加一个空格，再增加一个左括号来创造一个4空格缩进的多行条件。这会与 if 语句内同样使用4空格缩进的代码产生视觉冲突。PEP没有明确指明要如何区分i发的条件代码和内嵌代码。可使用的选项包括但不限于下面几种情况：

4、（可以参考下面关于是否在二进制运算符之前或之后截断的讨论）

在多行结构中的大括号/中括号/小括号的右括号可以与内容对齐单独起一行作为最后一行的第一个字符，如：

或者也可以与多行结构的第一行第一个字符对齐，如：

2、Tab还是空格？

空格是被首先推荐的缩进方式。

Tab应该只在现有代码已经使用tab进行缩进的情况下使用，以便和现有代码保持一致。

Python 3不允许再同一个代码块中Tab和空格混合使用。

混合使用制表符和空格缩进的Python2代码应该统一转成空格。

使用命令行运行Python 2时，使用-t选项，会出现非法混用tab和空格的警告。当使用-tt选项时，这些警告会变成错误。强烈推荐使用这些选项！

3、最大行长

每行最大长度79个字符。

对于连续大段的文字（比如文档字符串(docstring)或注释），每行应该被限制在72个字符长度内。

Python标准库比较传统，将行长限制在79个字符以内（文档字符串/注释为72个字符）。

一种推荐的换行方式是利用Python圆括号、方括号和花括号中的隐式续行。长行可以通过在括号内换行来分成多行。应该最好加上反斜杠来区别续行。

有时续行只能使用反斜杠才。例如，较长的多个 with 语句不能采用隐式续行，只能接受反斜杠表示换行：

另一个这样的例子是assert语句。要确保续行的缩进适当。

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

遵循数学的传统能产出更多可读性高的代码：

4、空行

顶层函数和类的定义，前后用两个空行隔开。

类里的方法定义用一个空行隔开。

相关的功能组可以用额外的空行（尽量少地）隔开。一堆相关的单行代码之间的空白行可以省略（例如，一组虚拟实现 dummy implementations）。

在函数中使用空行来区分逻辑段（尽量少地）。

Python接受control-L（即^L）换页符作为空格；许多工具把这些字符当作页面分隔符，所以你可以在文件中使用它们来分隔相关段落。请注意，一些编辑器和基于Web的代码阅读器可能无法识别control-L为换页，将在其位置显示另一个字形。

5、源文件编码

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

使用ASCII（Python 2）或者UTF-8（Python 3）的文件不应该添加编码声明。

在标准库中，只有用作测试目的，或者注释或文档字符串需要提及作者名字而不得不使用非ASCII字符时，才能使用非默认的编码。否则，在字符串文字中包括非ASCII数据时，推荐使用\x, \u, \U或\N等转义符。

对于Python 3.0及其以后的版本中，标准库遵循以下原则（参见PEP 3131）：Python标准库中的所有标识符都必须只采用ASCII编码的标识符，在可行的条件下也应当使用英文词（很多情况下，使用的缩写和技术术语词都不是英文）。此外，字符串文字和注释应该只包括ASCII编码。只有两种例外：

(a) 测试情况下为了测试非ASCII编码的特性

(b) 作者名字。作者名字不是由拉丁字母组成的也必须提供一个拉丁音译名。

鼓励面向全球的开源项目都采用类似的原则。

6、导入

1、imports应该分行写，而不是都写在一行，例如：

这样写也是可以的：

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

导入顺序如下：

imports应该按照下面的顺序分组来写：

1、标准库imports

2、相关第三方imports

3、本地应用/库的特定imports

不同组的imports之前用空格隔开。

将任何相关的 __all__ 说明(specification)放在imports之后。

推荐使用绝对(absolute)imports，因为这样通常更易读，在import系统没有正确配置的情况下，也会有更好的表现（或者至少会给出错误信息）：

在绝对路径比较长的情况下，也可以使用相对导入：

Python 3中已经禁止隐式的相对导入。

导入类的方法，通常可以这样写：

如果和本地命名的拼写产生了冲突，应当使用绝对导入：

禁止使用通配符导入。

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

7、模块中前后具有双下划线的变量名

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

比如：

二、字符串引号

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

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

三、表达式和语句中的空格

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

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

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

3、然而，冒号在切片中就像二元运算符，在两边应该有相同数量的空格（把它当做优先级最低的操作符）。在扩展的切片操作中，所有的冒号必须有相同的间距。例外情况：当一个切片参数被省略时，空格就被省略了。

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

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

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

其他建议

1、避免在尾部添加空格。因为尾部的空格通常都看不见，会产生混乱：比如，一个反斜杠后面跟一个空格的换行符，不算续行标记。有些编辑器不会保留尾空格，并且很多项目（像CPython）在pre-commit的挂钩调用中会过滤掉尾空格。

总是在二元运算符两边加一个空格：赋值（=），增量赋值（+=，-=），比较（==,,!=,,=,in,not,in,is,is not），布尔（and, or, not）。

如果使用具有不同优先级的运算符，请考虑在具有最低优先级的运算符周围添加空格。有时需要通过自己来判断；但是，不要使用一个以上的空格，并且在二元运算符的两边使用相同数量的空格。

2、在指定函数 关键字参数 或者 默认参数 值的时候，不要在=附近加上空格。

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

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

5、复合语句(同一行中的多个语句)通常是不允许的。

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

四、注释

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

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

如果注释很短，可以省略末尾的句号。注释块通常由一个或多个段落组成。段落由完整的句子构成且每个句子应该以点号(后面要有两个空格)结束，并注意断词和空格。

非英语国家的程序员请用英语书写你的注释，除非你120%确信代码永远不会被不懂你的语言的人阅读。

1、注释块

注释块通常应用在代码前，并和这些代码有同样的缩进。每行以 '# '(除非它是注释内的缩进文本，注意#后面有空格)。

注释块内的段落用仅包含单个 '#' 的行分割。

2、行内注释

慎用行内注释(Inline Comments) 节俭使用行内注释。 行内注释是和语句在同一行，至少用两个空格和语句分开。行内注释不是必需的，重复罗嗦会使人分心。

不推荐：

但是有时，很有必要：

加了以后对理解代码很有帮助的情况下，关键处才加。

3、文档字符串

文档字符串的标准参见：PEP 257。

为所有公共模块、函数、类和方法书写文档字符串。非公开方法不一定有文档字符串，建议有注释(出现在 def 行之后)来描述这个方法做什么。

更多参考：PEP 257 文档字符串约定。注意结尾的 """ 应该单独成行，例如：

单行的文档字符串，结尾的 """ 在同一行。

4、版本标签

如果你必须在源文件中包含git、Subversion、CVS或RCS crud信息，放置在模块的文档字符串之后，任何其他代码之前，上下各用一个空行：

五、命名规范

Python库的命名约定有点混乱，不可能完全一致。但依然有些普遍推荐的命名规范的。新的模块和包 (包括第三方的框架) 应该遵循这些标准。对不同风格的已有的库，建议保持内部的一致性。

1、最重要的原则

用户可见的API命名应遵循使用约定而不是实现。

2、命名风格

以下是常见的命名方式：

b（单个小写字母）

B（单个大写字母）

lowercase （小写字母）

lower_case_with_underscores （使用下划线分隔的小写字母）

UPPERCASE（ 大写字母）

UPPER_CASE_WITH_UNDERSCORES （使用下划线分隔的大写字母）

CapitalizedWords（首字母大写的单词串或驼峰缩写）

注意: 使用大写缩写时，缩写使用大写字母更好。故 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关键词的冲突。 例如：

__double_leading_underscore(双前置下划线): 当用于命名类属性，会触发名字重整。 (在类FooBar中，__boo变成 _FooBar__boo)。

__double_leading_and_trailing_underscore__(双前后下划线)：用户名字空间的魔法对象或属性。例如:__init__ , __import__ or __file__，不要自己发明这样的名字。

3、命名约定规范

避免采用的名字：

决不要用字符'l'(小写字母el)，'O'(大写字母oh)，或 'I'(大写字母eye) 作为单个字符的变量名。一些字体中，这些字符不能与数字1和0区别。用'L' 代替'l'时。

包和模块名：

模块名要简短，全部用小写字母，可使用下划线以提高可读性。包名和模块名类似，但不推荐使用下划线。

模块名对应到文件名，有些文件系统不区分大小写且截短长名字，在 Unix上不是问题，但当把代码迁移到 Mac、Windows 或 DOS 上时，就可能是个问题。当然随着系统的演进，这个问题已经不是经常出现。

另外有些模块底层用C或C++ 书写，并有对应的高层Python模块，C/C++模块名有一个前置下划线 (如：_socket)。

类名：

遵循CapWord。

接口需要文档化并且可以调用时，可能使用函数的命名规则。

注意大部分内置的名字是单个单词（或两个），CapWord只适用于异常名称和内置的常量。

异常名：

如果确实是错误，需要在类名添加后缀 "Error"。

全局变量名：

变量尽量只用于模块内部，约定类似函数。

对设计为通过 "from M import " 来使用的模块，应采用 __all__ 机制来防止导入全局变量；或者为全局变量加一个前置下划线。

函数名：

函数名应该为小写，必要时可用下划线分隔单词以增加可读性。 mixedCase(混合大小写)仅被允许用于兼容性考虑(如: threading.py)。

函数和方法的参数：

实例方法第一个参数是 'self'。

类方法第一个参数是 'cls'。

如果函数的参数名与保留关键字冲突，通常在参数名后加一个下划线。

方法名和实例变量：

同函数命名规则。

非公开方法和实例变量增加一个前置下划线。

为避免与子类命名冲突，采用两个前置下划线来触发重整。类Foo属性名为__a， 不能以 Foo.__a访问。(执著的用户还是可以通过Foo._Foo__a。) 通常双前置下划线仅被用来避免与基类的属性发生命名冲突。

常量：

常量通常在模块级定义,由大写字母用下划线分隔组成。比如括MAX_OVERFLOW和TOTAL。

继承设计：

考虑类的方法和实例变量(统称为属性)是否公开。如果有疑问，选择不公开；把其改为公开比把公开属性改为非公开要容易。

公开属性可供所有人使用，并通常向后兼容。非公开属性不给第三方使用、可变甚至被移除。

这里不使用术语"private"， Python中没有属性是真正私有的。

另一类属性是子类API(在其他语言中通常称为 "protected")。 一些类被设计为基类，可以扩展和修改。

谨记这些Python指南：

1、公开属性应该没有前导下划线。

2、如果公开属性名和保留关键字冲突，可以添加后置下划线

3、简单的公开数据属性，最好只公开属性名，没有复杂的访问/修改方法，python的Property提供了很好的封装方法。 d.如果不希望子类使用的属性，考虑用两个前置下划线(没有后置下划线)命名。

公共和内部接口：

任何向后兼容的保证只适用于公共接口。

文档化的接口通常是公共的，除非明说明是临时的或为内部接口、其他所有接口默认是内部的。

为了更好地支持内省，模块要在__all__属性列出公共API。

内部接口要有前置下划线。

如果命名空间(包、模块或类)是内部的，里面的接口也是内部的。

导入名称应视为实现细节。其他模块不能间接访名字，除非在模块的API文档中明确记载，如os.path中或包的__init__暴露了子模块。

六、 编程建议

1、考虑多种Python实现(PyPy, Jython, IronPython,Pyrex, Psyco, 等等)。

例如，CPython对a+=b或a=a+b等语句有高效的实现，但在Jython中运行很慢，尽量改用.join()。

2、None比较用'is'或'is not'，不要用等号。

注意"if x is not None" 与"if x" 的区别。

3、用"is not"代替"not ... is"。前者的可读性更好。

4、使用基于类的异常。

比较排序操作最好是实现所有六个操作 (__eq__, __ne__, __lt__, __le__, __gt__, __ge__) ，而不是代码中实现比较逻辑。functools.total_ordering()装饰符可以生成缺失的比较方法。

PEP207 比较标准表明反射规则由Python完成。因此解释器可能会交换参数的位置，比如替换y > x为x

5、使用函数定义def代替lambda赋值给标识符

前者更适合回调和字符串表示。

6、异常类继承自Exception，而不是BaseException。

源于异常，而不是BaseException例外。从BaseException直接继承的例外情况追赶他们几乎总是错误的事情做保留。

要设计基于层次的异常，捕捉到需要的异常，而不是异常引发的位置。能回答：“出了什么问题？”，而不是仅仅指出“问题发生”(更多参考：PEP3151 重构OS和IO异常层次）

7、适当使用异常链。在Python3中"raise X from Y"明确表示更换且保留了原来的traceback。

替换内部异常(在Python2: "raise X"或"raise X from None")时，确保相关细节转移到新的异常（如转换KeyError为AttributeError保存属性名，或在新的异常中嵌入原始异常)。

8、Python2中用" raise ValueError('message')"代替"raise ValueError, 'message'"

后者不兼容Python3语法。前者续行方便。

9、捕获异常时尽量指明具体异常，而不是空"except:"子句。比如：

空"except:"子句(相当于except Exception)会捕捉SystemExit和KeyboardInterrupt异常，难以用Control-C中断程序，并可掩盖其他问题。如果 你捕捉信号错误之外所有的异常，使用"except Exception"。

空"except:"子句适用的情况两种情况：

a, 打印出或记录了traceback，至少让用户将知道已发生错误。

b, 代码需要做一些清理工作，并用 raise转发了异常。这样try...finally可以捕捉到它。

10、Python 2.6以后建议用as显示绑定异常名

这样才能兼容Python3语法并避免歧义。

11、捕捉操作系统错误时，建议使用Python 3.3引入显式异常层次，支持内省errno值。

12、此外所有try/except子句的代码要尽可的少，以免屏蔽其他的错误。

13、本地资源建议使用with语句，以确保即时清理。当然try / finally语句也是可以接受的。

14、上下文管理器在做获取和释放资源之外的事情时，应通过独立的函数或方法。例如：

后者指明enter和exit方法。

15、函数或者方法在没有返回时要明确返回None

16、使用字符串方法而不是string模块。

python 2.0以后字符串方法总是更快，且Unicode字符串相同的API。

17、使用使用 .startswith()和.endswith()代替字符串切片来检查前缀和后缀。and

startswith()和endswith更简洁，利于减少错误。例如：

18、使用isinstance()代替对象类型的比较

检查是否是字符串时，注意Python 2中str和unicode有公共的基类:

if isinstance(obj, basestring): 在 Python 2.2 中，types 模块为此定义了 StringTypes 类型，例如：

Python3中Unicode和basestring的不再存在(只有str)和字节对象不再是字符串(是整数序列)

19、对序列(字符串、列表 、元组), 空序列为 false

20、字符串后面不要有大量拖尾空格。

21、不要用 == 进行布尔比较

七、参考

[1]PEP 7, Style Guide for C Code, van Rossum

[2]Barry's GNU Mailman style guide http://barry.warsaw.us/software/STYLEGUIDE.txt

[3]Donald Knuth's The TeXBook, pages 195 and 196.

[4]http://www.wikipedia.com/wiki/CamelCase

[5]Typeshed repo https://github.com/python/typeshed

[6]Suggested syntax for Python 2.7 and straddling code https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code

八、版权

This document has been placed in the public domain.