Python代码风格指南&编程规范

1 前言

        纷吾既有此内美兮，又重之以修能。 ---- 屈原《离骚》

 1.1 编写目的

        本文用于指导我司使用python语言进行开发的人员。

1.2 范围

        测试人员、开发人员以及其他python语言使用者。

2 简介

        很多语言都有自己独有的编码风格，python以简洁优美著称，当然也不能例外。如果和本文规则发生任何冲突，请优先与项目级别的代码风格保持一致。代码风格一致性当然重要，想象一下空姐的制服诱惑，是不是赏心悦目呢？但也要有自己的主观判断，不墨守陈规，愚蠢的追求代码一致性，例如有以下的场景：

1、遵循此风格写的一小片代码看起来和项目内其他代码格格不入，看到就想抠出来喂猪，人人见而曰日之。

2、遵循此风格后和其他 python 版本不兼容，甚至出现错误，这就尴尬了。

3、遵循此风格中的某些条目使代码更不易读，简单说就是丑。

3 代码布局

3.1 缩进

        一个缩进级别四个空格。

        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)



否：

# 括号内隐式连接，没有垂直对齐时，第一行的参数被禁止

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)

 

        2.当 if 语句过长时，可选的处理方式，但不限于此：

扫描二维码关注公众号，回复： 4114571 查看本文章

# 不使用额外缩进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()

        3.当闭环括号内元素跨行时，可以采用以下方式。

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

3.2 空格和tab

        Python 3 不允许 tab 和 space 混用，同时混用了 tab 和 space 的 Python 2 代码应该被转换为仅使用 space。

3.3 语句中的空格

        在以下场景避免不必要的空格：

是： spam(ham[1], {eggs: 2})
否： spam( ham[ 1 ], { eggs: 2 } )

是： foo = (0,)
否： bar = (0, )

是： if x == 4: print x, y; x, y = y, x
否： 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]
否：
    ham[lower + offset:upper + offset]
    ham[1: 9], ham[1 :9], ham[1:9 :3]
    ham[lower::upper]
    ham[:upper]
    
是： spam(1)
否： spam (1)

是： dct['key'] = lst[index]
否： dct ['key'] = lst [index]

是：
    x = 1
    y = 2
    long_variable = 3
  
否：
    x             = 1
    y             = 2
    long_variable = 3

        在任何地方避免使用尾随空格。

        在二元运算符周围使用空格：

是：
    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 complex(real, imag = 0.0):
        return magic(r = real, i = imag)

        函数注解的场景：

是：
    def munge(input: AnyStr): ...
    def munge() -> AnyStr: ...
否：
    def munge(input:AnyStr): ...
    def munge()->PosInt: ...

        当参数注释和默认值共存时：

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

        同行多语句不建议使用：

是：
    if foo == 'blah':
        do_blah_thing()
    do_one()
    do_two()
    do_three()
否：
    if foo == 'blah': do_blah_thing()
    do_one(); do_two(); do_three()

        下面这种丑就不多说了：

否：
    if foo == 'blah': do_blah_thing()
    for x in lst: total += x
    while t < 10: t = delay()
否：
    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()

3.4 代码行最大长度

        将所有行限制为最多79个字符。对于具有较少结构限制（文档字符串或注释）的长文本块，行长度应限制为72个字符。当然了，不要问为啥非得是 7972。因为要兼顾非洲大陆人民的生活。代码是全世界的。反斜杠有时可能仍然要用。 例如，又多又长的 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())

assert 语句也是如此。

3.5 运算符前还是后断行?

        算法和程序设计技术先驱，计算机排版系统 TEX 和 METAFONT 的发明者 Donald Knuth，推荐使用以下形式：

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

       只要保持本地一致性，在二元运算符之前和之后断开都是允许的，但是新的 Python 代码推荐使用 Knuth 形式。

3.6 空行

        顶层函数和类定义间使用两个空行。

        类内方法定义间使用一个空行。

       不同函数组之间使用两个空行隔离。

       总之，空行的作用就是隔离不同函数类等，使层次分明。

3.7 源文件编码

       Python 2 默认ASCII，Python 3 默认UTF-8。使用 ASCII 的 Python 2 源文件或使用 UTF-8 的 Python 3 源文件不应该有编码声明。源文件最好只使用 ASCII 字符，即使是蹩脚的 Chinglish 亦可，家和万事兴。

3.8 模块导入

是：
    from subprocess import Popen, PIPE
    import os
    import sys
否：
    import sys, os

        模块导入总是位于文件顶部，在模块注释和文档字符串之后，模块全局变量和常量之前。

导入应该按照以下顺序分组，不同组间用空行隔离。

1. 标准库 imports  
2. 相关第三方 imports
3. 本地特定应用／库 imports  

       推荐使用绝对导入，标准库代码应总是使用绝对导入。

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 <module> import *

3.9 模块级别 dunder 名称

         模块级别 “dunders”(即具有两个前导和两个后缀下划线的名称)，例如 __all__，__author__，__version__ 等应放在模块 docstring 之后，但在任何 import 语句之前，但是除了 __future__ 导入。 Python 强制 future-imports 必须在除了 docstrings 之外的任何其他代码之前出现在模块中。  

例如：

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

4 字符串引号，逗号

4.1 字符串引号

在 Python 中，单引号和双引号是等价的，只需要坚持使用一种并保持一致即可。

在双引号中使用单引号，单引号中使用双引号。三引号中使用双引号。

4.2 逗号

单元素元组强制使用逗号：

是：

    FILES = ('setup.cfg',)

OK, but confusing:

    FILES = 'setup.cfg',

当使用版本控制系统时，一组希望后续扩展的值/参数/改善的条目使用以下形式：

是：

    FILES = [

        'setup.cfg',

        'tox.ini',

        ]

    initialize(FILES,

               error=True,

               )

否：

    FILES = ['setup.cfg', 'tox.ini',]

    initialize(FILES, error=True,)

 

5 注释

       糟糕的注释不如没有注释，最好要用 English 注释！

5.1 块注释

       同等级别的一块代码的注释，块注释内每行注释以 # 开头，内部注释段落之间使用以 # 开头的空行注释隔开。

5.2 行注释

       行注释和代码声明间至少间隔两个空格，不要使用无聊的行注释，例如：

Don't do this:

x = x + 1                 # Increment x

But sometimes, this is useful:

x = x + 1                 # Compensate for border

5.3 文档字符串

        为所有公共模块，函数，类和方法编写文档字符串。 对于非公共方法，文本字符串不是必需的，但应该有一个描述该方法的注释。例如：

"""Return a foobangOptional plotz says to frobnicate the bizbaz first."""

"""only one single docstring line"""

       注意当注释为多行时，最终的 """ 单独起一行。

6 命名约定

        对用户可见的公共 API 部分的命名应该遵从反应如何使用而不是怎么实现。

6.1 描述性: 命名风格

        以下命名风格通常区分彼此使用：

• b (单个小写字母)
• B (单个大写字母)
• lowercase（小写）
• lower_case_with_underscores（带下划线的小写）
• UPPERCASE（大写）
• UPPER_CASE_WITH_UNDERSCORES（带下划线的大写）
• CapitalizedWords（驼峰式，蒙古包式 whatever.）

Note: 使用驼峰式时，缩写全部大写，例如：HTTPServerError 好于 HttpServerError

• mixedCase (乌鬼头)
• Capitalized_Words_With_Underscores (丑！不解释！)
• _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__ : "魔幻的" 对象或属性，只生存于用户控制的命名空间。例如， __init__ ，__import__ 或 __file__ 。千万不要臆造这种命名； only use them as documented.

6.2 规定性: 命名习惯

6.2.1 避免的命名

        一定不要使用 l(唉欧儿) O(偶) I(艾) 作为单字符变量命名，在某些字体中，这些字母和数字1，0无法区分。

6.2.2包和模块名

        模块应该使用简短并且全小写的命名，下划线也可以使用以提升可读性。

        Python 包也应该使用简短的全小写名称，尽管不鼓励使用下划线。

        当 C/C++ 编写的扩展模块伴随一个提供更高级别接口的 python 模块时，C/C++ 模块命名应该以下划线开头(例如，_socket)。

6.2.3 类名

        类名通常使用驼峰式命名习惯。

        在类的接口有文档说明，并且主要用于 callable 的情况下，类都是 callable 的，call 一个类将返回一个新的类实例，例如 instance = Class()。如果类实现了 __call__() 函数，那么类实例也将是 callable 的，类的命名也可以使用函数命名习惯。对于 builtin 函数的命名习惯，可以通过 dir(__builtins__) 查看系统函数命名样例。注意区分普通命名，异常名命名和 builtin 常量。

6.2.4 类型变量名

        相对于短名称如：T，AnyStr，Num，类型变量使用驼峰式命名习惯较好。另外建议在变量名前添加 _co 或 _contra 前缀响应的声明 covariant 或 contravariant 行为。例如：

from typing import TypeVar

VT_co = TypeVar('VT_co', covariant=True)KT_contra = TypeVar('KT_contra', contravariant=True)

6.2.5 异常名

        异常应该是类，所以可以使用类命名习惯，但是，如果异常是个错误类，一般加上 "Error" 后缀。

6.2.6 全局变量名

        我们假设这些全局变量只在一个模块内使用，这样的话和函数的命名习惯是一样的。设计为通过 from M import * 导入的类应该使用 __all__ 机制避免导出全局变量，或者可以使用老式的习惯，给这些全局变量名加上下划线作为前缀(表示这是非公有变量)。

6.2.7 函数名

        例如，func or func_write_to_file 为了向后兼容性，也可以使用 mixedCase 式命名风格。

6.2.8 函数和方法参数

       实例方法第一个入参一定要是 self。

       类方法第一个入参一定要是 cls。

       如果函数入参名和保留关键字冲突，则后缀下划线好过缩写或者糟糕的拼写。例如，class_ 好过 clss。

6.2.9 方法名和实例变量

        使用函数命名风格即可。如果希望是私有方法或实例变量，则前缀下划线。为避免和子类的命名冲突，请使用双下划线前缀命名。如果类 Foo 有一个属性变量 __a，那么通过 Foo.__a 是不能被访问的。当然，固执的用户仍然可以通过 Foo._Foo__a 访问），一般来说，双下划线前缀只是在避免子类属性命名冲突的场景下使用。

6.2.10 常量

        常量一般定义在模块级别。命名风格如：MAX_OVERFLOW 或 TOTAL 。

6.2.11 继承设计

        经常去思考类方法和实例变量（属性）应该是公有的还是非公有的（严格意义上，python 没有私有变量）。如果不确定，那就设置成非公有的。另一类属性类别是子类 API 的一部分，（在其他语言中称"protected"）。有些类天生就是被设计为用来继承的，当设计这种类时，注意哪些属性是公有的，哪些是子类 API 的一部分，哪些是只在基类中使用的。

来自仁慈的python之父的指导：

1. 公有实例变量不应该有前缀下划线。
2. 公有实例变量和保留关键字冲突时，变量名加前缀下划线避免，这比使用缩写和其他糟糕的拼写要好（除了 'cls'，当一个变量或入参确定是一个类，特别是作为类方法的第一个入参时，'cls' 更惹人喜爱）。
3. 对于简单的公有数据属性，不要使用复杂的存取函数，直接暴露属性名。
4. 如果设计继承基类时，不希望子类访问的属性加双下划线前缀。

6.2.12 公共和内部接口

        文档说明的接口一般认为是公共接口，除非文档明确声明为临时或内部接口（为了兼容性等其他原因），所有非文档说明的接口一般为内部接口。模块应该使用 __all__ 属性明确声明公共 API 名，如果 __all__ 为空，则表明模块没有公共 API。尽管使用了 __all__ 属性，内部接口（packages, modules, classes, functions, attributes or other names）仍然需要使用前缀下划线。如果包含的任何一个命名空间（package, module or class）是内部的，那么这个接口也被认为是内部接口。导入名应该总是被视为实现细节。其他导入模块一定不能依赖对此导入名的间接访问，除非它们是包含模块 API 的显式文档说明的部分，例如os.path 或者一个 package 向子模块暴露函数的 __init__ 模块。

7 编码建议

• 代码不应该以一种不利于其他 python 实现（PyPy, Jython, IronPython, Cython, Psyco 诸如此类）的方式编写。 例如：不要使用 a += b 或 a = a + b 来实现就地字符串连接，在库的性能敏感部分，应该使用 ''.join() 的形式，这就能保证在不同的 python 实现中，连接动作可以在线性时间内完成。
• 和例如 None 这类 singleton 的比较，应该使用 is 或 is not 而不是 ==。另外，小心使用 if x 如果你的本意是 if x is not None，如果 x 是个布尔变量值 false，那可就完蛋了。
• 尽管功能相同，从可读性上考虑：

是：

    if foo is not None:

否：

    if not foo is None:

• 当使用 rich comparisons 实现排序操作时，最好是实现所有六种操作(__eq__,__ne__, __lt__, __le__, __gt__, __ge__)而不要依赖其他的代码去单独实现某一类比较。为了减少劳动，functools.total_ordering() decorator 提供了一个生成缺失比较方法的工具。
• 使用 def 语句而不要使用赋值语句去直接绑定一个 lambda 表达式到标识符上：

是：

    def f(x): return 2*x

否：

    f = lambda x: 2*x

• 赋值语句的使用消除了 lambda 表达式相对于显式 def 语句的唯一好处，那就是它能够嵌入到一个更大的表达式里面。
• 捕获的异常要说明 "错误出在哪里了 ？" 而不是仅仅说明 "哎呀！出问题了！"。
• 正确使用异常链接。在 Python 3 中，应该使用 "raise X from Y" 来表示显式替换并且不会丢失原始追溯。
• 当有意替换一个内部异常(Python 2: "raise X", Python 3.3+: raise X from Non)时，请确保将相关的详细信息转移到新的异常(例如，将 KeyError 转换为 AttributeError 时保留属性名称，或将原始异常的文本嵌入到新的异常消息中)。
• 当在 Python 2 中抛出异常时，使用 raise ValueError('message') 而不是老式的 raise ValueError, 'message'，后者已经在 Python 3 中废弃。由于使用了括号，可以避免行连续符的使用。
• 当捕获异常时，尽可能提及具体的异常而不是使用一个赤裸裸的 except 子句。一个裸露的 except: 子句将捕获 SystemExit 和 KeyboardInterrupt 异常，这样的话就难于使用 control-c 中断程序，并可能掩盖其他问题。如果想要捕获标志程序错误的所有异常的话，用 except Exception:(裸露的 except 子句等同于 except BaseException:)：

try:

    import platform_specific_moduleexcept ImportError:

    platform_specific_module = None

        一个很好的经验法则是将裸露的 except 子句仅用于以下两种情况：

1、If the exception handler will be printing out or logging the traceback; at least the user will be aware that an error has occurred.

2、If the code needs to do some cleanup work, but then lets the exception propagate upwards with raise . try...finally can be a better way to handle this case.

• 当对捕获的异常重命名时，使用 2.6 版本引入的语法：

try:

    process_data()except Exception as exc:

    raise DataProcessingFailedError(str(exc))

• 当捕获操作系统错误时，相对于内置的 errno 值，最好是使用 Python 3.3 中介绍的显式异常层次结构。
• 对于所有的 try/except 子句，将 try 子句限制为必需的绝对最小代码量避免隐藏 bug：

是：

    try:

        value = collection[key]

    except KeyError:

        return key_not_found(key)

    else:

        return handle_value(value)


否：

    try:

        # Too broad!

        return handle_value(collection[key])

    except KeyError:

        # Will also catch KeyError raised by handle_value()

        return key_not_found(key)

• 特定代码块的本地资源使用 with 语句确保使用后立即释放，不能自动释放的使用 try/finally 也可以。
• 除了申请和释放资源，任何时候都应该使用单独的函数和方法调用 Context managers，例如：

是：

    with conn.begin_transaction():

        do_stuff_in_transaction(conn)

否：

    with conn:

        do_stuff_in_transaction(conn)

• 函数返回语句要一致。在一个函数内的所有返回语句要么都返回一个表达式，要么都不返回。如果任何一个返回语句返回了表达式，那么其他任何没有返回值的语句应该明确声明为 return None。在函数结束部分必须出现返回语句：

是：

    def foo(x):

        if x >= 0:

            return math.sqrt(x)

        else:

            return None

    def bar(x):

        if x < 0:

            return None

        return math.sqrt(x)

否：

    def foo(x):

        if x >= 0:

            return math.sqrt(x)

    def bar(x):

        if x < 0:

            return

        return math.sqrt(x)

• 相对于 string 模块，使用 string 方法要快的多并且与 unicode strings 共享相同的 API。当然了，除了需要考虑 2.0 版本之前 python 代码向后兼容性的情况。
• 使用 ''.startswith() 和 ''.endswith() 而不是字符串切片来检查前缀或后缀，例如：

是： if foo.startswith('bar'):

否： if foo[:3] == 'bar':

• 对象类型比较应该使用isinstance() 而不是直接比较：

是： if isinstance(obj, int):

否： if type(obj) is type(1):

• 当检查一个对象是否为字符串时，一定要注意这个对象也可能是 unicode 字符串！在Python 2 中，string 和 unicode 拥有一个公共基类 basestring，因此可以这么的：

if isinstance(obj, basestring):

        在 Python 3 中，unicode 和 basestring 已然不复存在(there's only str)，并且 bytes object 也不再视为一种 string 了，而是一个整形序列。

• 对于序列（字符串，列表，元组）的判空操作：

是：
    if not seq:

    if seq:

否：
    if len(seq):

    if not len(seq):

• 不要使用尾随空格。
• 不要使用 == 验证布尔值为 Ture 或 False：

是：

      if greeting:

否：

      if greeting == True:

也非：

      if greeting is True:

8 结束语

        本文主要参考的是PEP8 Python编码规范和来源于互联网上圈子内的的优秀实践，吸纳形成为我司的python编码规范文档，计划将这套规范用于指导我司python编程者进行作业，希望大家在日常的编码中都能遵守，拿它当作镜子，时常照照，对提升自身技能也大有裨益。当然，对本规范有任何不尽人意的地方都可以联系我进行修正完善。