Indentation 缩进和换行

Use 4 spaces per indentation level.

每级缩进使用 4 个空格。

For really old code that you don't want to mess up, you can continue to use 8-space tabs.

如果不想搞乱以前的古老的代码的话，可以使用8个空格长的制表符。

Continuation lines should align wrapped elements either vertically using Python's implicit line joining inside parentheses, brackets and braces, or using a hanging indent. When using a hanging indent the following considerations should be applied; there should be no arguments on the first line and further indentation should be used to clearly distinguish itself as a continuation line.

续行应该与其包裹元素对齐，要么使用圆括号、方括号和花括号内的隐式行连接来垂直对齐；要么使用悬挂式缩进对齐。使用悬挂式缩进时，应该考虑下面的意见。第一行不应该有参数；使用缩进以便与其他代码区分清楚。

Yes:

# Aligned with opening delimiter

# 与开始的分隔符对齐

foo = long_function_name(var_one, var_two,

                         var_three, var_four)

# More indentation included to distinguish this from the rest.

# 更多的缩进，更加的清晰

def long_function_name(

        var_one, var_two, var_three,

        var_four):

    print(var_one)

No:

# Arguments on first line forbidden when not using vertical alignment

# 没有使用垂直对齐时，禁止把参数放在第一行

foo = long_function_name(var_one, var_two,

    var_three, var_four)

# Further indentation required as indentation is not distinguishable

# 缩进不够，代码不清晰

def long_function_name(

    var_one, var_two, var_three,

    var_four):

    print(var_one)

Optional:

可选:

# Extra indentation is not necessary.

foo = long_function_name(

  var_one, var_two,

  var_three, var_four)

Tabs or Spaces? 制表符或者空格？

Never mix tabs and spaces.

绝不要混用制表符和空格。

The most popular way of indenting Python is with spaces only. The second-most popular way is with tabs only. Code indented with a mixture of tabs and spaces should be converted to using spaces exclusively. When invoking the Python command line interpreter with the -t option, it issues warnings about code that illegally mixes tabs and spaces. When using -tt these warnings become errors. These options are highly recommended!

最流行的 Python 缩进方式是仅使用空格，其次是仅使用制表符。混合着制表符和空格缩进的代码将被转换成仅使用空格。使用带-t选项来调用Python命令行解释器时，代码中非法混用制表符和空格会给出警告。当使用-tt选项时这些警告就会变成错误。高度建议使用这些选项。

For new projects, spaces-only are strongly recommended over tabs. Most editors have features that make this easy to do.

对新的项目，强烈建议只使用空格而不是制表符。大多数的编辑器都能轻松做到这一点。

Maximum Line Length 行的最大长度

Limit all lines to a maximum of 79 characters.

限制所有行的最大长度为 79 个字符。

There are still many devices around that are limited to 80 character lines; plus, limiting windows to 80 characters makes it possible to have several windows side-by-side. The default wrapping on such devices disrupts the visual structure of the code, making it more difficult to understand. Therefore, please limit all lines to a maximum of 79 characters. For flowing long blocks of text (docstrings or comments), limiting the length to 72 characters is recommended.

周围还有很多设备限制每行 80个字符。而且，限制窗口显示 80 个字符可以并排显示多个窗口。有些设备上，默认折行会打乱代码结构，不易理解。因此，请限制所有行的最大长度为 79 个字符。对一大段长文本（文档字符串或注释），推荐限制每行最多72个字符。

The preferred way of wrapping long lines is by using Python's implied line continuation inside parentheses, brackets and braces. Long lines can be broken over multiple lines by wrapping expressions in parentheses. These should be used in preference to using a backslash for line continuation. Make sure to indent the continued line appropriately. The preferred place to break around a binary operator is after the operator, not before it. Some examples:

较长代码行折行的首选方法是在圆括号、方括号和花括号内使用Python的隐式续行方式。通过圆括号内的表达式的折行来把较长的代码行折成多行。这种方式要优先使用，优先于反斜杠。同时确保适当的续行缩进。二元运算符的首选的折行处是在运算符之后，而不是之前。请看一些例子：

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)

Blank Lines 空行

Separate top-level function and class definitions with two blank lines.

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

Method definitions inside a class are separated by a single blank line.

类的方法之间使用一个空行。

Extra blank lines may be used (sparingly) to separate groups of related functions. Blank lines may be omitted between a bunch of related one-liners (e.g. a set of dummy implementations).

（谨慎地）使用额外的空白行来分隔一组相关的函数。一堆相关的单行代码之间的空白行可以省略（例如，一组dummy implementations）。

Use blank lines in functions, sparingly, to indicate logical sections.

在函数中使用空行来（谨慎地）表示不同的逻辑段落。

Python accepts the control-L (i.e. ^L) form feed character as whitespace; Many tools treat these characters as page separators, so you may use them to separate pages of related sections of your file. Note, some editors and web-based code viewers may not recognize control-L as a form feed and will show another glyph in its place.

Python接受control-L（即^L）换页符作为空格；许多工具把这些字符当作页面分隔符，所以你可以在文件中使用它们来分隔相关段落。请注意，一些编辑器和基于Web的代码阅读器可能无法识别control-L为换页，将在其位置显示另一个字形。

Encodings (PEP 263) 编码

Code in the core Python distribution should always use the ASCII or Latin-1 encoding (a.k.a. ISO-8859-1). For Python 3.0 and beyond, UTF-8 is preferred over Latin-1, see PEP 3120.

Python核心发行代码应该总是使用 ASCII 或 Latin-1 编码 (又名 ISO-8859-1)。Python 3.0 和以后的版本，首选 UTF-8 而不是 Latin-1，请查看 PEP 3120 获取更多信息。（译者注：对中文项目，请首选UTF-8。）

ASCII 编码的文件不应该有coding cookie（译者注：# -*- coding: utf-8 -*-，# coding=utf-8）。Latin-1（或 UTF-8 ）只应该当注释或文档字符串涉及作者名需要 Latin-1 时才使用；否则，使用 \x，\u或 \U等转义字符是在字符串中包含非 ASCII 数据的首选方法。

For Python 3.0 and beyond, the following policy is prescribed for the standard library (see PEP 3131): All identifiers in the Python standard library MUST use ASCII-only identifiers, and SHOULD use English words wherever feasible (in many cases, abbreviations and technical terms are used which aren't English). In addition, string literals and comments must also be in ASCII. The only exceptions are (a) test cases testing the non-ASCII features, and (b) names of authors. Authors whose names are not based on the latin alphabet MUST provide a latin transliteration of their names.

对Python 3.0 和以后的版本来说，下述政策仅对标准库作出限制（请查阅PEP 3131）：All identifiers in the Python standard library MUST use ASCII-only identifiers, and SHOULD use English words wherever feasible (in many cases, abbreviations and technical terms are used which aren't English). In addition, string literals and comments must also be in ASCII. The only exceptions are (a) test cases testing the non-ASCII features, and (b) names of authors. Authors whose names are not based on the latin alphabet MUST provide a latin transliteration of their names.

Open source projects with a global audience are encouraged to adopt a similar policy.

面向全球用户的开源项目，鼓励采用类似的政策。

Imports 导入

• Imports should usually be on separate lines, e.g.:

  导入通常应当使用单独的行，例如：

  Yes: import os
  
       import sys
  
  No:  import sys, os
  

  It's okay to say this though:

  但是可以这么做：

  from subprocess import Popen, PIPE
  

• Imports are always put at the top of the file, just after any module comments and docstrings, and before module globals and constants.

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

  Imports should be grouped in the following order:

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

  1. standard library imports 标准库导入
  2. related third party imports 相关第三方导入
  3. 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__ 说明书。

• Relative imports for intra-package imports are highly discouraged. Always use the absolute package path for all imports. Even now that PEP 328 is fully implemented in Python 2.5, its style of explicit relative imports is actively discouraged; absolute imports are more portable and usually more readable.

  非常不推荐在包内导入中使用相对路径导入。对所有导入来说，总是使用绝对包路径导入。尽管PEP 328 在Python 2.5中已经完全实现，但是相对路径导入一直以来都是不推荐的，绝对路径导入更容易移植，而且常常更容易阅读。

• When importing a class from a class-containing module, it's usually okay to spell this:

  从一个包含类的模块中导入类时，常常这么写：

  from myclass import MyClass
  
  from foo.bar.yourclass import YourClass
  

  If this spelling causes local name *es, then spell them

  如果上述写法导致内部名称冲突，那么可以这么写：

  import myclass
  
  import foo.bar.yourclass
  

  and use "myclass.MyClass" and "foo.bar.yourclass.YourClass".

  分别这样使用："myclass.MyClass" 和 "foo.bar.yourclass.YourClass"。

Pet Peeves 宠物的烦恼（即无伤大雅的小问题）

Avoid extraneous whitespace in the following situations:

在下列情况下，避免多余的空格：

• Immediately inside parentheses, brackets or braces.

  紧贴着圆括号、方括号和花括号。

  Yes: spam(ham[1], {eggs: 2})
  
  No:  spam( ham[ 1 ], { eggs: 2 } )
  

• Immediately before a comma, semicolon, or colon:

  紧贴在逗号，分号或冒号之前：

  Yes: if x == 4: print x, y; x, y = y, x
  
  No:  if x == 4 : print x , y ; x , y = y , x
  

• Immediately before the open parenthesis that starts the argument list of a function call:

  紧贴在函数调用的参数列表的圆括号的开括号前：

  Yes: spam(1)
  
  No:  spam (1)
  

• Immediately before the open parenthesis that starts an indexing or slicing:

  紧贴在索引或切片的方括号的开括号前：

  Yes: dict['key'] = list[index]
  
  No:  dict ['key'] = list [index]
  

• More than one space around an assignment (or other) operator to align it with another.

  在赋值（或其他）语句的运算符周围，不要为了对齐而使用多个空格。

  Yes:

  x = 1
  
  y = 2
  
  long_variable = 3
  

  No:

  x             = 1
  
  y             = 2
  
  long_variable = 3
  

Other Recommendations 其他建议

• Always surround these binary operators with a single space on either side: assignment (=), augmented assignment (+=, -= etc.), comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not), Booleans (and, or, not).

  总是在这些二元运算符前后加一个空格：赋值（=），自增赋值（+=，-= 等等）， 比较（==，<，>，!=，<>，<=，>=，in，not in，is，is not)，布尔运算（and，or，not）。

• Use spaces around arithmetic operators:

  在算术运算符前后加空格：

  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)
  

• Don't use spaces around the = sign when used to indicate a keyword argument or a default parameter value.

  不要在一个关键字参数或者一个缺省参数值的 = 符号前后加一个空格。

  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)
  

• Compound statements (multiple statements on the same line) are generally discouraged.

  通常不推荐使用复合语句（一行代码中有多条语句）。

  Yes:

  if foo == 'blah':
  
      do_blah_thing()
  
  do_one()
  
  do_two()
  
  do_three()
  

  Rather not:

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

• While sometimes it's okay to put an if/for/while with a small body on the same line, never do this for multi-clause statements. Also avoid folding such long lines!

  通常情况下，一行代码包括一个小的if/for/while块，是可以的。但是多子句绝不可以。同样，需要避免折叠类似的长代码行！

  Rather not:

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

  Definitely not:

  绝对不可以：

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

Block Comments 块注释

Block comments generally apply to some (or all) code that follows them, and are indented to the same level as that code. Each line of a block comment starts with a # and a single space (unless it is indented text inside the comment).

块注释在一些（或全部）代码之前，并和代码缩进一致。每行注释均以 # 开头，然后紧跟一个空格（除非在注释内缩进）。

Paragraphs inside a block comment are separated by a line containing a single #.

块注释内的段落使用仅含 # 的单行分隔。

Inline Comments 行内注释

Use inline comments sparingly.

谨慎地使用内嵌注释

An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space.

内嵌注释是一种和语句在同一行的注释。内嵌注释至少和语句间隔2个空格。他们开始于一个 # 和一个空格。

Inline comments are unnecessary and in fact distracting if they state the obvious. Don't do this:

如果语句显而易见，那么内嵌注释是不必要的，实际上会让开发者分心。不要这么做：

x = x + 1                 # Increment x

But sometimes, this is useful:

但是有的情况下，这样却很有帮助：

x = x + 1                 # Compensate for border

Documentation Strings 文档字符串

Conventions for writing good documentation strings (a.k.a. "docstrings") are immortalized in PEP 257.

编写良好的文档字符串（documentation strings，又名 "docstrings"）的约定永生（:(）在 PEP 257。

• Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the def line.

  所有的公告模块，函数，类和方法都需要编写文档字符串。对非公共的方法而言，文档字符串则不是必要的，但是可以使用一个注释来描述这个方法。这个注释必须位于 def 行之后。

• PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, and preferably preceded by a blank line, e.g.:

  PEP 257 描述了一个良好的文档字符串的编写约定。注意最重要的是，""" 作为多行的文档字符串的结束，应该单独一行，例如：

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

• For one liner docstrings, it's okay to keep the closing """ on the same line.

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

Descriptive: Naming Styles 描述：命名风格

There are a lot of different naming styles. It helps to be able to recognize what naming style is being used, independently from what they are used for.

有许多不同的命名风格。它能够识别正在使用什么样的命名风格，而不考虑他们为什么使用。

The following naming styles are commonly distinguished:

下面是常见的优秀命名方式：

• b (single lowercase letter) （单个小写字母）

• B (single uppercase letter) （单个大写字母）

• lowercase 小写字母

• lower_case_with_underscores 使用下划线分隔的小写字母

• UPPERCASE 大写字母

• UPPER_CASE_WITH_UNDERSCORES 使用下划线分隔的大写字母

• CapitalizedWords (or CapWords, or CamelCase -- so named because of the bumpy look of its letters [4]). This is also sometimes known as StudlyCaps.

  CapitalizedWords （或 CapWords，或 CamelCase -- 这样命名因为其字母有起伏的外观[4]）。这有时也被称为 StudlyCaps。

  Note: When using abbreviations in CapWords, capitalize all the letters of the abbreviation. Thus HTTPServerError is better than HttpServerError.

  注意：当首字大写中用到缩写时，所有字符用大写。因此HTTPSeverError比HttpSeverError好。

• mixedCase (differs from CapitalizedWords by initial lowercase character!)

  mixedCase（不同于首字符大写，开始是小写字母！）

• Capitalized_Words_With_Underscores (ugly!)（丑陋之极！）

There's also the style of using a short unique prefix to group related names together. This is not used much in Python, but it is mentioned for completeness. For example, the os.stat() function returns a tuple whose items traditionally have names like st_mode, st_size, st_mtime and so on. (This is done to emphasize the correspondence with the fields of the POSIX system call struct, which helps programmers familiar with that.)

也有用唯一短前缀来组织相关字符的方法。在Python中用的不多。但为了完整提一下。比如，os.stat()返回一个元组， 里面的条目是传统的名字，如st_mode, st_size, st_mtime 等。 (这么做是为了与 POSIX 系统的调用一致，以帮助程序员熟悉它。)

The X11 library uses a leading X for all its public functions. In Python, this style is generally deemed unnecessary because attribute and method names are prefixed with an object, and function names are prefixed with a module name.

X11库的所有公共函数用了前导X。在Python中，这种风格通常被视为非必须的，因为属性和方法的名字用类做前缀，方法名用模块名做前缀。

In addition, the following special forms using leading or trailing underscores are recognized (these can generally be combined with any case convention):

另外，下面用前导和结尾下划线的特殊格式是被认可的（通常和一些示例规范结合）

• _single_leading_underscore: weak "internal use" indicator. E.g. from M import * does not import objects whose name starts with an underscore.

  _single_leading_underscore：（单下划线开始）弱"内部使用"指示器。例如：from M import * 不会导入以下划线开始的对象。

• single_trailing_underscore_: used by convention to avoid conflicts with Python keyword, e.g.

  single_trailing_underscore_：（单下划线结束）规定使用其来避免与Python关键字冲突，例如：

  Tkinter.Toplevel(master, class_='ClassName')
  

• __double_leading_underscore: when naming a class attribute, invokes name mangling (inside class FooBar, __boo becomes _FooBar__boo; see below).

  __double_leading_underscore：（双下划线开始）命名一个类的属性时，调用"名字变化"（类FooBar中，__boo 变为了 _FooBar__boo; 见下文）。

• __double_leading_and_trailing_underscore__: "magic" objects or attributes that live in user-controlled namespaces. E.g. __init__, __import__ or __file__. Never invent such names; only use them as documented.

  __double_leading_and_trailing_underscore__：（双下划线开始和结束）"magic"对象或属性存活于用户控制的命名空间。 例如__init__, __import__ 或 __file__。永远不要起这样的名字；只在文档中使用。

Prescriptive: Naming Conventions 说明：命名规范