PEP 8 – Style Guide for Python Code

原文：PEP 8 – Style Guide for Python Code

PEP：8
题目：Python代码风格指南
做者：Guido van Rossum, www.yszx11.cnBarry Warsaw , Nick Coghlan
状态：Active
类型：Process
建立：2001-07-05
往期：2001-07-05，2013-08-01

内容：

介绍

该文档提供了python编程中的一些惯例，包含Python发布版中的一些基础库。 请参阅Python的C语言实现中的C代码配套信息PEP描述风格指南[1]。
本文档和PEP 257由Guido的原始Python风格指导文章改编，其中一些添加了Barry的风格指南的内容[2]。
这个风格指南会随着时间的推移而演变，而过去的惯例会因语言自己的变化而过期。
在不少工程中有本身的编程风格指导。若是工程内的风格指南与本文冲突的话，前者有优先级应该更高。

呆板的坚持一致性简直傻的没边了

（这个PEP8仍是挺有情怀的，标题的英文是《A foolish consistency is the hobgoblin of little minds》，出自爱默生的self reliance）

Guido的主要看法之一是咱们大部分时间是在读代码而不是写。 这里提供的指导旨在提升代码的可读性，使其在普遍的Python代码中保持一致。就像PEP 20所说的：强调可读性。
风格指南是关于一致性的。风格指南的一致性很重要。 一个项目的一致性更重要。 一个模块或功能内的一致性是最重要的。
可是，咱们应该知道什么时候须要不一致 - 有时风格指南的建议不适用。 若是由此疑惑的话，应当听从本身的判断。或者你能够看看其余的例子，决定什么看起来最好。而且不要犹豫去问问题！
特别是：不要只是为了符合这个PEP 8建议而破坏向后兼容性！

下面有些其余的缘由可让咱们忽略特定指导原则：
1.当使用了这个指南致使代码可读性不好，甚至是使用过PEP 8的人去读依旧不好。
2.为了与原有的代码风格保持一致，也能够不遵循PEP 8（多是出于历史缘由），固然还有一种多是原有代码的风格是乱的，这样的话也能够趁着这个机会整理一下以前混乱的风格。
3.代码风格问题出现的比指南还要早，并且已经没有什么必要再修改。
4.当代码须要与不支持风格指南推荐功能的旧版本的Python保持兼容时。

代码的布局

缩进

一次缩进使用4个空格
连续的行应使用Python的内隐行以垂直对齐的方式链接在圆括号、方括号或花括号内，或者使用悬挂式缩进[7]来将封装的元素对齐。在使用悬挂式缩进时，应注意下面的问题：在第一行中不该该有任何参数（悬挂式缩进时），而且应该使用进一步的缩进来清楚表示参数的延续线。

正确的示范：

#在分界处对齐，var_one与var_three对齐
foo = long_function_name(var_one, var_two,
var_three, var_four)

#使用更多的缩进与其余部分区分开，var_one和var_four与print()缩进不一样
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( www.yszx11.cn var_one, var_two,
var_three, var_four)

# 参数的缩进与print()函数缩进相同
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
对于连续的行而言，四个空格的规定不是必须的。

# Hanging indents *may* be indented to other than 4 spaces.
foo = long_function_name(
var_one, var_two,
var_three, var_four)

若是if语句的条件长到须要多行才能写下，值得注意的是，在多行条件语句中，左括号加空格再加上两个字符关键字的组合的形式会为多行条件的后续行建立一个天然的4空格缩进。这种形式很像if中的嵌套，这样就带来了视觉上的混淆。这个PEP对于如何（或者是否）进一步将这些条件行与if嵌套进行视觉上的区分没有明确的规定。在这种状况下可采用以下方式（但不限于此）：
（说了一大串，结果就是咋用都行）

# 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()
（另外能够参考下面的考虑：关于换行符应在二元运算符以前仍是以后？）

在Python的List数据结构中，右面的（closing brace/opening brace）花括号/方括号/圆括号能够在列表的最后一行的第一个非空格字符之下排列，以下：

my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'www.yszxylpt.com 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仍是空格？

推荐使用空格做为缩进方式。
Tab只有在以前就已经使用了Tab做为缩进的代码中继续使用。
Python 3中禁止缩进时空格和Tab混合使用。
Python 2中混合使用了空格和Tab的代码最好应该改为只是用Tab。
当使用-t选项调用Python 2命令行解释器时，会发出关于非法混合Tab和空格的代码的警告。当使用-tt调用时，这些警告会变成错误。 强烈推荐使用这些选项！

行的最大长度

全部行的最大值为79个字节。
对于长度较短的文本块（文本输入或注释）较少的结构限制，行长度应限制为72个字符。

限制所需的编辑器窗口宽度使得能够并排打开多个文件，而且在使用在相邻列中呈现两个版本的代码审阅工具时能够正常工做。

大多数工具中的默认包装会破坏代码的可视化结构，使其更难于理解。选择限制以免将窗口宽度设置为80的编辑器中包围，即便工具在包装线时将标记字形放在最后一列中。一些基于Web的工具根本不能提供动态的线条包装。

一些团队强烈但愿更长的线路长度。对于惟一或主要由可以就此问题达成协议的团队维护的代码，能够将标称行长度从80增长到100个字符（有效地将最大长度增长到99个字符），前提是注释和文档包装仍然包装72个字符

Python标准库是保守的，而且须要将限制行限制为79个字符（和docstrings /注释到72）。

换行长行的首选方法是使用括号，括号和大括号内的Python隐含行延续。经过将表达式包含在括号中，能够在多行上分割长行。这些应优先于使用反斜杠进行行连续使用。

有时，反斜杠可能仍然适用。例如，long，multiple with-statements不能使用隐式继承，因此反斜杠是能够接受的：

换行符应在二元运算符以前仍是以后？

几十年来，都是推崇在二元运算符以后换行的风格。但这可能会在两个方面损害程序的可读性：程序员不得不将视线分散到屏幕上的不一样的行，而且程序员还须要把视线从找到的操做数上移到上一行上。 如此，眼睛必须作额外的工做来判断哪些项目被添加，哪些被减去：

# No: 操做数里运算符远
income = (gross_wages +
taxable_interest +
(dividends - qualified_dividends) -
ira_deduction -
student_loan_interest)
1
2
3
4
5
6
1
2
3
4
5
6
为了解决易读性的问题，数学家及其出版商遵循相反的惯例。 唐纳德·克努特（Donald Knuth）在他的“电脑和排版”系列中解释了传统的规则：“尽管段落中的公式老是在一个二元运算符和关系运算符以后断开，可是被显示的公式老是在二元运算符前断开（说实话我没太理解这个虽然。。。可是。。。的比较，意思好像是在说在电脑里面通常是以后断开，可是在排版的时候是以前断）”。
遵循数学中传统的风格每每使代码变得更易读：

# Yes: 更容易对运算符和操做数配对
income = (gross_wages
+ taxable_interest
+ (dividends - www.jpg521.com qualified_dividends)
- ira_deduction

在Python代码中，在运算符前面断开是合法（就是说这个你的Python版本这样写不报错），可是要和你以前的风格一致。而对于新的代码，建议使用克努特推荐的风格（在前面断开）。

空行

在开头定义的功能和类，带行空行。

类中定义的方法首位单行空行。

可使用额外的空行（谨慎地）来分离相关功能组。在一系列相关的单线程程序里（例如，一组虚拟实现），不该该使用空行。

在功能函数中使用空白行，应当谨慎地指示逻辑部分。

Python接受ctrl-L的形式的做为空格; 许多工具将这些字符视为页面分隔符，所以您可使用它们来分隔文件的相关部分的页面。 请注意，一些编辑器和基于Web的代码查看器可能不支持ctrl-L，并会在其位置显示另外一个字形。

源文件的编码

核心Python发行版中的代码应始终使用UTF-8（或Python 2中的ASCII）。

使用ASCII（Python 2）或UTF-8（在Python 3中）的文件不该该具备编码声明。

在标准库中，非默认编码应仅用于测试，注释或者评论和文档中用以说起做者的名字。
docstring须要说起包含非ASCII字符的做者名称时;不然，使用\ x，\ u，\ U或\ N转义是在字符串文字中包含非ASCII数据的首选方法。

对于Python 3.0及更高版本，标准库规定了如下策略（参见PEP 3131）：Python标准库中的全部标识符必须使用只有ASCII的标识符，并应尽量使用英文单词（在许多状况下，缩写和技术术语使用不是英文的术语）。 此外，字符串文字和注释也必须是ASCII。 惟一的例外是（a）测试非ASCII功能的测试用例，（b）做者名称。 名字不是拉丁字母的做者必须提供其名字的拉丁音译。

鼓励有全球观众的开源项目采起相似的政策。

引入

引入应当分行：

Yes: import os
import sys

这样是能够的：

from subprocess import Popen, PIPE

import一般在文件的开头位置，仅仅在模块的注释、文档字符串说明、全局变量和常量以后。

引入应按如下顺序分组：

1.标准库
2.相关第三方库
3.自定义库
您应该在每组导入之间留一个空行。

推荐绝对引入的方式，它们一般可读性更好。若是导入系统配置不正确，至少能够提供更准确的错误消息。（例如，当一个包中的目录在sys.path中最终出现时）

import mypkg.sibling
from mypkg import sibling
from mypkg.sibling www.wmyl88.com/ import example
1
2
3
1
2
3
固然，明确的相对引入是绝对引入的可接受的替代方案，特别是在处理复杂的布局时，绝对引入的方式将带来没必要要的冗长的字符：

from . import sibling
from .sibling import example
1
2
1
2
标准库代码应避免复杂的布局，并始终使用绝对引入的方式引入。
不明确相对引入的方式步应该被使用，而且已经在Python 3中被删除了。
若是从类的包含模块中导入类，一般能够这样写：

from myclass import MyClass
from foo.bar.yourclass import YourClass
1
2
1
2
可是若是这样写形成本地命名冲突的话，就这样写：

import myclass
import foo.bar.your www.lieqibiji.com class
1
2
1
2
而后这样使用：
“myclass.MyClass”
“foo.bar.yourclass.YourClass”

应避免使用通配符导入（from <module> import *），由于它们使在名称空间中的不清楚，从而使不论是读者仍是许多自动化编译工具都很困惑。通配符导入有一个防护用例，它是做为公共API的一部分从新发布一个内部接口 （例如，覆盖来自可选加速器模块的定义的界面的纯Python实现，以及将覆盖哪些定义是未知的）。

当以这种方式从新发布名称时，下面关于公共和内部接口的指南仍然适用。

模块的双下划线命名

具备两个前导和后下划线的模块de 名称（如__all__，__author__，__version__等）应放置在模块的字符串说明以后，import操做以前。（除了__future__）
Python要求将来的导入必须出如今的全部其余引入代码以后（除了字符串说明）。

例如：

"""
This is the example www.wmyl11.com module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import osimport sys