Python pep8编码规范

 

1.代码布局

1.1 缩进

每个缩进级别使用4个空格。

1.1.1 对齐缩进

1.1.2 悬挂缩进

1.1.3 层级缩进

 

1.2 制表符还是空格？

1）空格是首选的缩进方法。

2）制表符应仅用于与已使用制表符缩进的代码保持一致。

3）Python 3 不允许混合使用制表符和空格进行缩进。

4）使用制表符和空格混合缩进的 Python 2 代码应转换为仅使用空格。

5）使用-t选项调用 Python 2 命令行解释器时，它会发出有关非法混合制表符和空格的代码的警告。使用-tt 时，这些警告会变成错误。

 

1.3 最大限长

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

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

3）包装长行的首选方法是在括号、方括号和大括号内使用 Python 的隐含行续行。通过将表达式括在括号中，可以将长行分成多行。这些应该优先于使用反斜杠进行行延续。

 

1.4应该在二元运算符之前还是之后换行？

在 Python 代码中，只要约定在本地保持一致，就可以在二元运算符之前或之后中断。对于新代码，建议使用在运算符之前换行。

 

 

1.5 空行

1）顶层函数和类定义，间隔两个空行。

2）类里的方法定义，间隔一个空行。

 

1.6 源文件编码

核心 Python 发行版中的代码应始终使用 UTF-8（或 Python 2 中的 ASCII）。

 

1.7 导入

1）导入通常应该在单独的行上。

2）导入总是放在文件的顶部，就在任何模块注释和文档字符串之后，以及模块全局变量和常量之前。

3）导入应按以下顺序分组：

标准库导入。

相关的第三方进口。

本地应用程序/库特定的导入。

应该在每组导入之间放置一个空行。

4）推荐使用绝对导入，因为如果导入系统配置不正确（例如当包内的目录最终位于sys.path 上时），它们通常更具可读性并且往往表现更好（或至少给出更好的错误消息）。

Import os

From module import test

5）应该避免通配符导入（from <module> import *）。

 

1.8 字符串的引号

在 Python 中，单引号字符串和双引号字符串是一样的。本 PEP 不对此提出建议。选择一条规则并坚持下去。但是，当字符串包含单引号或双引号字符时，请使用另一个字符以避免字符串中出现反斜杠。它提高了可读性。

 

2.注释

2.1 注意事项

1）与代码矛盾的注释比没有注释更糟糕。当代码更改时，始终优先保持注释是最新的！

2）评论应该是完整的句子。第一个单词应该大写，除非它是以小写字母开头的标识符（永远不要改变标识符的大小写！）。

3）块注释通常由一个或多个由完整句子构成的段落组成，每个句子以句号结尾。

4）在多句评论中，句末句号后应使用两个空格，最后一句后除外。

5）确保您的评论清晰易懂，而且您所用语言的其他使用者也能轻松理解。

6）来自非英语国家的 Python 编码员：请用英语写下您的评论，除非您 120% 确定不会说您的语言的人永远不会阅读代码。

 

2.2 块注释

1）块注释通常适用于它们后面的一些（或全部）代码，并且缩进到与该代码相同的级别。块注释的每一行都以#和一个空格开头（除非它是注释内的缩进文本）。

2）块注释内的段落由包含单个#的行分隔。

 

2.3 内嵌注释

1）谨慎使用内联注释。

2）内联注释是与语句在同一行的注释。内联注释应与语句之间至少用两个空格隔开。它们应该以 # 和一个空格开头。

 

2.3 文档字符串

1）为所有公共模块、函数、类和方法编写文档字符串。非公共方法不需要文档字符串，但您应该有一个注释来描述该方法的作用。此注释应出现在def行之后。

2）PEP 257描述了良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的"""应该单独在一行上。

3）对于单行文档字符串，请在同一行上保留结尾的"""

 

3.命名约定

3.1 要避免的名字

1）切勿使用字符“l”（小写字母 el）、“O”（大写字母 oh）或“I”（大写字母 eye）作为单字符变量名。

2）在某些字体中，这些字符与数字一和零无法区分。当想要使用“l”时，请改用“L”。

 

3.2 包和模块名称

1）模块应该有简短的全小写名称。如果可以提高可读性，可以在模块名称中使用下划线。Python 包也应该有简短的、全小写的名称，但不鼓励使用下划线。

2）当用 C 或 C++ 编写的扩展模块附带提供更高级别（例如，更面向对象）接口的 Python 模块时，C/C++ 模块具有前导下划线（例如_socket）。

 

3.3 类名

1）类名通常应使用 CapWords 约定。

2）在接口被记录并主要用作可调用的情况下，可以使用函数的命名约定。

3）请注意，内置名称有一个单独的约定：大多数内置名称是单个单词（或两个单词一起运行），CapWords 约定仅用于异常名称和内置常量。

 

3.4 类型变量名

PEP 484 中引入的类型变量的名称通常应使用 CapWords 首选短名称：T、AnyStr、Num。建议在用于声明协变或逆变行为的变量中相应添加后缀_co或_contra。

 

3.5 异常名称

因为异常应该是类，类命名约定在这里适用。但是，您应该在异常名称上使用后缀“Error”（如果异常实际上是错误）。

 

3.6 全局变量名

1）（让我们希望这些变量仅用于在一个模块内使用。）这些约定与函数的约定大致相同。

2）设计为通过from M import *使用的模块应该使用__all__机制来防止导出全局变量，或者使用旧的约定，在此类全局变量前面加上下划线（您可能想要这样做以表明这些全局变量是“模块非公开的”） ”）。

 

3.7 函数名和变量名

1）函数名应该是小写的，单词之间用下划线分隔以提高可读性。

2）变量名遵循与函数名相同的约定。

3）mixCase 只允许在已经是流行风格的上下文中（例如 threading.py），以保持向后兼容性。

 

3.8 函数和方法参数

1）始终使用self作为实例方法的第一个参数。

2）始终使用cls作为类方法的第一个参数。

3）如果函数参数的名称与保留关键字发生冲突，通常最好附加一个尾随下划线，而不是使用缩写或拼写错误。因此class_比clss 好。（也许更好的是通过使用同义词来避免这种冲突。）

 

3.9 方法名称和实例变量

1）使用函数命名规则：小写，必要时用下划线分隔单词以提高可读性。

2）仅对非公共方法和实例变量使用一个前导下划线。

3）为避免与子类发生名称冲突，请使用两个前导下划线来调用 Python 的名称修改规则。

4）Python 使用类名修改这些名称：如果类 Foo 具有名为__a的属性，则Foo.__a无法访问它。（坚持的用户仍然可以通过调用Foo._Foo__a获得访问权限。）通常，双前导下划线应该只用于避免与设计为子类化的类中的属性发生名称冲突。

 

3.10 常数

常量通常在模块级别定义，并以所有大写字母书写，下划线分隔单词。示例包括 MAX_OVERFLOW和TOTAL。

 

3.11 为继承而设计

1）公共属性不应有前导下划线。

2）如果您的公共属性名称与保留关键字相冲突，请在您的属性名称后添加一个尾随下划线。这比缩写或拼写错误更可取。（然而，尽管有这个规则，对于已知是类的任何变量或参数，尤其是类方法的第一个参数，'cls' 是首选拼写。）

3）对于简单的公共数据属性，最好只公开属性名称，而不是复杂的访问器/修改器方法。请记住，如果您发现一个简单的数据属性需要增加功能行为，那么 Python 提供了一条通往未来增强的简单途径。在这种情况下，使用属性将功能实现隐藏在简单的数据属性访问语法后面。

4）如果您的类打算成为子类，并且您有不希望子类使用的属性，请考虑使用双前导下划线而不是尾随下划线命名它们。这会调用 Python 的名称修改算法，其中类的名称被修改为属性名称。如果子类无意中包含具有相同名称的属性，这有助于避免属性名称冲突。

 

4.公共和内部接口

1）任何向后兼容性保证仅适用于公共接口。因此，重要的是用户能够清楚地区分公共接口和内部接口。

2）文档化的接口被认为是公共的，除非文档明确声明它们是临时或内部接口，免于通常的向后兼容性保证。所有未记录的接口都应假定为内部接口。

3）为了更好地支持自省，模块应该使用__all__属性在其公共 API 中显式声明名称。将__all__设置 为空列表表示该模块没有公共 API。

4）即使适当地设置了__all__，内部接口（包、模块、类、函数、属性或其他名称）仍应以单个前导下划线作为前缀。

5）如果任何包含的命名空间（包、模块或类）被视为内部接口，则接口也被视为内部接口。

6）导入的名称应始终被视为实现细节。其他模块不得依赖于对此类导入名称的间接访问，除非它们是包含模块 API 的明确记录部分，例如os.path或从子模块公开功能的包的__init__模块。

 

5.编程建议

• 代码的编写方式不应损害 Python 的其他实现（PyPy、Jython、IronPython、Cython、Psyco 等）。
• 与像 None 这样的单例的比较应该总是用is或is not来完成， 而不是等号运算符。
• 使用is not运算符而不是not ... is。虽然这两个表达式在功能上是相同的，但前者更具可读性和首选。
• 在实现具有丰富比较的排序操作时，最好实现所有六个操作（__eq__、__ne__、 __lt__、__le__、__gt__、__ge__），而不是依赖其他代码来仅执行特定的比较。
• 始终使用 def 语句而不是将 lambda 表达式直接绑定到标识符的赋值语句。
• 从Exception而不是BaseException派生异常。从BaseException直接继承是为异常保留的，在这些异常中捕获它们几乎总是错误的做法。
• 适当地使用异常链。在 Python 3 中，“raise X from Y”应该用于指示显式替换而不丢失原始回溯。
• 在 Python 2 中引发异常时，使用raise ValueError('message') 而不是旧形式raise ValueError, 'message'。
• 在捕获异常时，尽可能提及特定的异常，而不是使用一个空的except:子句。
• 当绑定捕获到名称的异常时，更喜欢在 Python 2.6 中添加的显式名称绑定语法。
• 在捕获操作系统错误时，与errno 值的内省相比，更喜欢 Python 3.3 中引入的显式异常层次结构。
• 对于所有 try/except 子句，将try子句限制为所需的绝对最少代码量。
• 当资源是特定代码段的本地资源时，请使用 with语句以确保在使用后及时可靠地清理资源。try/finally 语句也是可以接受的。
• 上下文管理器在执行除获取和释放资源之外的其他操作时，应通过单独的函数或方法调用。
• 在 return 语句中保持一致。函数中的所有 return 语句都应该返回一个表达式，或者它们都不应该返回。如果任何 return 语句返回一个表达式，则任何没有返回值的return 语句都应将其显式声明为return None，并且应在函数末尾出现显式 return 语句（如果可访问）。
• 使用字符串方法而不是字符串模块。
• 使用''.startswith()和''.endswith()而不是字符串切片来检查前缀或后缀。
• 对象类型比较应始终使用 isinstance() 而不是直接比较类型。
• 对于序列（字符串、列表、元组），使用空序列为假的事实。
• 不要编写依赖重要尾随空格的字符串文字。这种尾随空白在视觉上无法区分，一些编辑器（或最近的 reindent.py）会修剪它们。
• 不要使用==将布尔值与 True 或 False 进行比较。
• 不鼓励在try...finally 的 finally 套件中使用流控制语句return / break / continue，其中流控制语句会跳到 finally 套件之外。这是因为此类语句将隐式取消通过 finally 套件传播的任何活动异常。

 

6.变量注释

1）模块级变量、类和实例变量以及局部变量的注释应该在冒号后有一个空格。

2）冒号前不应该有空格。

3）如果赋值有右手边，那么等号两边应该正好有一个空格：