PEP8 naming conventions | Python

这是一份代码样式指南，帮助规范代码样式并提高代码可读性。
————
文章并不完全，可以直接点击【来源】访问源文件

代码布局

缩进

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

＃与分隔符对齐。
foo = long_function_name（var_one，var_two，
                         var_three，var_four）

＃添加4个空格（额外的缩进级别）以将参数与其余参数区分开。
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）

多行构造的右花括号/括号/括号可以在列表最后一行的第一个非空白字符下对齐，如下所示：

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',
)

制表符或者空格？

空格是首选的缩进方法。

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

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

由制表符和空格组成的缩进的Python 2代码应转换为：仅使用空格。

当使用-t选项调用Python 2命令行解释器时，它会发出有关非法混用制表符和空格的代码的警告。当使用-tt时，这些警告变为错误。强烈建议您使用这些选项！

单行字符长度

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

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

！长行的解决办法
包装长行的首选方法是在括号，方括号和花括号内使用Python的隐含行连续性。通过将表达式包装在括号中，可以将长行分成多行。应优先使用这些，而不是使用反斜线进行行连续。

反斜杠法：有时反斜杠可能仍然合适

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

换行符是在二进制运算符之前还是之后？

！之前。

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

空行

用两个空行（定义之前与定义之后）包围最高级别的函数定义（区别于嵌套等）和类的定义。

类中的方法定义由单个空白行分割。

源代码编码

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

导入 | import

Imports should usually be on separate lines:鼓励使用单行

# Correct:
import os
import sys

# Wrong:
import sys, os

# Correct:
from subprocess import Popen, PIPE

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

导入应按以下顺序分组：
标准库导入。
相关第三方进口。
本地应用程序/库特定的导入。
您应该在每组导入之间放置一个空白行。

模块级Dunder名称

“dunders”（即名称具有两个前下划线和俩后下划线）如__all__，__author__，__version__等应被放置在模块文档字符串之后，但在除__future__导入之外的任何导入语句之前。

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

表达式和语句中的空格等

以下情况请避免出现多余空格：

1. 括号，方括号或大括号内

# Correct:
spam(ham[1], {eggs: 2})
# Wrong:
spam( ham[ 1 ], { eggs: 2 } )

# Correct:
foo = (0,)
# Wrong:
bar = (0, )

3. 在逗号，分号或冒号之前：

# Correct:
if x == 4: print x, y; x, y = y, x
# Wrong:
if x == 4 : print x , y ; x , y = y , x

4. 但是，在切片中，冒号的行为类似于二元运算符，并且在每一侧都应具有相等的数量

# Correct:
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]
# Wrong:
ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : upper]
ham[ : upper]

5. 函数注释

# Correct:
def munge(input: AnyStr): ...
def munge() -> PosInt: ...
# Wrong:
def munge(input:AnyStr): ...
def munge()->PosInt: ...

6. 但是，当将参数注释与默认值组合时，请在=符号周围使用空格：

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

7. 函数参数

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

7. 其他

# Correct:
x = 1
y = 2
long_variable = 3
# Wrong:
x             = 1
y             = 2
long_variable = 3

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

其他

1. 通常不建议使用复合语句

# Correct:
if foo == 'blah':
    do_blah_thing()

# Wrong:
if foo == 'blah': do_blah_thing()

2. 尽管有时可以将if / for / while的小主体放在同一行上，但不意味着多子句语句也可以这样

何时使用尾随逗号

尾部的逗号通常是可选的，除了在只有一个元素的元组里它们是强制性的

# Correct:
FILES = ('setup.cfg',)
# Wrong:
FILES = 'setup.cfg',

在与结束定界符相同的行上加上逗号是没有意义的。

# Correct:
FILES = [
    'setup.cfg',
    'tox.ini',
    ]
initialize(FILES,
           error=True,
           )
           
# Wrong:
FILES = ['setup.cfg', 'tox.ini',]
initialize(FILES, error=True,)

注释

与代码矛盾的注释比没有注释更糟糕。 当代码更改时，始终要始终使注释保持最新状态！

注释应为完整句子。 第一个单词应大写，除非它是一个以小写字母开头的标识符（请勿更改标识符的大小写！）。

整体注释通常由一个或多个完整句子组成的段落组成，每个句子以句点结尾。

在多句注释中，除了最后一句之后，您应该在句子结尾句后使用两个空格。

确保您的注释清晰明了，并且其他母语使用者也很容易理解。

来自非英语国家的Python编码人员：请用英语写您的评论，除非您有120％的把握确保不会说这种语言的人不会阅读该代码。

块注释 | Block Comments

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

块注释中的段落由包含单个＃的行分隔。

内联注释 | Inline Comments

谨慎使用内联注释。

内联注释是与语句在同一行上的注释。

内联注释应与语句至少分隔两个空格。它们应以＃和单个空格开头。

文档字符串 | Documentation Strings

在PEP 257中，编写好的文档字符串（也称为“文档字符串”）的约定不朽。

为所有公共模块，函数，类和方法编写文档字符串。对于非公共方法，文档字符串不是必需的，但是您应该具有描述该方法功能的注释。该注释应出现在def行之后。

PEP 257描述了良好的文档字符串约定。请注意，最重要的是，多行文档字符串结尾的“”应单独位于一行上：

"""Return a foobang

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

命名约定

Python库的命名约定有点混乱，因此我们永远都无法做到完全一致-尽管如此，这是当前推荐的命名标准。新的模块和软件包（包括第三方框架）应按照这些标准编写，但是如果现有库具有不同的样式，则首选内部一致性。

首要原则

对于用户而言，作为API公共部分可见的名称应遵循反映用法而不是实现的约定。

描述性：命名样式

说明性：命名约定

避免使用的名称

切勿将字符“ l”（小写字母el），“ O”（大写字母o）或“ I”（大写字母eye）用作单个字符变量名称。

在某些字体中，这些字符与数字1和0没有区别。当尝试使用“ l”时，请改用“ L”。

ASCII兼容性

标准库中使用的标识符必须 与PEP 3131的策略部分中所述的ASCII兼容 。

软件包和模块名称

模块应使用简短的全小写名称。如果模块名称可以提高可读性，则可以在模块名称中使用下划线。尽管不鼓励使用下划线，但Python软件包也应使用短的全小写名称。

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

类名

类名通常应使用CapWords约定。

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

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

函数和变量名

函数名称应小写，必要时用下划线分隔单词，以提高可读性。

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

函数和方法参数

始终将self作为实例方法的第一个参数。

始终对类方法的第一个参数使用cls。

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

方法名称和实例变量

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

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

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

Python用类名来修饰这些名称：如果类Foo具有名为__a的属性，则Foo .__ a不能访问它。（坚持的用户仍然可以通过调用Foo._Foo__a来获得访问权限。）通常，双引号下划线仅应用于避免名称与设计为子类的类中的属性发生冲突。

常数

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

公共和内部接口

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

除非文档明确声明它们是临时接口或内部接口不受通常的向后兼容性保证，否则已说明文件的接口被视为公共接口。所有未记录的接口都应假定为内部接口。

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

即使正确设置了__all__，内部接口（包，模块，类，函数，属性或其他名称）仍应使用单个下划线作为前缀。

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

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

来源

1. PEP 8 – Style Guide for Python Code | Python.org

2. 版权：该文档已放置在公共区域。