缩进

一般默认使用4个空格，不是tab键

在一个语句需要放在多行来写时，需要缩进

# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# No extra indentation.
if (this_is_one_thing and
    that_is_another_thing):
    do_something()

# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
    that_is_another_thing):
    # Since both conditions are true, we can frobnicate.
    do_something()

# Add some extra indentation on the conditional continuation line.
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',
)

tab和space

空格优先，tab只在已经使用了tab缩进时才使用，不要混合tab和空格

单行的最大长度

单行的合适长度是79

文档注释docstring和评论comment最长是72

单行的最大长度是99

换行的最优方式是在括号中的隐式连续行，当然对于with结构（assert）结构可以使用反斜杠来换行。

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

二元操作符前后的换行

# Wrong:
# operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)


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

前后两种方式都允许，但是第二种会更可读一点

blank lines

类，函数前后两个空行

类中方法前后一个空行

Extra blank lines may be used (sparingly) to separate groups of related functions. Blank lines may be omitted between a bunch of related one-liners (e.g. a set of dummy implementations).

Use blank lines in functions, sparingly, to indicate logical sections.

Python accepts the control-L (i.e. ^L) form feed character as whitespace; many tools treat these characters as page separators, so you may use them to separate pages of related sections of your file. Note, some editors and web-based code viewers may not recognize control-L as a form feed and will show another glyph in its place.

Source File 编码

核心Python发行版中的代码应该始终使用UTF-8，并且不应该有编码声明。

在标准库中，非utf-8编码应该仅用于测试目的。限制使用非ascii字符，最好只用于表示地名和人名。如果使用非ascii字符作为数据，则避免嘈杂的Unicode字符。

Python标准库中的所有标识符都必须使用仅限ascii的标识符，并且应该尽可能使用英语单词(在许多情况下，使用的缩写和技术术语不是英语)。

鼓励面向全球的开源项目采用类似的政策。

imports

• 书写规范

导入不同模块，需要分行

# Correct:
import os
import sys

导入同一模块下的不同内容，可以from

# Correct:
from subprocess import Popen, PIPE

• 导入顺序

在模块的说明之后，模块的全局变量和常量之前书写import语句，导入顺序为：

1. Standard library imports.
2. Related third party imports.
3. Local application/library specific imports.

• 导入方法

  • 绝对方法：需要知道模块名，标准库应该避免复杂的包layout，只能用绝对导入方法。

        import mypkg.sibling
        from mypkg import sibling
        from mypkg.sibling import example

  • 相对方法：explicit relative imports are an acceptable alternative to absolute imports, especially when dealing with complex package layouts where using absolute imports would be unnecessarily verbose

        from . import sibling
        from .sibling import example

  • 冲突：导入模块中的类与已有类冲突，则可以只导入模块，使用模块名.类名的方式调用类。

        import myclass
        import foo.bar.yourclass        

Module Level Dunder Names

Module level “dunders” (i.e. names with two leading and two trailing underscores) such as all, author, version, etc. should be placed after the module docstring but before any import statements except from future imports.

python要求future-import之类的语句必须在除docstring之外的语句之前，如import __future__,

pet peeves（a frequent subject of complaint）

以下情形需要避免多余的空格

括号，中括号，大括号中的元素应该立即书写。

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

在trailing comma和closing paranthesis之间

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

紧靠在逗号，分号，冒号之前

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

紧靠在函数调用参数列表开始的左括号之前:

# Correct:
spam(1)
# Wrong:
spam (1)

紧靠在进行切片或index时的左括号之前：

# Correct:
dct['key'] = lst[index]
# Wrong:
dct ['key'] = lst [index]

不要为了对齐操作符而让赋值操作符两侧出现超过一个的空格

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

exception

但是在切片中，冒号其实相当于二元操作符，需要在左右两边保持相同的空格数，但是一个slice后面的参数消失时，就不应该有空格，

也就是要不然没有空格，要不然参数和冒号之间都要有空格

# 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]

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

# Correct:
def complex(real, imag=0.0):
    return magic(r=real, i=imag)
# Correct:
def munge(sep: AnyStr = None): ...
def munge(input: AnyStr, sep: AnyStr = None, limit=1000): 

block comments

用于之后的一些或所有代码，并且和之后的代码保持统一层级。

块注释通常由一个或多个由完整句子构成的段落组成，每个句子都以句号结尾。在多句注释中，除了最后一句之外，句尾的句号后面应该有两个空格。

以#号加空格开头，用单独的一行写一个#号来区分两个段落。

inline comments

不必要，注意不要分散了代码的注意力，但是有时候也能起到解释的作用。

Document strings

Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the def line.

PEP 257 describes good docstring conventions. Note that most importantly, the ““” that ends a multiline docstring should be on a line by itself:

"""Return a foobang

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

For one liner docstrings, please keep the closing ““” on the same line:

"""Return an ex-parrot."""

一个docstring是一个stringliteral，作为模块、函数、类或者方法定义的第一个陈述。这样一个docstring就成为了一个对象的特殊属性__doc__。

所有的模块应该有docstrings，所有由模块输出的函数和类都应该有docstrings。公共方法（包括__init__构造器）也应该有docstrings。一个包可能由包目录下面的__init__.py文件里面模块docstring归档。

为了一致性，一直使用"""三双引号"""来写docstrings。如果在docstrings里面使用任意的反斜杠，用r"""raw triple double quotes"""。如果用Unicode docstrings，用u"""Unicode triple-quoted strings"""。

有两种形式的docstrings，一种是单行docstrings，另一种是多行docstrings。

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    ...
    

def complex(real=0.0, imag=0.0):
    """Form a complex number
    
    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
 
    if imag == 0.0 and real == 0.0:
        return complex_zero
    
    ...

Package and Module Names 包名和模块名

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

Class Names 类名

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

Exception Names 异常名

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

Global Variable Names 全局变量名

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

Function Names 函数名

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

Function and method arguments 函数和方法参数

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

Method Names and Instance Variables 方法名和实例变量

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

Constants 常量

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

Designing for inheritance 继承的设计

始终要考虑到一个类的方法和实例变量（统称：属性）应该是共有还是非共有。如果存在疑问，那就选非共有；因为将一个非共有变量转为共有比反过来更容易。

公共属性是那些与类无关的客户使用的属性，并承诺避免向后不兼容的更改。非共有属性是那些不打算让第三方使用的属性；你不需要承诺非共有属性不会被修改或被删除。

我们不使用“私有（private）”这个说法，是因为在Python中目前还没有真正的私有属性（为了避免大量不必要的常规工作）。

另一种属性作为子类API的一部分（在其他语言中通常被称为“protected”）。有些类是专为继承设计的，用来扩展或者修改类的一部分行为。当设计这样的类时，要谨慎决定哪些属性时公开的，哪些是作为子类的API，哪些只能在基类中使用。

贯彻这样的思想，一下是一些让代码Pythonic的准则：

公共属性不应该有前缀下划线。

如果公共属性名和关键字冲突，在属性名之后增加一个下划线。这比缩写和随意拼写好很多。（然而，尽管有这样的规则，在作为参数或者变量时，’cls’是表示‘类’最好的选择，特别是作为类方法的第一个参数。） 　　　 注意1：参考之前的类方法参数命名建议

如果你的类打算用来继承的话，并且这个类里有不希望子类使用的属性，就要考虑使用双下划线前缀并且没有后缀下划线的命名方式。这会调用Python的命名转换算法，将类的名字加入到属性名里。这样做可以帮助避免在子类中不小心包含了相同的属性名而产生的冲突。

　　　注意1：只有类名才会整合进属性名，如果子类的属性名和类名和父类都相同，那么你还是会有命名冲突的问题。
　　　注意2：命名转换会在某些场景使用起来不太方便，例如调试，__getattr__()。然而命名转换的算法有很好的文档说明并且很好操作。
　　　注意3：不是所有人都喜欢命名转换。尽量避免意外的名字冲突和潜在的高级调用。

Public and internal interfaces 公共和内部的接口

任何向后兼容保证只适用于公共接口，因此，用户清晰地区分公共接口和内部接口非常重要。

文档化的接口被认为是公开的，除非文档明确声明它们是临时或内部接口，不受通常的向后兼容性保证。所有未记录的接口都应该是内部的。

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

即使通过__all__设置过，内部接口（包，模块，类，方法，属性或其他名字）依然需要单个下划线前缀。

如果一个命名空间（包，模块，类）被认为是内部的，那么包含它的接口也应该被认为是内部的。

导入的名称应该始终被视作是一个实现的细节。其他模块必须不能间接访问这样的名称，除非它是包含它的模块中有明确的文档说明的API，例如 os.path 或者是一个包里从子模块公开函数接口的 __init__模块。

参考文献：

pep8官方文档

pep8中文翻译

docstring中文翻译