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.
"""