Python-pep8代码规范

发布于 2017-12-05 · 本文总共 5147 字 · 阅读大约需要 15 分钟

python代码格式规范

PEP是 Python Enhancement Proposal 的缩写,翻译过来就是 Python增强建议书。 pep8规范pep-0008

一代码布局

缩进

使用4个空格进行缩进

行宽

每行代码尽量不超过80个字符

理由：

这在查看side-by-side的diff时很有帮助
方便在控制台下查看代码
太长可能是设计有缺陷

换行

续行应该与被圆括号、方括号、花括号包裹起来的其他元素对齐，或者使用悬挂式缩进。当使用悬挂式缩进时，应该遵循这些注意事项：第一行不能有参数，应该使用进一步的缩进来将续行与其他行区分开 Python支持括号内的换行。这时有两种情况。 1) 第二行缩进到括号的起始处

foo = long_function_name(var_one, var_two,
                         var_three, var_four)

2) 第二行缩进4个空格，适用于起始括号就换行的情形

def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

使用反斜杠\换行，二元运算符+ .等应出现在行首，并与上一行的.或=对齐；或者缩进4个空格。长字符串也可以用此法换行

foo = variable_with_long_name \
    + another_variable \
    + variable

session.query(MyTable) \
       .filter_by(id=1) \
       .one()

this_is_a_very_long(function_call, 'with many parameters') \
    .that_returns_an_object_with_an_attribute

print 'Hello, ' \
      '%s %s!' % \
      ('Harry', 'Potter')

多个元素的list或者tuple，在起始括号后换行，第二行缩进4个空格

items = [
    'this is the first', 'set of items', 'with more items',
    'to come in this line', 'like this'
]

结尾的括号另起一行
禁止复合语句，即一行中包含多个语句：

# yes
do_first()
do_second()
do_third()

# no
do_first();do_second();do_third();

if/for/while一定要换行：

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

# no
if foo == 'blah': do_blash_thing()

空行

模块级函数和类定义之间空两行；
类成员函数之间空一行；
不要使用太多的连续空行来区分代码的逻辑块

class A:
    """This is a simple docstring."""

    def __init__(self):
        pass

    def hello(self):
        pass


def hello(name):
    print "Hello %s!" % name


def main():
    pass

可以使用多个空行分隔多组相关的函数
函数中可以使用空行分隔出逻辑相关的代码

二表达式

空格

一元运算符不加空格
在二元运算符两边各空一格[=,-,+=,==,>,in,is not, and]:

# yes
exp = -1.05
i = i + 1
submitted += 1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)

# no
exp = - 1.05
i=i+1
submitted +=1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)

函数的参数列表中，,之后要有空格

# yes
def complex(real, imag):
    pass

# no
def complex(real,imag):
    pass

函数的参数列表中，默认值等号两边不要添加空格

# yes
def complex(real, imag=0.0):
    pass

# no
def complex(real, imag = 0.0):
    pass

左括号之后，右括号之前不要加多余的空格

# yes
spam(ham[1], {eggs: 2})
value = my_list[index]

# no
spam( ham[1], { eggs : 2 } )
value = my_list[ index ]

字典、列表对象的左括号之前不要多余的空格

# yes
dict['key'] = list[index]

# no
dict ['key'] = list [index]

不要为对齐赋值语句而使用的额外空格

# yes
x = 1
y = 2
long_variable = 3

# no
x             = 1
y             = 2
long_variable = 3

比较

使用变量在左，常量在右
不显示进行对True、False的比较
否定比较采用，foo not in bar的形式，而不是not foo in bar
使用instance(a, C)进行实例的类型检查，而不是type(A) is C

# yes
if method == 'md5':
    pass
if not foo:
    pass
if foo not in bar:
    pass
if instance(a, C):
    pass
# no

if 'md5' == method:
    pass
if foo == False:
    pass
if not foo in bar:
    pass
if type(A) is C:
    pass

引号

简单说，自然语言使用双引号，机器标示使用单引号，因此 代码里 多数应该使用 单引号

自然语言 使用双引号 "..."
例如错误信息；很多情况还是unicode，使用u"你好世界"
机器标识 使用单引号 '...' 例如dict里的key
正则表达式 使用原生的双引号 r"..."
文档字符 使用三个双引号 """......"""

三 import语句

import语句应该分行书写

# yes
import os
import sys

# no
import sys,os

# yes
from subprocess import Popen, PIPE

import语句应该使用 absolute import

# yes
from foo.bar import Bar

# no
from ..bar import Bar

import语句应该放在文件头部，置于模块说明及docstring之后，于全局变量之前；

import语句应该按照顺序排列，每组之间用空行分隔

导入应该按照以下的顺序分组：

standard library imports 标准库导入
related third party imports 相关第三方导入
local application/library specific imports 本地应用程序/库的特定导入 You should put a blank line between each group of imports.每组导入之间使用空行隔开。

Put any relevant all specification after the imports. 在导入之后放置任何相关的 all 说明书。

import os
import sys

import msgpack
import zmq

import foo

导入其他模块的类定义时，可以使用相对导入

from myclass import MyClass

如果发生命名冲突，则可使用命名空间

import bar
import foo.bar

bar.Bar()
foo.bar.Bar()

四注释

块注释

#号后空一格，段落间用空行分开（同样需要#号）

# 块注释
# 块注释
#
# 块注释
# 块注释

行注释

内嵌注释是一种和语句在同一行的注释。内嵌注释至少和语句间隔2个空格。使用# 和一个空格开头。

# yes
x = x + 1  # 边框加粗一个像素

# no
x = x + 1 # x加1

其他注意事项

请使用英语写注释，除非你120％肯定你的代码将永远不会被不说你的语言的人阅读。
注释应该是一条完整的句子。如果注释是一个短语或句子，它的第一个字应该大写，除非它是一个小写字母开头的标识符（绝对不要改变标识符的大小写）。
句号结尾的句子后面应该有2个空格。

文档字符串

docstring的规范在 PEP 257 中有详细描述，其中最其本的两点：

所有的公共模块、函数、类、方法，都应该写docstring。私有方法不一定需要，但应该在def后提供一个块注释来说明。
docstring的结束”"”应该独占一行，除非此docstring只有一行。
- ””” 作为多行的文档字符串的结束，应该单独一行
- 对单行的文档字符串来说，结尾的 “”” 在同一行。

"""Return a foobar
Optional plotz says to frobnicate the bizbaz first.
"""

"""Oneline docstring"""

五命名规范

避免使用的名字

应避免使用小写字母l(L)，大写字母O(o)或I(i)单独作为一个变量的名称，以区分数字1和0 在某些字体中，这些字很难和数字的0和1区分。当打算用’l’的时候,用’L’来代替

变量

常量

常量使用以下划线分隔的大写命名，UPPERCASE_WITH_UNDERSCORES
Precompiled regular expressions: name_re

MAX_OVERFLOW = 100

Class FooBar:

    def foo_bar(self, print_):
        print(print_)

私有变量

小写和一个前导下划线 _private_value

内置变量

小写，两个前导下划线和两个后置下划线 __class__

包和模块名称

包和模块使用全小写命名，尽量不要使用下划线
模块应该用简短的，全小写的名字。如果能增强可读性的话，可以使用下划线。 Python的包也要用全小写的，短名称，但是不建议用下划线。
因为模块名称和文件名关联，而且某些文件系统大小写不敏感，也会截断过长的名字。所以模块选用相当简短的名字是很重要的。在Unix下不会有这样的问题，但是在早些的Mac、Windows 或者 DOS下会有这样的问题。
当用C或C++连编写一个含有Python模块提供更高层（比如，更加面向对象）接口的扩展模块时，这个C/C++模块要有一个前导下划线（例如 _socket）。

类名

类总是使用驼峰格式命名，即所有单词首字母大写其余字母小写。类名应该简明，精确，并足以从中理解类所完成的工作。常见的一个方法是使用表示其类型或者特性的后缀，例如: SQLEngine MimeTypes
类名使用CamelCase命名风格，内部类可用一个下划线开头；
约定的缩写保留原样，例如使用HTTPWriter而不是HttpWriter

函数名

函数使用下划线分隔的小写命名，lowercase_with_underscores

函数和方法参数

始终用self作为实例方法的第一个参数。
当参数名称和Python保留字冲突，可在最后添加一个下划线，尽量不是使用缩写或自造的词如果函数的参数名和保留字冲突。用结尾下划线比缩写或是滥用的组词更好。因此 class_ 比 clss好。（也许，更好的避免冲突的方式是用同义词。）
Lambdas for properties may have the first parameter replaced with x, as in display_name = property(lambda x: x.real_name or x.username).

编码建议

使用’‘.startswith() 和 ‘‘.endswith()而非字符切片去检测前缀或后缀。
对于序列，(strings, lists, tuples)，利用空序列为false这一点。

Yes: if not seq:
     if seq:

No: if len(seq)
    if not len(seq)

别用‘==’进行布尔值和 True 或者 False 的比较

Yes:   if greeting:
No:    if greeting == True:
Worse: if greeting is True:

字符串不要以空格收尾。视觉上难以区分，而且很多编辑器会去掉他们。
编码中考虑到其他python实现的效率等问题例如，不要依赖于CPython的高效内置字符连接语句a += b or a = a + b.这些语句在Jython中运行较慢。在性能敏感的库中，应该用’‘.join() 来取代。这样可以保证在不同的实现中，字符链接花费的时间都呈线性。
建议
一个函数 : 不要超过 30 行代码, 即可显示在一个屏幕类，可以不使用垂直游标即可看到整个函数。一个类 : 不要超过 200 行代码，不要有超过 10 个方法。一个模块不要超过 500 行。

验证脚本

>>easy_install pep8

>>pep8 -r --ignoire E501 Test.py

重复打出错误，并且忽略 501 错误(代码超过79行)。

参考资料

pep8翻译
PEP8中文翻译 http://wiki.hiaero.net/doku.php?id=python:pep8
python编码风格指南：https://python.freelycode.com/contribution/detail/49