PEP8中文版 -- Python编码风格指南(上)

Python部落组织翻译, 禁止转载

PEP:
8
标题:
Python编码风格指南
作者:
Guido van Rossum < python.org的guido >, Barry Warsaw < python.org的barry>, Nick Coghlan <gmail.com的ncoghlan >
状态:
活动中
类型:
过程
创建于:
2011年7月5日
修改历史:
2011年7月5日,2013年8月1日


目录
      缩进
      制表符还是空格?
      行的最大长度
      空行
      源文件编码
      导入
      无法忍受的
      其它建议
      注释块
      行内注释
      文档字符串
      根本原则
      描述:命名风格
      规定:命名约定



本文档所提供的编码规范,适用于主要的Python发行版中组成标准库的Python代码。请参阅PEP关于Python的C实现的C编码风格指南的描述[1]。

本文档和PEP257(文档字符串规范)改编自Guido的《Python Style Guide》一文,用Barry的风格指南[2]做一些补充。

这篇风格指南随着时间的推移而逐渐演变,随着语言本身的变化,过去的约定已经过时了并确定了更多新的约定。

许多项目都有自己的编码风格指南。如果有任何冲突,优先使用该项目特定的指南。


令人讨厌的小人物身上愚蠢的一致性


Guido的一个重要的见解是,代码阅读的次数比编写的次数多。这里提供的指南旨在提高代码的可读性,并使各种不同的Python代码一致。如PEP20所说,“易读性非常重要”。

风格指南是关于一致性的。与本风格指南一致很重要。项目中的一致性更重要。一个模块或功能中的一致性最重要。

最重要的是:知道何时会不一致——有时风格指南就不适用了。怀疑时,作出你最佳的判断。看看其他的例子,并决定什么是最好的。不要犹豫,尽管发问!

特别地:不要只为遵从这个PEP而打破向后兼容性!

忽视既定指南的一些其他的好理由:
1、当应用指南会降低代码的可读性,即使对于那些习惯遵照这个PEP来阅读代码的人来说。
2、与周围的代码保持一致也会破坏它(可能是历史原因)——虽然这也是收拾别人烂摊子的好机会(在真正的XP风格中)。
3、因为问题代码先于指南,又没有其它的修改理由。
4、代码需要兼容老版本,本风格指南不建议使用的Python特性。


代码布局


缩进


每级缩进使用4个空格。
连续行应该对齐折叠元素,无论是垂直的Python的隐式行连接圆括号内的,中括号内的,大括号内的,还是使用悬挂缩进[5]。使用悬挂缩进应注意以下几点;


第一行没有参数并且使用更多的缩进来区别它本身和连续行。


风格良好:

# 与分界符对齐。
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)

对于连续行,4个空格规则是可选的。
可选的:
# 悬挂缩进可能缩进不是4个空格。
foo = long_function_name(
  var_one, var_two,
  var_three, var_four)


if语句条件块足够长时需要编写多行,值得注意的是两个字符组成的关键字(例如if),加上一个空格,加上开括号为多行条件的后续行创建一个4个空格的缩进。这可以给嵌入if内的缩进语句产生视觉冲突,这也自然被缩进4个空格。这个PEP没有明确如何(是否)进一步区分条件行和if语句内的嵌入行。这种情况下,可以接受的选项包括,但不仅限于:


# 没有额外的缩进。
if (this_is_one_thing and
    that_is_another_thing):
    do_something()

# 添加一行注释,这将为编辑器支持语法高亮提供一些区分。
if (this_is_one_thing and
    that_is_another_thing):
    # 因为两个条件都是true,我们可以frobnicate.
    do_something()

# 在条件接续行,增加额外的缩进
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',
)


制表符还是空格?


空格是缩进方法的首选。
制表符仅用于与已经用制表符做缩进的代码保持一致。
Python3不允许混用制表符和空格来缩进。
Python2代码混用制表符和空格缩进,将被转化为只使用空格。
调用Python2命令行解释器时使用-t选项,可对代码中非法混用制表符和空格发出警告。当使用-tt选项,警告将变成错误。这些选项是高度推荐的!


行的最大长度


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

下垂的长块结构限制为更少的文本(文档字符串或注释),行的长度应该限制在72个字符。

限制编辑器窗口宽度使得并排打开多个文件成为可能,并且使用代码审查工具显示相邻列的两个版本工作正常。

绝大多数工具的默认折叠会破坏代码的可视化结构,使其更难以理解。编辑器中的窗口宽度设置为80个字符。即使该工具将在最后一列中标记字形。一些基于网络的工具可能不会提供动态的自动换行。

有些团队强烈喜欢较长的行长度。对于代码维护完全或主要由一个团队的,可以在这个问题上达成协议,象征性的将行长度从80个字符增加到100个字符(有效地增加最大长度到99个字符)也是可以的,提供注释和文档字符串仍是72个字符。

Python标准库采取保守做法,要求行限制到79个字符(文档字符串/注释到72个字符)。

折叠长行的首选方法是在小括号,中括号,大括号中使用Python隐式换行。长行可以在表达式外面使用小括号来变成多行。连续行使用反斜杠更好。

反斜杠有时可能仍然是合适的。例如,长的多行的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())
(为进一步思考With语句的多行缩进,见前面多行if语句的讨论。)


另一个这样的例子是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接受control-L(即^L)换页符作为空白符;许多工具把这些字符作为分页符,所以你可以使用它们为文件中的相关部分分页。注意,一些编辑器和基于Web的代码查看器可能不能识别control-L是换页,将显示另外的字形。
源文件编码
Python核心发布中的代码应该始终使用UTF-8(或Python2中用ASCII)。
文件使用ASCII(Python2中)或UTF-8(Python3中)不应有编码声明。

在标准库中,非默认编码仅用于测试目的或注释或文档字符串需要提及包含非ASCII字符的作者名;否则,使用\x,\u,\U,或\N是字符串中包含非ASCII数据的首先方式。

Python3.0及以上版本,为标准库(参见PEP 3131)规定以下策略:Python标准库中的所有标识符必须使用ASCII标识符,在可行的地方使用英文单词(在很多例子中,使用非英文的缩写和专业术语)。另外,字符串和注释必须用ASCII。仅有的例外是(a)测试非ASCII的特点,(b)测试作者名。不是基于拉丁字母表的作者名必须提供一个他们名字的拉丁字母表的音译。

开源项目面向全球,鼓励采用统一策略。


导入


导入通常是单独一行,例如:
风格良好:


          import os
          import sys


风格不良:

         

         import sys,os


这样也是可以的:
from subprocess import Popen, PIPE
导入常常位于文件顶部,在模块注释和字符串文档之后,在模块的全局变量和常量之前。

导入应该按照以下顺序分组:
1. 标准库导入
2. 相关的第三方导入
3. 特定的本地应用/库导入
在每个导入组之间放一行空行。

把任何相关__all__规范放在导入之后。
推荐绝对导入,因为它们更易读,并且如果导入系统配置的不正确(例如当包中的一个目录结束于sys.path)它们有更好的表现(至少给出更好的错误信息):
import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example

明确的相对导入可以用来接受替代绝对导入,特别是处理复杂包布局时,绝对导入过于冗长。
from . import sibling
from .sibling import example

标准库代码应该避免复杂包布局并使用绝对导入。
隐式的相对导入应该永远不被使用,并且在Python3中已经移除。
从一个包含类的模块中导入类时,通常下面这样是好的写法:
from myclass import MyClass
from foo.bar.yourclass import YourClass
如果这种写法导致本地名字冲突,那么就这样写:
import myclass
import foo.bar.yourclass
并使用“myclass.MyClass”和“foo.bar.yourclass.YourClass”来访问。
避免使用通配符导入(from <模块名> import *),因为它们使哪些名字出现在命名空间变得不清楚,这混淆了读者和许多自动化工具。通配符导入有一种合理的使用情况,重新发布一个内部接口作为一个公共API的一部分(例如,重写一个纯Python实现的接口,该接口定义从一个可选的加速器模块并且哪些定义将被重写提前并不知道)。

用这种方式重新命名,下面的有关公共和内部接口的指南仍适用。


英文原文: https://www.python.org/dev/peps/pep-0008/

译者: wangyc

 

2月15日11:00到13:00网站停机维护,13:00前恢复
iPy智能助手 双击展开
查看更多聊天记录
(Ctrl+回车)换行