python代码风格指南：pep8 中文翻译

时间  2020-01-15
标签 python 代码 风格 指南 pep8 pep 中文 翻译 栏目 Python 繁體版
原文   原文链接

        最近半年都在断断续续地学习使用python，基本语法和基本编程思想都差很少了解了。就是只知其一;不知其二的意思啦~~t_0020.gif最近在着手写一些工具了。是时候好好学习一下规范一点的代码规范了。python

        今天转载一下oschina的python码风格pep8的翻译文章。但愿对本身之后的编码也能规范一点。t_0005.gifgit

代码布局

缩进

每级缩进用4个空格。程序员

括号中使用垂直隐式缩进或使用悬挂缩进。后者应该注意第一行要没有参数，后续行要有缩进。编程

  • Yesapi

# 对准左括号
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)

  • No数组

# 不使用垂直对齐时，第一行不能有参数。
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)

4个空格的规则是对续行可选的。框架

# 悬挂缩进不必定是4个空格
foo = long_function_name(
  var_one, var_two,
  var_three, var_four)

if语句跨行时，两个字符关键字(好比if)加上一个空格，再加上左括号构成了很好的缩进。后续行暂时没有规定，至少有以下三种格式，建议使用第3种。socket

# 没有额外缩进，不是很好看，我的不推荐.
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()
 
# 额外添加缩进,推荐。
# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

右边括号也能够另起一行。有两种格式，建议第2种。编辑器

# 右括号不回退，我的不推荐
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?

  • 空格是首选的缩进方法。ide

  • Tab仅仅在已经使用tab缩进的代码中为了保持一致性而使用。

  • Python 3中不容许混合使用Tab和空格缩进。

  • Python 2的包含空格与Tab和空格缩进的应该所有转为空格缩进。

Python2命令行解释器使用-t选项时有非法混合Tab和空格的状况会告警。当使用-tt警告提高为错误。强烈推荐这些选项！另外我的推荐pep8和autopep8模块。

最大行宽

限制全部行的最大行宽为79字符。

文本长块，好比文档字符串或注释，行长度应限制为72个字符。

多数工具默认的续行功能会破坏代码结构，使它更难理解，不推荐使用。可是超过80个字符加以提醒是必要的。一些工具可能根本不具有动态换行功能。

一些团队强烈但愿更长的行宽。若是能达成一致，能够从从80提升到100个字符(最多99个字符)增长了标称线的长度，不过依旧建议文档字符串和注释保持在72的长度。

Python标准库比较保守，限制行宽79个字符(文档字符串/注释72）。

续行的首选方法是使用小括号、中括号和大括号反斜线仍可能在适当的时候。其次是反斜杠。好比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。

注意续行要尽可能不影响可读性。好比一般在二元运算符以后续行：

class Rectangle(Blob):
 
    def __init__(self, width, height,
                 color='black', emphasis=None, highlight=0):
        if (width == 0 and height == 0 and
                color == 'red' and emphasis == 'strong' or
                highlight > 100):
            raise ValueError("sorry, you lose")
        if width == 0 and height == 0 and (color == 'red' or
                                           emphasis is None):
            raise ValueError("I don't think so -- values are %s, %s" %
                             (width, height))
        Blob.__init__(self, width, height,
                      color, emphasis, highlight)

空行

  • 两行空行分割顶层函数和类的定义。

  • 类的方法定义用单个空行分割。

  • 额外的空行能够必要的时候用于分割不一样的函数组，可是要尽可能节约使用。

  • 额外的空行能够必要的时候在函数中用于分割不一样的逻辑块，可是要尽可能节约使用。

  • Python接 contol-L做为空白符；许多工具视它为分页符，这些要因编辑器而异。

源文件编码

在核心Python发布的代码应该老是使用UTF-8(ASCII在Python 2)。

ASCII文件(Python 2)或UTF-8(Python 3)不该有编码声明。

标准库中非默认的编码应仅用于测试或当注释或文档字符串,好比包含非ASCII字符的做者姓名，尽可能使用\x , \u , \U , or \N。

Python 3.0及之后版本，PEP 3131可供参考，部份内容以下：在Python标准库必须使用ASCII标识符，并尽可能只使用英文字母。此外字符串和注释也必须用ASCII。惟一的例外是：（a）测试非ASCII的功能，和（b）做者的名字不是拉丁字母。

导入

  • 导入在单独行

import os
import sys
from subprocess import Popen, PIPE

No:

import os, sys

  • 导入始终在文件的顶部，在模块注释和文档字符串以后，在模块全局变量和常量以前。

导入顺序以下：标准库进口,相关的第三方库，本地库。各组的导入之间要有空行。

相关的all放在导入以后。

  • 推荐绝对路径导入，由于它们一般更可读，并且每每是表现更好的（或至少提供更好的错误消息。

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

  • 禁止使用通配符导入。

通配符导入(from <module> import *)应该避免，由于它不清楚命名空间有哪些名称存，混淆读者和许多自动化的工具。惟一的例外是从新发布对外的API时能够考虑使用。

字符串引用

Python中单引号字符串和双引号字符串都是相同的。注意尽可能避免在字符串中的反斜杠以提升可读性。

根据PEP 257, 三个引号都使用双引号。

表达式和语句中的空格

强制要求

  • 括号里边避免空格

# 括号里边避免空格
# Yes
spam(ham[1], {eggs: 2})
# No
spam( ham[ 1 ], { eggs: 2 } )

  • 逗号，冒号，分号以前避免空格

# 逗号，冒号，分号以前避免空格
# Yes
if x == 4: print x, y; x, y = y, x
# No
if x == 4 : print x , y ; x , y = y , x

  • 索引操做中的冒号看成操做符处理先后要有一样的空格(一个空格或者没有空格，我的建议是没有。

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

  • 函数调用的左括号以前不能有空格

# Yes
spam(1)
dct['key'] = lst[index]
 
# No
spam (1)
dct ['key'] = lst [index]

  • 赋值等操做符先后不能由于对齐而添加多个空格

# Yes
x = 1
y = 2
long_variable = 3
 
# No
x             = 1
y             = 2
long_variable = 3

其余建议

  • 二元运算符两边放置一个空格:

涉及 =、符合操做符 ( += , -=等)、比较( == , < , > , != , <> , <= , >= , in , not in , is , is not )、布尔( and , or , not )。

  • 优先级高的运算符或操做符的先后不建议有空格。

# Yes
i = i + 1
submitted += 1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)
 
# No
i=i+1
submitted +=1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)

  • 关键字参数和默认值参数的先后不要加空格

# Yes
def complex(real, imag=0.0):
    return magic(r=real, i=imag)
 
# No
def complex(real, imag = 0.0):
    return magic(r = real, i = imag)

  • 函数注释中，=先后要有空格，冒号和"->"的前面无空格，后面有空格。

# Yes
def munge(input: AnyStr):
def munge(sep: AnyStr = None):
def munge() -> AnyStr:
def munge(input: AnyStr, sep: AnyStr = None, limit=1000):
 
# No
def munge(input: AnyStr=None):
def munge(input:AnyStr):
def munge(input: AnyStr)->PosInt:

  • 一般不推荐复合语句(Compound statements: 多条语句写在同一行)。

# Yes
if foo == 'blah':
    do_blah_thing()
do_one()
do_two()
do_three()
 
# No
if foo == 'blah': do_blah_thing()
do_one(); do_two(); do_three()

  • 尽管有时能够在if/for/while 的同一行跟一小段代码，但毫不要跟多个子句，并尽可能避免换行。

# No
if foo == 'blah': do_blah_thing()
for x in lst: total += x
while t < 10: t = delay()

更不是：

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

注释

与代码自相矛盾的注释比没注释更差。修改代码时要优先更新注释！

注释是完整的句子。若是注释是断句，首字母应该大写，除非它是小写字母开头的标识符(永远不要修改标识符的大小写)。

若是注释很短，能够省略末尾的句号。注释块一般由一个或多个段落组成。段落由完整的句子构成且每一个句子应该以点号(后面要有两个空格)结束，并注意断词和空格。

非英语国家的程序员请用英语书写你的注释，除非你120%确信代码永远不会被不懂你的语言的人阅读。

注释块

注释块一般应用在代码前，并和这些代码有一样的缩进。每行以 '# '(除非它是注释内的缩进文本，注意#后面有空格)。

注释块内的段落用仅包含单个 '#' 的行分割。

行内注释

慎用行内注释(Inline Comments) 节俭使用行内注释。 行内注释是和语句在同一行，至少用两个空格和语句分开。行内注释不是必需的，重复罗嗦会令人分心。不要这样作：

x  =  x  +  1  # Increment x

但有时颇有必要:

x  =  x  +  1  # Compensate for border

文档字符串

文档字符串的标准参见：PEP 257。

  • 为全部公共模块、函数、类和方法书写文档字符串。非公开方法不必定有文档字符串，建议有注释(出如今 def 行以后)来描述这个方法作什么。

更多参考：PEP 257 文档字符串约定。注意结尾的 """ 应该单独成行，例如：

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

单行的文档字符串，结尾的 """ 在同一行。

版本标签

版本注记 (Version Bookkeeping)

若是你必须在源文件中包含git、Subversion、CVS或RCS crud信息，放置在模块的文档字符串以后，任何其余代码以前，上下各用一个空行：

version__ = "$Revision$"# $Source$

命名约定

Python库的命名约定有点混乱，不可能彻底一致。但依然有些广泛推荐的命名规范的。新的模块和包 (包括第三方的框架) 应该遵循这些标准。对不一样风格的已有的库，建议保持内部的一致性。

最重要的原则

用户可见的API命名应遵循使用约定而不是实现。

描述：命名风格

有多种命名风格：

  • b(单个小写字母)

  • B(单个大写字母)

  • lowercase(小写串)

  • lower_case_with_underscores(带下划线的小写)

  • UPPERCASE(大写串)

  • UPPER_CASE_WITH_UNDERSCORES(带下划线的大写串)

  • CapitalizedWords(首字母大写的单词串或驼峰缩写）

注意: 使用大写缩写时，缩写使用大写字母更好。故 HTTPServerError 比 HttpServerError 更好。

  • mixedCase(混合大小写，第一个单词是小写)

  • Capitalized_Words_With_Underscores（带下划线，首字母大写，丑陋）

还有一种风格使用短前缀分组名字。这在Python中不经常使用， 但出于完整性提一下。例如，os.stat()返回的元组有st_mode, st_size, st_mtime等等这样的名字(与POSIX系统调用结构体一致)。

X11库的全部公开函数以X开头, Python中一般认为是没必要要的，由于属性和方法名有对象做前缀，而函数名有模块名为前缀。

下面讲述首尾有下划线的状况:

  • _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__ or __file__，不要本身发明这样的名字。

命名约定规范

  • 避免采用的名字

决不要用字符'l'(小写字母el)，'O'(大写字母oh)，或 'I'(大写字母eye) 做为单个字符的变量名。一些字体中，这些字符不能与数字1和0区别。用'L' 代替'l'时。

  • 包和模块名

模块名要简短，所有用小写字母，可以使用下划线以提升可读性。包名和模块名相似，但不推荐使用下划线。

模块名对应到文件名，有些文件系统不区分大小写且截短长名字，在 Unix上不是问题，但当把代码迁移到 Mac、Windows 或 DOS 上时，就多是个问题。固然随着系统的演进，这个问题已经不是常常出现。

另外有些模块底层用C或C++ 书写，并有对应的高层Python模块，C/C++模块名有一个前置下划线 (如：_socket)。

  • 类名

遵循CapWord。

接口须要文档化而且能够调用时，可能使用函数的命名规则。

注意大部份内置的名字是单个单词（或两个），CapWord只适用于异常名称和内置的常量。

  • 异常名

若是确实是错误，须要在类名添加后缀 "Error"。

  • 全局变量名

变量尽可能只用于模块内部，约定相似函数。

对设计为经过 "from M import " 来使用的模块，应采用 __all__ 机制来防止导入全局变量；或者为全局变量加一个前置下划线。

  • 函数名

函数名应该为小写，必要时可用下划线分隔单词以增长可读性。 mixedCase(混合大小写)仅被容许用于兼容性考虑(如: threading.py)。

  • 函数和方法的参数

实例方法第一个参数是 'self'。

类方法第一个参数是 'cls'。

若是函数的参数名与保留关键字冲突，一般在参数名后加一个下划线。

  • 方法名和实例变量

同函数命名规则。

非公开方法和实例变量增长一个前置下划线。

为避免与子类命名冲突，采用两个前置下划线来触发重整。类Foo属性名为__a， 不能以 Foo.__a访问。(执著的用户仍是能够经过Foo._Foo__a。) 一般双前置下划线仅被用来避免与基类的属性发生命名冲突。

  • 常量

常量一般在模块级定义,由大写字母用下划线分隔组成。好比括MAX_OVERFLOW和TOTAL。

  • 继承设计

考虑类的方法和实例变量(统称为属性)是否公开。若是有疑问，选择不公开；把其改成公开比把公开属性改成非公开要容易。

公开属性可供全部人使用，并一般向后兼容。非公开属性不给第三方使用、可变甚至被移除。

这里不使用术语"private"， Python中没有属性是真正私有的。

另外一类属性是子类API(在其余语言中一般称为 "protected")。 一些类被设计为基类，能够扩展和修改。

谨记这些Python指南：

  1. 公开属性应该没有前导下划线。

  2. 若是公开属性名和保留关键字冲突，能够添加后置下划线

  3. 简单的公开数据属性，最好只公开属性名，没有复杂的访问/修改方法，python的Property提供了很好的封装方法。 d.若是不但愿子类使用的属性，考虑用两个前置下划线(没有后置下划线)命名。

公共和内部接口

任何向后兼容的保证只适用于公共接口。

文档化的接口一般是公共的，除非明说明是临时的或为内部接口、其余全部接口默认是内部的。

为了更好地支持内省，模块要在__all__属性列出公共API。

内部接口要有前置下划线。

若是命名空间(包、模块或类)是内部的，里面的接口也是内部的。

导入名称应视为实现细节。其余模块不能间接访名字，除非在模块的API文档中明确记载，如os.path中或包的__init__暴露了子模块。

编程建议

  • 考虑多种Python实现(PyPy, Jython, IronPython,Pyrex, Psyco, 等等)。

例如，CPython对a+=b或a=a+b等语句有高效的实现，但在Jython中运行很慢，尽可能改用.join()。

  • None比较用'is'或'is not'，不要用等号。

注意"if x is not None" 与"if x" 的区别。

  • 用"is not"代替"not ... is"。前者的可读性更好。

# Yes
if foo is not None

# No
if not foo is None

  • 使用基于类的异常。

比较排序操做最好是实现全部六个操做，而不是代码中实现比较逻辑。functools.total_ordering()装饰符能够生成缺失的比较方法。

__eq__，__ne__，__lt__，__lt__，__gt__，____）


PEP207 比较标准代表反射规则由Python完成。所以解释器可能会交换参数的位置，好比替换y > x为x < y，因此有必要实现这5种方法。

  • 使用函数定义def代替lambda赋值给标识符：

# Yes
def f(x): 
    return 2*x
 
# No
f = lambda x: 2*x

前者更适合回调和字符串表示。

  • 异常类继承自Exception，而不是BaseException。

源于异常，而不是BaseException例外。从BaseException直接继承的例外状况追赶他们几乎老是错误的事情作保留。

要设计基于层次的异常，捕捉到须要的异常，而不是异常引起的位置。能回答：“出了什么问题？”，而不是仅仅指出“问题发生”(更多参考：PEP3151 重构OS和IO异常层次）

  • 适当使用异常链。在Python3中"raise X from Y"明确表示更换且保留了原来的traceback。

替换内部异常(在Python2: "raise X"或"raise X from None")时，确保相关细节转移到新的异常（如转换KeyError为AttributeError保存属性名，或在新的异常中嵌入原始异常)。

后者不兼容Python3语法。前者续行方便。

  • 捕获异常时尽可能指明具体异常，而不是空"except:"子句。好比：

# Yes
try:
    import platform_specific_module
except ImportError:
    platform_specific_module = None

空"except:"子句(至关于except Exception)会捕捉SystemExit和KeyboardInterrupt异常，难以用Control-C中断程序，并可掩盖其余问题。若是 你捕捉信号错误以外全部的异常，使用"except Exception"。

空"except:"子句适用的状况两种状况：

a, 打印出或记录了traceback，至少让用户将知道已发生错误。

b, 代码须要作一些清理工做，并用 raise转发了异常。这样try...finally能够捕捉到它。

  • Python 2.6之后建议用as显示绑定异常名：

# Yes
try:
    process_data()
except Exception as exc:
    raise DataProcessingFailedError(str(exc))

这样才能兼容Python3语法并避免歧义。

  • 捕捉操做系统错误时，建议使用Python 3.3引入显式异常层次，支持内省errno值。

  • 此外全部try/except子句的代码要尽可的少，以避免屏蔽其余的错误。

# Yes
try:
    value = collection[key]
except KeyError:
    return key_not_found(key)
else:
    return handle_value(value)
 
# No
try:
    # 太泛了!
    return handle_value(collection[key])
except KeyError:
    # 会捕捉到handle_value()中的KeyError
    return key_not_found(key)

  • 本地资源建议使用with语句，以确保即时清理。固然try / finally语句也是能够接受的。

  • 上下文管理器在作获取和释放资源以外的事情时，应经过独立的函数或方法。例如：

# Yes
with conn.begin_transaction():
    do_stuff_in_transaction(conn)
 
# No
with conn:
    do_stuff_in_transaction(conn)

后者指明enter和exit方法。

  • 函数或者方法在没有返回时要明确返回None。

  • 使用字符串方法而不是string模块。

python 2.0之后字符串方法老是更快，且Unicode字符串相同的API。

  • 使用使用 .startswith()和.endswith()代替字符串切片来检查前缀和后缀。and

startswith()和endswith更简洁，利于减小错误。例如：

# Yes
if foo.startswith('bar'):
 
# No
if foo[:3] == 'bar':

  • 使用isinstance()代替对象类型的比较：

# Yes
if isinstance(obj, int):
 
# No
if type(obj) is type(1):

检查是不是字符串时，注意Python 2中str和unicode有公共的基类:

if isinstance(obj, basestring): 在 Python 2.2 中，types 模块为此定义了 StringTypes 类型，例如：

# Yes
if isinstance(obj, basestring):

Python3中Unicode和basestring的再也不存在(只有str)和字节对象再也不是字符串(是整数序列)

  • 对序列(字符串、列表 、元组), 空序列为false:

# Yes
if not seq:
   pass
if seq:
   pass
 
# No
if len(seq):
   pass
if not len(seq):
   pass

  • 字符串后面不要有大量拖尾空格。

  • 不要用 == 进行布尔比较

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

本文原文链接：http://my.oschina.net/u/1433482/blog/464444?p=1

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程