PEP

PEP 8

  • PEP 8 是 Python 社群共通的程式設計風格指南。由於網路上已經有許多翻譯,且IDE中也有PEP8格式的檢查工具,因此以下只列出重點。

  • 每級縮進用4個空格,而不使用tab。

  • 限制所有行的最大行寬為79字元。
  • 文本長塊,比如文檔字串或注釋,行長度應限制為72個字元。
  • 續行的首選方法是使用小括弧、中括弧和大括弧反斜線仍可能在適當的時候。其次是反斜線。
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())

左括號

  • 括弧中使用垂直隱式縮進或使用首行凸排。後者應該注意第一行要沒有參數,後續行要有縮進。
# 對準左括弧
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)

# 首行凸排不一定是4個空格
foo = long_function_name(
  var_one, var_two,
  var_three, var_four)

if格式

  • if語句跨行時,兩個字元關鍵字(比如if)加上一個空格,再加上左括弧構成了很好的縮進。後續行暫時沒有規定,至少有如下三種格式,建議使用第3種。
# 沒有額外縮進,不是很好看,個人不推薦.
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()

# 額外添加縮進,推薦。
# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

右括號

  • 右邊括弧也可以另起一行。有兩種格式,建議第2種。
# 右括弧不回退,個人不推薦
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',
)

空白列

• 兩行空列分割頂層函數和類的定義。 • 類的方法定義用單個空列分割。 • 額外的空列可以必要的時候用於分割不同的函數組,但是要儘量節約使用。 • 額外的列行可以必要的時候在函數中用於分割不同的邏輯塊,但是要儘量節約使用。 • Python接 contol-L作為空白符;許多工具視它為分頁符,這些要因編輯器而異。

import

  • 一行import只導入一個模組
import os
import sys
from subprocess import Popen, PIPE
  • 導入始終在檔的頂部,在模組注釋和文檔字串之後,在模組全域變數和常量之前。
  • 導入順序如下:標準庫進口,相關的協力廠商庫,本地庫。各組的導入之間要有空行。相關的all放在導入之後。
  • 推薦絕對路徑導入,因為它們通常更可讀,而且往往是表現更好的(或至少提供更好的錯誤消息。
import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example
  • 在絕對路徑比較長的情況下,也可以使用相對路徑:
from . import sibling
from .sibling import example

import class

from myclass import MyClass
from foo.bar.yourclass import YourClass
  • 如果和本地名字有衝突:
import myclass
import foo.bar.yourclass
  • 萬用字元導入(from module import *)應該避免,因為它不清楚命名空間有哪些名稱存,混淆讀者和許多自動化的工具。唯一的例外是重新發佈對外的API時可以考慮使用。

運算式和語句中的空格

  • 括弧裡邊避免空格
# 括弧裡邊避免空格
# Yes
spam(ham[1], {eggs: 2})
# No
spam( ham[ 1 ], { eggs: 2 } )
  • 逗號,冒號,分號之前避免空格
# 逗號,冒號,分號之前避免空格
# Yes
if x == 4: print x, y; x, y = y, x
# No
if x == 4 : print x , y ; x , y = y , x
  • 索引操作中的冒號當作操作符處理前後要有同樣的空格(一個空格或者沒有空格,個人建議是沒有。
# Yes
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]
# No
ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : upper]
ham[ : upper]
  • 函式呼叫的左括弧之前不能有空格
# Yes
spam(1)
dct['key'] = lst[index]

# No
spam (1)
dct ['key'] = lst [index]
  • 賦值等操作符前後不能因為對齊而添加多個空格
# Yes
x = 1
y = 2
long_variable = 3

# No
x             = 1
y             = 2
long_variable = 3
  • 二元運算子兩邊放置一個空格
  • 優先順序高的運算子或操作符的前後不建議有空格。
# 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)
  • 關鍵字參數和預設值參數的前後不要加空格
# 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)
  • 函數注釋中,=前後要有空格,冒號和"->"的前面無空格,後面有空格。 ```python

    Yes

    def munge(input: AnyStr): def munge(sep: AnyStr = None): def munge() -> AnyStr: def munge(input: AnyStr, sep: AnyStr = None, limit=1000):

No

def munge(input: AnyStr=None): def munge(input:AnyStr): def munge(input: AnyStr)->PosInt:


* 通常不推荐复合语句(Compound statements: 多条语句写在同一行)。

```python
# Yes
if foo == 'blah':
    do_blah_thing()
do_one()
do_two()
do_three()

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

PEP 8 的檔案命名規則

Type example
Module module_name.py
Package package_name
Class class ClassName(object):
Exception class ExceptionName(Exception):
Function def function_name():
Method def method_name(self):
Constant GLOBAL_CONSTANT_NAME = 1
Variable var_name = 1

PEP 257: Docstring Conventions

numpy style docstring

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True


def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    The return type must be duplicated in the docstring to comply
    with the NumPy docstring style.

    Parameters
    ----------
    param1
        The first parameter.
    param2
        The second parameter.

    Returns
    -------
    bool
        True if successful, False otherwise.

    """

參考資料

results matching ""

    No results matching ""