PEP 8 介绍

PEP8 是 Python 社群共通的风格指南，一开始是 Python 之父 Guido van Rossum 自己的撰码风格，慢慢后来演变至今，目的在于帮助开发者写出可读性高且风格一致的程式。许多开源项目，都是以 PEP8 为基础再加上自己的风格建议。

这列出 PEP8 里面的重点，有兴趣可以直接看官方原文的文件会更清楚一些。

1. 缩进 (Indentation)

每层缩进使用 4 个空格

2. 断行风格

  • 风格良好：

    # 断行首字母与开头的括号垂直对齐
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)

3. if 条件断行

  • if 刚好有 4 个字符，相当于一层缩进。

  • 对于 if 条件断行，以下几种风格都可以：

    • 没有额外的缩进

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

    • 添加额外的缩进加以区分

      if (this_is_one_thing
        and that_is_another_thing):
    do_something()

4. 多行的括号

  • 括号结束符与最后行的首字符对齐，如：

    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',
)

上面两种排版的方式都可以

5. 使用 Tab 还是空格缩进

  • 用空格

6. 每行最长长度

  • 所有行都不超过 80 个字符

  • 限制编辑器视窗的宽度，使能并排同时打开多个文件。

  • 设置编辑器宽度 (set width to 80)，来避免 wrapping

  • 对于较少结构限制的长文本（如 docstrings 或注释），行长应限制为 72 个字符。

  • 如果团队成员都同意使用长行，则可以将行长增加到不超过 100 个字符，但是 docstrings 和注释还必须为 72 个字符。

  • 有括号的长行可以用 implicit continuation 来断行，其它的可以用 \ 来断行，如：

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

7. 操作符要和操作数在一起 

# 风格良好，这样很容易将操作符与操作数匹配：
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

# 这种风格现今已不推荐使用了：
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

8. 空行分隔

  • 模组中最顶层的函数和类定义都要用两行空行分隔

  • 类别中的方法定义用单行分隔

  • 要把一组相关的函数分组，可以用一些额外的空行

  • 函数中的逻辑区块可以加空行来分隔

9. 原始码的编码

  • Python 核心模组文件的编码都必须用 UTF-8（Python2 是 ASCII）。

  • 使用默认的编码时（Python3: UTF-8，Python2: ASCII），不能使用编码声明

  • 标准库中，只有测试、作者名才能使用非默认的编码，其它情况下的非 ASCII 字符用 \x, \u , \u, \N 表示法表示。

10. Import

  • 每行 import 只导入一个模组：

    # 风格良好:
import os
import sys

# 风格不良：
import sys, os

# 风格良好：同一模组中的内容可以在同一行导入
from subprocess import Popen, PIPE

  • import 语句要在文件的前面，在模组注释及 docstrings 之后，在模组全域变量和常量定义之前。

  • import 分组及导入顺序，每个分组之间用一行空行分隔

    1. 标准库

    2. 相关第三方库

    3. 本地应用 / 库的特殊导入

  • 推荐使用绝对导入，如：

    import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example

  • 在比较覆杂的套件组成中，也可以用显式的相对导入，如：

    from . import sibling
from .sibling import example

  • 从一个模块中导入一个类别时，要显示拼写出类别名，如：

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

  • 如果与本地名称冲突，可以先导入模组：

    import myclass
import foo.bar.yourclass

    然后使用：myclass.MyClass 和 foo.bar.yourclass.YourClass。

  • 应该避免使用from <module> import *

  • 模组层级的特殊名称（如 __all__) 的位置：

  • 必须在模组的 docstrings 或注释之后，但在任何的 import 语句之前。from __future__ 比较特殊，Python 强制该语句必须在 docstrings 或注释之后，因此风格如下：

    """This is the example module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

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

import os
import sys

11. 字符引号 (String Quotes)

  • 单引号和双引号的功能是等同的。

  • 对于多行字符串，应该用双引号字符形式的三引号 """ ，以便与 PEP257 中的 docstrings 规范兼容

12. 表达式和语句中的空格 (Whitespace in Expressions and Statements)

  • ()、[]、{} 等括号内不要多余的空格，如：

    # 风格良好：
spam(ham[1], {eggs: 2})

# 风格不良：
spam( ham[ 1 ], { eggs: 2 } )

  • ,、;、: 之前不要有空格，如：

    # 风格良好：
if x == 4: print x, y; x, y = y, x

# 风格不良：
if x == 4 : print x , y ; x , y = y , x

  • 在 slice 语句中的：实际上是一个二元操作符，因此其两侧的空格数必须相同；但当无 slice 参数时，两侧的空格可以都省略，如：

    # 风格良好：
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]

# 风格不良：
ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : upper]
ham[ : upper]

  • 函数调用的 () 及索引的 [] 前不要加空格，如：

    # 风格良好：
spam(1)
dct['key'] = lst[index]

# 风格不良：
spam (1)
dct ['key'] = lst [index]

  • 不要在赋值语句中加入额外的空格来对齐，如：

    # 风格良好：
x = 1
y = 2
long_variable = 3

# 风格不良:
x = 1
y = 2
long_variable = 3

13. 其它推荐风格

  • 任何行的行尾都不要有空白符。

  • 在二元操作符号两侧一般都要加一个空格，一般的二元操作符号如：

    • 赋值：=, +=, -=

    • 比较：==, <, >, !=, <>, <=, >=, in, not in, is, is not

    • 布尔操作： and, or, not

  • 在分优先级的表达式中，在最低优先级的操作符两侧加一个空格，但至多只能加一个空格，如：

    # 风格良好：
x = x*2 – 1
hypot2 = x*x + y*y
c = (a+b) * (ab)

# 风格不良：
x = x * 2 – 1
hypot2 = x * x + y * y
c = (a + b) * (a – b)

  • 在关键字参数和默认参数值中的 = 两侧不要加空格，如：

    # 风格良好：
def complex(real, imag=0.0 ):
return magic(r=real, i=imag)

# 风格不良：
def complex(real, imag = 0.0):
return magic(r = real, i = imag)

  • 函数注解中的 : 前不要加空格，这符合 : 的常规风格，但是 -> 两侧要加空格，如：

    # 风格良好：
def munge(input: AnyStr): …
def munge() -> AnyStr: …

# 风格不良：
def munge(input:AnyStr): …
def munge()->PosInt: …

  • 参数注解中，如果注解的参数有默认值，指定默认值的 = 两侧要加空格，如：

    # 风格良好：
def munge(sep: AnyStr = None): …
def munge(input: AnyStr, sep: AnyStr = None, limit=1000): …

# 风格不良：
def munge(input: AnyStr=None): …
def munge(input: AnyStr, limit = 1000): …

  • 不要将多条语句组合在一行中，如：

    # 风格良好：
if foo == 'blah':
do_blah_thing()
do_one()
do_two()
do_three()

# 风格不良：
if foo == 'blah': do_blah_thing ()
do_one(); do_two(); do_three()

  • 如果 if/for/while 区块内的程式码很少，组合在一行有时还是可以接受的，但是不推荐，如：

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

# 但是在有多段语句时，绝对不能这样，如：
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()

14. 注释 (Comments)

  • 注释内容必须要和程式码相关！

  • 注释应该是完整的语句，首字母一般大写（英文），一般要有句号。

  • 注释很短时句号可以省略。

  • 区块注释一般由多个段落组成。用英文写注释

14.1. 区块注释 (Block Comments)

  • 每行用 # 及一个空格开始

  • 段落用一个只有 # 的行分隔

14.2. 行内注释 (Inline Comments)

  • 注释与语句内容至少用两个空格分开，注释用 # 加一个空格开始

    # 不要像下面这样，注释内容没有必要
x = x + 1  # Increment x
# 但是有时，如下面的注释会很有用
x = x + 1  # Compensate for border

14.3. 文档字串 (Documentation Strings)

  • 公开的模组、函数、类及方法都应该有文件字串，而非公开的方法可以用注释来代替，且注释放置在 def 行之后。

  • 多行的文件字串，结束符号要自成一行，如：

    """Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""

  • 单行的文件字串，结束符号和内容放在同一行

15. 命名 (Naming Conventions)

没有推荐的风格，但是别人要能从你的程式码中看出你用的是什么风格，常用的风格如下：

  • b 单个小写字母

  • B 单个大写字母

  • lowercase

  • lower_case_with_underscores

  • UPPERCASE

  • UPPER_CASE_WITH_UNDERSCORES

  • CapitalizedWords, 这种风格中，对于缩写词应全部用大写，如

    • HTTPServerError 比 HttpServerError 好

  • mixedCase

  • Capitalized_Words_With_Underscores，这个太丑，不要用这种！

  • st_mode、st_mtime 等前缀，一般是系统接口返回，如果自己写的程式码不推荐用这种

  • _single_leading_underscore : 弱内部使用 指示器，这种对象用 from M import * 不会被导入

  • single_trailing_underscore_ : 可以用来和 Python 关键词进行区分，如 Tkinter.Toplevel(master, class_='ClassName')

  • __double_leading_underscore : 命名一个类属性时，可以进行命名矫正，例如 class FooBar 内的 __boo 会变成 _FooBar__boo

  • double_leading_and_trailing_underscore : magic 对象，不要自己发明这种对象

15.1. 命名习惯 (Prescriptive: Naming Conventions)

  • 不用单个 l, O, I 等这样的单个字符来命名，它们与数字 1，0 不好区分

  • 套件名和模组名：全部用小写，必要时可用 _，但不推荐，C/C++ 的扩展模组，如果其对应有 Python 版本，那么 C/C++ 扩展模组名前加 _

  • 类别名：用 CapWords 风格

  • 异常名：用 CapWords 风格，一般应该有 Error 后缀

  • 全域变量名：能用 from M import * 导入的变量全部放在 __all__ 中，或者全域变量用 _ 做前缀

  • 函数名：应该用全部用小写，单词间可以用 _ 分隔，如 my_func，不推荐用 mixedCase 风格

  • 函数和方法的参数：实例方法的第一个参数用 self, 类别方法的第一个参数用 cls，如果参数与关键字冲突，在参数名后加 _ 后缀，如 class_

  • 实例变量和方法： 用小写字符和 _ , 非公开的实例变量和方法用一个 _ 做前缀；避免与子类别中的名字冲突，类的变量可用两个 _ 作前缀，例如 class FooBar 内的 __boo 会变成只能通过 FooBar._FooBar__boo 读取

  • 常量：全部大写，可用 _ 分隔，如 MAX_OVERFLOW、TOTAL

16. 推荐的程式撰写方式 (Programming Recommendations)

  • 字符串连接不要用 a += b 或者 a = a + b, 用 .join(), 后者性能更好。跟 None 的比较用 is 和 is not，不要用 ==，如果你想判断 if x is not None, 不要缩写成 if x 使用 if foo is not None，而不是 if not foo is None，前者更加易读

  • 如果要实现序列比较操作的话，应将 6 个操作（__eq__ , __ne__ , __lt__ , __le__ , __gt__ , __ge__）全部实现，可以借助 functools.total_ordering() 修饰器来减少工作量

  • 将函数保存在一个变量中应该用 def f(x): return 2*x， 而非 f = lambda x: 2*x，后者不利于调试

  • 自定义的异常类应该继承至 Exception 类，而非 BaseException 类。Python 2 中抛出异常用 raise ValueError('message')，而非 raise ValueRoor, 'message'

  • 尽量可以的指明异常名，如：

    try:
    import platform_specific_module
except ImportError:
    platform_specific_module = None

  • 避免使用无异常名的 except: 语句，它会捕获全部的异常（如 Ctrl + C）。

  • 将异常绑定到名字的方法：

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

  • try: 中的语句要尽量减少，如：

    # 风格良好：
try:
    value = collection[key]
except KeyError:
    return key_not_found(key)
else:
    return handle_value(value)

# 风格不良
try:
    # Too broad!
    return handle_value(collection[key])
except KeyError:
    # Will also catch KeyError raised by handle_value()
    return key_not_found(key)

  • 如果资源只适用于某个代码段内，使用 with 或 try/finally 来确保能进行清理工作

  • 上下文管理器应用通过一个单独的函数或方法来呼叫，如：

    # 风格良好：
with conn.begin_transaction():
    do_stuff_in_transaction(conn)

# 风格不良：
with conn:
    do_stuff_in_transaction(conn)

  • return 语句应该一致，如：

    # 风格良好：
def foo(x):
    if x >= 0:
        return math.sqrt(x)
    else:
        return None

def bar(x):
    if x < 0:
        return None
    return math.sqrt(x)

# 风格不良：
def foo(x):
    if x >= 0:
        return math.sqrt(x)

def bar(x):
    if x < 0:
        return
    return math.sqrt(x)

  • 使用字符串的方法，而不是用 string 模组中的方法

  • 使用 .startswith() 和 .endswidth() 而不用 slicing 来检查前缀和后缀：

    # 风格良好：
if foo.startswith('bar'):

# 风格不良：
if foo[:3] == 'bar':

  • 判断对象的类型用 isinstance 而不直接 type 比较，如：

    # 风格良好：
if isinstance(obj, int):

# 风格不良:
if type(obj) is type( 1):

  • 对序列是否空的判断不用 len，如：

    # 风格良好：
if not seq:
if seq:

# 风格不良：
if len(seq):
if not len(seq):

  • 布尔值的比较：

    # 风格良好：
if greeting:

# 不要这样:
if greeting == True:

# 这样更不行：
if greeting is True:
© 2022 刘士. All rights reserved.

结果匹配 ""

    没有匹配的结果 ""