Python 编码风格与规范

Python 编码风格与规范 | 极客日志

# 与定界（括号）符对齐
foo = long_function_name(var_one, var_two, var_three, var_four)
# 换行并增加 4 个额外的空格（一级缩进）
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)

# 与最后一行的非空字符对齐
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',
)

yes = ('y', 'Y', 'yes', 'TRUE', 'True', 'true', 'On', 'on', '1')
# 基本不再改变
kwlist = [
    'False', 'None', 'True', 'and', 'as', 'assert',
    ...
    'yield', # 最后一个元素也增加一个逗号，方便以后 diff 不显示此行
]
person = {
    'name': 'bob',
    'age': 12, # 可能经常增加字段
}

# 关键字会不断增加，每个元素都换行
kwlist = ['False', 'None', 'True', 'and', 'as', 'assert', 'async', ...]
person = {'name': 'bob', 'age': 12}

# 更推荐：在续行中，增加额外的缩进级别。允许 and 操作符在前
if (this_is_one_thing and that_is_another_thing):
    do_something()
# 更推荐：在续行中，增加额外的缩进级别
if (this_is_one_thing and that_is_another_thing):
    do_something()
# 允许：与定界符（括号）对齐，不需要额外的缩进
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()

x = ('This will build a very long long '
     'long long long long long long string')

x = y + 1

x=y+1
x = y+1

# YES: 尾部没有空白符号
para = {}
para = {} # comment

# No: 结尾存在多余空白符号
para = {}   
para = {} # comment

# YES: 易于将运算符与操作数匹配，可读性高
income = (
    gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest
)

# No: 运算符的位置远离其操作数
income = (
    gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest
)

trailingcomma = (['f'],)
return (1,)

trailingcomma = ['f'], # tuple
return 1,

if foo:
    bar(foo)
else:
    baz(foo)
try:
    bar(foo)
except ValueError:
    baz(foo)

if foo: bar(foo) else: baz(foo)
try: bar(foo) except ValueError: baz(foo)
try: bar(foo) except ValueError: baz(foo)

"""This is the example module. This module does stuff."""
import os

def foo():
    pass

class MyClass():
    def __init__(self):
        pass
    def foo(self):
        pass

class AnotherClass(object):
    """Another class. This is some comments for another class"""
    def __init__(self, a, b):
        if a > b:
            self._min = b
            self._max = a
        else:
            self._min = a
            self._max = b
        self._gap = self._max = self._min
    def foo(self):
        pass

# -*- coding: utf-8 -*-

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import os
import sys

import os, sys

import foo
from foo import bar
from foo.bar import baz
from foo.bar import Quux
from Foob import ar

import os # used
dir_path = os.path.abspath('.')

import os # unused !
# dir_path = os.path.abspath('.')

# -*- coding: utf-8 -*-
#
"""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

# this is a very complex operation, please
# read this carefully
if i & (i-1) == 0:
    # do my job
    ...
# 单行注释，为可读性，至少离开代码 2 个空格
x = x + 1 # Compensate for border

# TODO(zhangsan): Change this to use relations.
# FIXME([email protected]): Please fix me here.
# NOTES(zhangsan): This is some notes.

def foobar():
    """Return a foobang Optional plotz says to frobnicate the bizbaz first."""

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.
    Retrieves rows pertaining to the given keys from the Table instance represented by big_table.
    Silly things may happen if other_silly_variable is not None.
    :param big_table: An open Bigtable Table instance.
    :param keys: A sequence of strings representing the key of each table row to fetch.
    :param other_silly_variable: Another optional variable, that has a much longer name than the other args, and which does nothing.
    :return: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {'Serak': ('Rigel VII', 'Preparer'), 'Zim': ('Irk', 'Invader'), 'Lrrr': ('Omicron Persei 8', 'Emperor')} If a key from the keys argument is missing from the dictionary, then that row was not found in the table.
    :raises ValueError: if `keys` is empty.
    :raises IOError: An error occurred accessing the bigtable.Table object.
    """
    pass

class SampleClass(object):
    """Summary of class here. Longer class information.... Longer class information....
    :ivar likes_spam: A boolean indicating if we like SPAM or not.
    :ivar eggs: An integer count of the eggs we have laid.
    """
    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0
    def public_method(self):
        """Performs operation blah."""

from typing import List

class Container(object):
    def __init__(self) -> None:
        self.elements: List[int] = []
    def append(self, element: int) -> None:
        self.elements.append(element)
    def greeting(name: str) -> str:
        return 'Hello ' + name

# 变量定义
lang: str = 'zh'
success_code: int = 0

code: int = 10

class Point(object):
    coords: Tuple[int, int] = (0, 0)
    label: str = '<unknown>'

def broadcast(servers: Sequence[Server], message: str = 'spaces around equality sign') -> None:
    pass

code:int # No space after colon
code : int # Space before colon
class Test(object):
    result: int=0 # No spaces around equality sign

import typing
if typing.TYPE_CHECKING:
    # 运行时不导入
    # For type annotation
    from typing import Any, Dict, List, Sequence # NOQA
    from sphinx.application import Sphinx # NOQA

class Parser(docutils.parsers.Parser):
    def set_application(self, app: "Sphinx") -> None:
        # 同时采用引号
        pass

# 更推荐
x = f'name: {name}; score: {n}' # Python3.6+ 以上支持
x = 'name: {name}; score: {n}'.format(name=name, n=n)
x = 'name: {name}; score: {n}'.format(**{"name": name, "n": n})
x = 'name: %(name)s; score: %(n)d' % {"name": name, "n": n}
# 可接受
x = '%s, %s!' % (imperative, expletive)
x = '{}, {}!'.format(imperative, expletive)
x = 'name: %s; score: %d' % (name, n)
x = 'name: {}; score: {}'.format(name, n)

x = '%s%s' % (a, b) # use + in this case
x = '{}{}'.format(a, b) # use + in this case
x = imperative + ', ' + expletive + '!'
x = 'name: ' + name + '; score: ' + str(n)

items = ['<table>']
for last_name, first_name in employee_list:
    items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
items.append('</table>')
html_content = ''.join(items)

employee_table = '<table>'
for last_name, first_name in employee_list:
    employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
employee_table += '</table>'

Python('Why are you hiding your eyes?')
Gollum("I'm scared of lint errors.")
Narrator('"Good!" thought a happy Python reviewer.')

Python("Why are you hiding your eyes?")
Gollum('The lint. It burns. It burns us.')
Gollum("Always the great lint. Watching. Watching.")

print("This is much nicer.\n"
      "Do it this way.\n")

print("""This is pretty ugly. Don't do this. """)

if foo.startswith('bar'):

if foo[:3] == 'bar':

with open("hello.txt") as hello_file:
    for line in hello_file:
        print(line)

import contextlib
with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
    for line in front_page:
        print(line)

def main():
    ...

if __name__ == '__main__':
    main()

Type	Public	Internal
Modules	lower_with_under	_lower_with_under
Packages	lower_with_under
Classes	CapWords	_CapWords
Exceptions	CapWords
Functions	lower_with_under()	_lower_with_under()
Global/Class Constants	CAPS_WITH_UNDER	_CAPS_WITH_UNDER
Global/Class Variables	lower_with_under	_lower_with_under
Instance Variables	lower_with_under	_lower_with_under (protected) or __lower_with_under (private)
Method Names	lower_with_under()	_lower_with_under() (protected) or __lower_with_under() (private)
Function/Method Parameters	lower_with_under
Local Variables	lower_with_under

x = a if a >= b else b

x = a >= b and a or b

if foo is not None:

if not foo is None:

def f(x):
    return 2 * x

f = lambda x: 2 * x

raise ValueError('message')

raise ValueError, 'message'

try:
    import platform_specific_module
except ImportError:
    platform_specific_module = None

try:
    do_something()
except Exception as ex:
    # pylint: disable=broad-except
    log.exception(ex) # 应将错误堆栈打印到日志文件中，以供后续排查。
    handle_exception_or_not() # 除打印日志外，还可以进一步处理如清理资源等，可选。

try:
    import platform_specific_module
except Exception: # broad-except
    platform_specific_module = None

try:
    do_something()
except Exception: # 框架等未明确异常场景，建议增加 traceback 打印
    pass

def write_data():
    if check_file_exist():
        do_something()
    else:
        raise FileNotExist()

def write_data():
    if check_file_exist():
        do_something()
        return 0
    else:
        return FILE_NOT_EXIST

try:
    raise MyException()
except MyException as ex:
    try_handle_exception()
    raise # 可以保留原始的 traceback

try:
    raise MyException()
except MyException as ex:
    log.exception(ex)
    raise AnotherException(str(ex)) # 允许的，建议保留好之前的异常栈信息，用于定位问题

try:
    raise MyException()
except MyException as ex:
    try_handle_exception()
    raise ex # 异常栈信息从这里开始，原始的 raise 异常栈信息消息

try:
    value = collection[key]
except KeyError:
    return key_not_found(key)
else:
    return handle_value(value)

try:
    # 范围太广
    return handle_value(collection[key])
except KeyError:
    # 会捕捉到 handle_value() 中的 KeyError
    return key_not_found(key)

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)

def f(x):
    if x in ('SUCCESS',):
        return True
    else:
        raise MyException() # 如果一定不会走到的条件，可以增加异常，防止将来未知的语句执行。

def f(x):
    if x in ('SUCCESS',):
        return True
    return None

if condition:
    do_something()
else:
    # 增加说明注释
    pass

if condition:
    do_something()
    # 这里增加注释说明为什么不用写 else 子句
    # else: # pass

if condition:
    do_something()
if another_condition: # 不能确定是否笔误为 elif，还是开启全新一个 if 条件
    do_another_something()
else:
    do_else_something()

if greeting:
    pass

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

if not seq:
    pass
if seq:
    pass

if len(seq):
    pass
if not len(seq):
    pass

number_list = [1, 2, 3, 10, 20, 55]
odd = [i for i in number_list if i % 2 == 1]
result = []
for x in range(10):
    for y in range(5):
        if x * y > 10:
            result.append((x, y))

result = [(x, y) for x in range(10) for y in range(5) if x * y > 10] # for 语句

fizzbuzz = []
for n in range(100):
    if n % 3 == 0 and n % 5 == 0:
        fizzbuzz.append(f'fizzbuzz {n}')
    elif n % 3 == 0:
        fizzbuzz.append(f'fizz {n}')
    elif n % 5 == 0:
        fizzbuzz.append(f'buzz {n}')
    else:
        fizzbuzz.append(n)

for n in range(1, 11):
    print(n)

# 条件过于复杂，应该采用 for 语句展开
fizzbuzz = [
    f'fizzbuzz {n}' if n % 3 == 0 and n % 5 == 0 else
    f'fizz {n}' if n % 3 == 0 else
    f'buzz {n}' if n % 5 == 0 else n
    for n in range(100)
]
[print(n) for n in range(1, 11)] # 无返回值

def get_x(x):
    return x

def get_x(x): # 模块内重复定义
    return x

def f(x=0, y=None, z=None):
    if y is None:
        y = []
    if z is None:
        z = {}

def f(x=0, y=[], z={}):
    pass

def f(a, b=time.time()):
    pass

def get_x_plus_y(x, y):
    return x + y

some_unused_var = 42 # 定义了变量不意味着就是使用了
y = 10
y = 5 # 对自身的操作并不意味着使用了
z = 0
z = z + 1 # 未使用的函数参数
def get_x(x, y):
    return x

flake8 {source_file_or_directory}

[flake8]
ignore = ;W503 line break before binary operator
         W503,
         ;E203 whitespace before ':'
         E203,
exclude = .tox, .git, __pycache__, build, dist, *.pyc, *.egg-info, .cache, .eggs
max-line-length = 120

example = lambda: 'example' # noqa: E731

pylint {source_file_or_directory}

try:
    do_something()
except Exception as ex:
    # pylint: disable=broad-except
    pass

# pylint: disable=invalid-name
app = Flask(__name__)
# pylint: enable=invalid-name

black {source_file_or_directory}

# fmt: off
# 在这的代码不会被格式化
# fmt: on

# https://editorconfig.org
root = true
[*]
indent_style = space
indent_size = 4
trim_trailing_whitespace = true
insert_final_newline = true
charset = utf-8
end_of_line = lf
[*.py]
max_line_length = 120
[*.bat]
indent_style = tab
end_of_line = crlf
[LICENSE]
insert_final_newline = false
[Makefile]
indent_style = tab

Python 编码风格与规范

Python 编码风格与规范

一、编码风格

1.1 缩进

1.1.1【必须】

1.1.2【必须】

1.1.3【推荐】

1.1.4【推荐】

1.1.5【可选】

1.2 每行最大长度

1.2.1【必须】

1.3 空白符

1.3.1【必须】

1.3.2【必须】

1.4 操作符

1.4.1【推荐】

1.5 括号

1.5.1【必须】

1.6 空行

1.6.1【必须】

1.6.2【必须】

1.6.3【必须】

1.6.4【必须】

1.6.5【推荐】

1.7 源文件编码

1.7.1【必须】

1.7.2【必须】

1.8 Shebang

1.8.1【必须】

1.9 模块引用 (import)

1.9.1【必须】

1.9.2【必须】

1.9.3【必须】

1.9.4【必须】

1.10 模块中的魔术变量 (dunders)

1.10.1【必须】

1.10.2【必须】

1.11 注释

1.11.1【必须】

1.11.2【必须】

1.11.3【必须】

1.11.4【必须】

1.11.5【必须】

1.12 文档字符串

1.12.1【推荐】

1.12.2【必须】

1.12.3【推荐】

1.12.4【推荐】

1.13 类型提示

1.13.1【必须】

1.13.2【必须】

1.13.3【必须】

1.13.4【推荐】

1.14 字符串

1.14.1【推荐】

1.14.2【推荐】

1.14.3【推荐】

1.14.4【必须】

1.14.5【必须】

1.14.6【可选】

1.14.7【推荐】

1.15 文件和 sockets

1.15.1【必须】

1.15.2【推荐】

1.16 访问控制

1.16.1【推荐】

1.17 Main

1.17.1【必须】

1.18 命名

1.18.1【推荐】

二、编码规范

2.1 三目运算符

2.1.1【必须】

2.2 None 条件的判断

2.2.1【必须】

2.3 lambda 匿名函数

2.3.1【必须】

2.4 异常

2.4.1【必须】

2.4.2【必须】