Python語言規範
轉自：
Python語言規範
Lint
Tip
對你的程式碼執行pylint
定義:
pylint是一個在Python原始碼中查詢bug的工具. 對於C和C++這樣的不那麼動態的(譯者注: 原文是less dynamic)語言, 這些bug通常由編譯器來捕獲. 由於Python的動態特性, 有些警告可能不對. 不過偽告警應該很少.
優點:
可以捕獲容易忽視的錯誤, 例如輸入錯誤, 使用未賦值的變數等.
缺點:
pylint不完美. 要利用其優勢, 我們有時侯需要:
- a) 圍繞著它來寫程式碼
- b) 抑制其告警
- c) 改進它, 或者
- d) 忽略它.
結論:
確保對你的程式碼執行pylint.抑制不準確的警告,以便能夠將其他警告暴露出來。
你可以通過設定一個行註釋來抑制警告. 例如:
dict = 'something awful' # Bad Idea... pylint: disable=redefined-builtin
pylint警告是以一個數字編號(如 C0112 )和一個符號名(如 empty-docstring )來標識的. 在編寫新程式碼或更新已有程式碼時對告警進行抑制, 推薦使用符號名來標識.
如果警告的符號名不夠見名知意，那麼請對其增加一個詳細解釋。
採用這種抑制方式的好處是我們可以輕鬆查詢抑制並回顧它們.
你可以使用命令 pylint --list-msgs 來獲取pylint告警列表. 你可以使用命令 pylint --help-msg=C6409 , 以獲取關於特定訊息的更多資訊.
相比較於之前使用的 pylint: disable-msg , 本文推薦使用 pylint: disable .
要抑制”引數未使用”告警, 你可以用””作為引數識別符號, 或者在引數名前加”unused”. 遇到不能改變引數名的情況, 你可以通過在函式開頭”提到”它們來消除告警. 例如:
def foo(a, unused_b, unused_c, d=None, e=None):
_ = d, e
return a
匯入
Tip
僅對包和模組使用匯入
定義:
模組間共享程式碼的重用機制.
優點:
名稱空間管理約定十分簡單. 每個識別符號的源都用一種一致的方式指示. x.Obj表示Obj物件定義在模組x中.
缺點:
模組名仍可能衝突. 有些模組名太長, 不太方便.
結論:
使用 import x 來匯入包和模組.
使用 from x import y , 其中x是包字首, y是不帶字首的模組名.
使用 from x import y as z, 如果兩個要匯入的模組都叫做y或者y太長了.
例如, 模組 sound.effects.echo 可以用如下方式匯入:
from sound.effects import echo
...
echo.EchoFilter(input, output, delay=0.7, atten=4)
匯入時不要使用相對名稱. 即使模組在同一個包中, 也要使用完整包名. 這能幫助你避免無意間匯入一個包兩次.
包
Tip
使用模組的全路徑名來匯入每個模組
優點:
避免模組名衝突. 查詢包更容易.
缺點:
部署程式碼變難, 因為你必須複製包層次.
結論:
所有的新程式碼都應該用完整包名來匯入每個模組.
應該像下面這樣匯入:
# Reference in code with complete name.
import sound.effects.echo
# Reference in code with just module name (preferred).
from sound.effects import echo
異常
Tip
允許使用異常, 但必須小心
定義:
異常是一種跳出程式碼塊的正常控制流來處理錯誤或者其它異常條件的方式.
優點:
正常操作程式碼的控制流不會和錯誤處理程式碼混在一起. 當某種條件發生時, 它也允許控制流跳過多個框架. 例如, 一步跳出N個巢狀的函式, 而不必繼續執行錯誤的程式碼.
缺點:
可能會導致讓人困惑的控制流. 呼叫庫時容易錯過錯誤情況.
結論:
異常必須遵守特定條件:
像這樣觸發異常: raise MyException("Error message") 或者 raise MyException . 不要使用兩個引數的形式( raise MyException, "Error message" )或者過時的字串異常( raise "Error message" ).
模組或包應該定義自己的特定域的異常基類, 這個基類應該從內建的Exception類繼承. 模組的異常基類應該叫做”Error”.
class Error(Exception):
pass
永遠不要使用 except: 語句來捕獲所有異常, 也不要捕獲 Exception 或者 StandardError , 除非你打算重新觸發該異常, 或者你已經在當前執行緒的最外層(記得還是要列印一條錯誤訊息). 在異常這方面, Python非常寬容, except: 真的會捕獲包括Python語法錯誤在內的任何錯誤. 使用 except: 很容易隱藏真正的bug.
儘量減少try/except塊中的程式碼量. try塊的體積越大, 期望之外的異常就越容易被觸發. 這種情況下, try/except塊將隱藏真正的錯誤.
使用finally子句來執行那些無論try塊中有沒有異常都應該被執行的程式碼. 這對於清理資源常常很有用, 例如關閉檔案.
當捕獲異常時, 使用 as 而不要用逗號. 例如
try:
raise Error
except Error as error:
pass
全域性變數
Tip
避免全域性變數
定義:
定義在模組級的變數.
優點:
偶爾有用.
缺點:
匯入時可能改變模組行為, 因為匯入模組時會對模組級變數賦值.
結論:
避免使用全域性變數, 用類變數來代替. 但也有一些例外:
指令碼的預設選項.
模組級常量. 例如: PI = 3.14159. 常量應該全大寫, 用下劃線連線.
有時候用全域性變數來快取值或者作為函式返回值很有用.
如果需要, 全域性變數應該僅在模組內部可用, 並通過模組級的公共函式來訪問.
巢狀/區域性/內部類或函式
Tip
鼓勵使用巢狀/本地/內部類或函式
定義:
類可以定義在方法, 函式或者類中. 函式可以定義在方法或函式中. 封閉區間中定義的變數對巢狀函式是隻讀的.
優點:
允許定義僅用於有效範圍的工具類和函式.
缺點:
巢狀類或區域性類的例項不能序列化(pickled).
結論:
推薦使用.
列表推導(List Comprehensions)
Tip
可以在簡單情況下使用
定義:
列表推導(list comprehensions)與生成器表示式(generator expression)提供了一種簡潔高效的方式來建立列表和迭代器, 而不必藉助map(), filter(), 或者lambda.
優點:
簡單的列表推導可以比其它的列表建立方法更加清晰簡單. 生成器表示式可以十分高效, 因為它們避免了建立整個列表.
缺點:
複雜的列表推導或者生成器表示式可能難以閱讀.
結論:
適用於簡單情況. 每個部分應該單獨置於一行: 對映表示式, for語句, 過濾器表示式. 禁止多重for語句或過濾器表示式. 複雜情況下還是使用迴圈.
Yes:
result = []
for x in range(10):
for y in range(5):
if x * y > 10:
result.append((x, y))
for x in xrange(5):
for y in xrange(5):
if x != y:
for z in xrange(5):
if y != z:
yield (x, y, z)
return ((x, complicated_transform(x))
for x in long_generator_function(parameter)
if x is not None)
squares = [x * x for x in range(10)]
eat(jelly_bean for jelly_bean in jelly_beans
if jelly_bean.color == 'black')
No:
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
return ((x, y, z)
for x in xrange(5)
for y in xrange(5)
if x != y
for z in xrange(5)
if y != z)
預設迭代器和操作符
Tip
如果型別支援, 就使用預設迭代器和操作符. 比如列表, 字典及檔案等.
定義:
容器型別, 像字典和列表, 定義了預設的迭代器和關係測試操作符(in和not in)
優點:
預設操作符和迭代器簡單高效, 它們直接表達了操作, 沒有額外的方法呼叫. 使用預設操作符的函式是通用的. 它可以用於支援該操作的任何型別.
缺點:
你沒法通過閱讀方法名來區分物件的型別(例如, has_key()意味著字典). 不過這也是優點.
結論:
如果型別支援, 就使用預設迭代器和操作符, 例如列表, 字典和檔案. 內建型別也定義了迭代器方法. 優先考慮這些方法, 而不是那些返回列表的方法. 當然，這樣遍歷容器時，你將不能修改容器.
Yes: for key in adict: ...
if key not in adict: ...
if obj in alist: ...
for line in afile: ...
for k, v in dict.iteritems(): ...
No: for key in adict.keys(): ...
if not adict.has_key(key): ...
for line in afile.readlines(): ...
生成器
Tip
按需使用生成器.
定義:
所謂生成器函式, 就是每當它執行一次生成(yield)語句, 它就返回一個迭代器, 這個迭代器生成一個值. 生成值後, 生成器函式的執行狀態將被掛起, 直到下一次生成.
優點:
簡化程式碼, 因為每次呼叫時, 區域性變數和控制流的狀態都會被儲存. 比起一次建立一系列值的函式, 生成器使用的記憶體更少.
缺點:
沒有.
結論:
鼓勵使用. 注意在生成器函式的文件字串中使用”Yields:”而不是”Returns:”.
Lambda函式
Tip
適用於單行函式
定義:
與語句相反, lambda在一個表示式中定義匿名函式. 常用於為 map() 和 filter() 之類的高階函式定義回撥函式或者操作符.
優點:
方便.
缺點:
比本地函式更難閱讀和除錯. 沒有函式名意味著堆疊跟蹤更難理解. 由於lambda函式通常只包含一個表示式, 因此其表達能力有限.
結論:
適用於單行函式. 如果程式碼超過60-80個字元, 最好還是定義成常規(巢狀)函式.
對於常見的操作符，例如乘法操作符，使用 operator 模組中的函式以代替lambda函式. 例如, 推薦使用 operator.mul , 而不是 lambda x, y: x * y .
條件表示式
Tip
適用於單行函式
定義:
條件表示式是對於if語句的一種更為簡短的句法規則. 例如: x = 1 if cond else 2 .
優點:
比if語句更加簡短和方便.
缺點:
比if語句難於閱讀. 如果表示式很長， 難於定位條件.
結論:
適用於單行函式. 在其他情況下，推薦使用完整的if語句.
預設引數值
Tip
適用於大部分情況.
定義:
你可以在函式引數列表的最後指定變數的值, 例如, def foo(a, b = 0): . 如果呼叫foo時只帶一個引數, 則b被設為0. 如果帶兩個引數, 則b的值等於第二個引數.
優點:
你經常會碰到一些使用大量預設值的函式, 但偶爾(比較少見)你想要覆蓋這些預設值. 預設引數值提供了一種簡單的方法來完成這件事, 你不需要為這些罕見的例外定義大量函式. 同時, Python也不支援過載方法和函式, 預設引數是一種”仿造”過載行為的簡單方式.
缺點:
預設引數只在模組載入時求值一次. 如果引數是列表或字典之類的可變型別, 這可能會導致問題. 如果函式修改了物件(例如向列表追加項), 預設值就被修改了.
結論:
鼓勵使用, 不過有如下注意事項:
不要在函式或方法定義中使用可變物件作為預設值.
Yes: def foo(a, b=None):
if b is None:
b = []
No: def foo(a, b=[]):
...
No: def foo(a, b=time.time()): # The time the module was loaded???
...
No: def foo(a, b=FLAGS.my_thing): # sys.argv has not yet been parsed...
...
屬性(properties)
Tip
訪問和設定資料成員時, 你通常會使用簡單, 輕量級的訪問和設定函式. 建議用屬性（properties）來代替它們.
定義:
一種用於包裝方法呼叫的方式. 當運算量不大, 它是獲取和設定屬性(attribute)的標準方式.
優點:
通過消除簡單的屬性(attribute)訪問時顯式的get和set方法呼叫, 可讀性提高了. 允許懶惰的計算. 用Pythonic的方式來維護類的介面. 就效能而言, 當直接訪問變數是合理的, 新增訪問方法就顯得瑣碎而無意義. 使用屬性(properties)可以繞過這個問題. 將來也可以在不破壞介面的情況下將訪問方法加上.
缺點:
屬性(properties)是在get和set方法聲明後指定, 這需要使用者在接下來的程式碼中注意: set和get是用於屬性(properties)的(除了用 @property 裝飾器建立的只讀屬性). 必須繼承自object類. 可能隱藏比如操作符過載之類的副作用. 繼承時可能會讓人困惑.
結論:
你通常習慣於使用訪問或設定方法來訪問或設定資料, 它們簡單而輕量. 不過我們建議你在新的程式碼中使用屬性. 只讀屬性應該用 @property 裝飾器 來建立.
如果子類沒有覆蓋屬性, 那麼屬性的繼承可能看上去不明顯. 因此使用者必須確保訪問方法間接被呼叫, 以保證子類中的過載方法被屬性呼叫(使用模板方法設計模式).
Yes: import math
class Square(object):
"""A square with two properties: a writable area and a read-only perimeter.
To use:
>>> sq = Square(3)
>>> sq.area
9
>>> sq.perimeter
12
>>> sq.area = 16
>>> sq.side
4
>>> sq.perimeter
16
"""
def __init__(self, side):
self.side = side
def __get_area(self):
"""Calculates the 'area' property."""
return self.side ** 2
def ___get_area(self):
"""Indirect accessor for 'area' property."""
return self.__get_area()
def __set_area(self, area):
"""Sets the 'area' property."""
self.side = math.sqrt(area)
def ___set_area(self, area):
"""Indirect setter for 'area' property."""
self._SetArea(area)
area = property(___get_area, ___set_area,
doc="""Gets or sets the area of the square.""")
@property
def perimeter(self):
return self.side * 4
True/False的求值
Tip
儘可能使用隱式false
定義:
Python在布林上下文中會將某些值求值為false. 按簡單的直覺來講, 就是所有的”空”值都被認為是false. 因此0， None, [], {}, “” 都被認為是false.
優點:
使用Python布林值的條件語句更易讀也更不易犯錯. 大部分情況下, 也更快.
缺點:
對C/C++開發人員來說, 可能看起來有點怪.
結論:
儘可能使用隱式的false, 例如: 使用 if foo: 而不是 if foo != []: . 不過還是有一些注意事項需要你銘記在心:
永遠不要用==或者!=來比較單件, 比如None. 使用is或者is not.
注意: 當你寫下 if x: 時, 你其實表示的是 if x is not None . 例如: 當你要測試一個預設值是None的變數或引數是否被設為其它值. 這個值在布林語義下可能是false!
永遠不要用==將一個布林量與false相比較. 使用 if not x: 代替. 如果你需要區分false和None, 你應該用像 if not x and x is not None: 這樣的語句.
對於序列(字串, 列表, 元組), 要注意空序列是false. 因此 if not seq: 或者 if seq: 比 if len(seq): 或 if not len(seq): 要更好.
處理整數時, 使用隱式false可能會得不償失(即不小心將None當做0來處理). 你可以將一個已知是整型(且不是len()的返回結果)的值與0比較.
Yes: if not users:
print 'no users'
if foo == 0:
self.handle_zero()
if i % 10 == 0:
self.handle_multiple_of_ten()
No: if len(users) == 0:
print 'no users'
if foo is not None and not foo:
self.handle_zero()
if not i % 10:
self.handle_multiple_of_ten()
注意‘0’(字串)會被當做true.
過時的語言特性
Tip
儘可能使用字串方法取代字串模組. 使用函式呼叫語法取代apply(). 使用列表推導, for迴圈取代filter(), map()以及reduce().
定義:
當前版本的Python提供了大家通常更喜歡的替代品.
結論:
我們不使用不支援這些特性的Python版本, 所以沒理由不用新的方式.
Yes: words = foo.split(':')
[x[1] for x in my_list if x[2] == 5]
map(math.sqrt, data) # Ok. No inlined lambda expression.
fn(*args, **kwargs)
No: words = string.split(foo, ':')
map(lambda x: x[1], filter(lambda x: x[2] == 5, my_list))
apply(fn, args, kwargs)
詞法作用域(Lexical Scoping)
Tip
推薦使用
定義:
巢狀的Python函式可以引用外層函式中定義的變數, 但是不能夠對它們賦值. 變數繫結的解析是使用詞法作用域, 也就是基於靜態的程式文字. 對一個塊中的某個名稱的任何賦值都會導致Python將對該名稱的全部引用當做區域性變數, 甚至是賦值前的處理. 如果碰到global宣告, 該名稱就會被視作全域性變數.
一個使用這個特性的例子:
def get_adder(summand1):
"""Returns a function that adds numbers to a given number."""
def adder(summand2):
return summand1 + summand2
return adder
(譯者注: 這個例子有點詭異, 你應該這樣使用這個函式: sum = get_adder(summand1)(summand2) )
優點:
通常可以帶來更加清晰, 優雅的程式碼. 尤其會讓有經驗的Lisp和Scheme(還有Haskell, ML等)程式設計師感到欣慰.
缺點:
可能導致讓人迷惑的bug. 例如下面這個依據 PEP-0227 的例子:
i = 4
def foo(x):
def bar():
print i,
# ...
# A bunch of code here
# ...
for i in x: # Ah, i *is* local to Foo, so this is what Bar sees
print i,
bar()
因此 foo([1, 2, 3]) 會列印 1 2 3 3 , 不是 1 2 3 4 .
(譯者注: x是一個列表, for迴圈其實是將x中的值依次賦給i.這樣對i的賦值就隱式的發生了, 整個foo函式體中的i都會被當做區域性變數, 包括bar()中的那個. 這一點與C++之類的靜態語言還是有很大差別的.)
結論:
鼓勵使用.
函式與方法裝飾器
Tip
如果好處很顯然, 就明智而謹慎的使用裝飾器
定義:
用於函式及方法的裝飾器 (也就是@標記). 最常見的裝飾器是@classmethod 和@staticmethod, 用於將常規函式轉換成類方法或靜態方法. 不過, 裝飾器語法也允許使用者自定義裝飾器. 特別地, 對於某個函式 my_decorator , 下面的兩段程式碼是等效的:
class C(object):
@my_decorator
def method(self):
# method body ...
class C(object):
def method(self):
# method body ...
method = my_decorator(method)
優點:
優雅的在函式上指定一些轉換. 該轉換可能減少一些重複程式碼, 保持已有函式不變(enforce invariants), 等.
缺點:
裝飾器可以在函式的引數或返回值上執行任何操作, 這可能導致讓人驚異的隱藏行為. 而且, 裝飾器在匯入時執行. 從裝飾器程式碼的失敗中恢復更加不可能.
結論:
如果好處很顯然, 就明智而謹慎的使用裝飾器. 裝飾器應該遵守和函式一樣的匯入和命名規則. 裝飾器的python文件應該清晰的說明該函式是一個裝飾器. 請為裝飾器編寫單元測試.
避免裝飾器自身對外界的依賴(即不要依賴於檔案, socket, 資料庫連線等), 因為裝飾器執行時這些資源可能不可用(由 pydoc 或其它工具匯入). 應該保證一個用有效引數呼叫的裝飾器在所有情況下都是成功的.
裝飾器是一種特殊形式的”頂級程式碼”. 參考後面關於 Main 的話題.
執行緒
Tip
不要依賴內建型別的原子性.
雖然Python的內建型別例如字典看上去擁有原子操作, 但是在某些情形下它們仍然不是原子的(即: 如果__hash__或__eq__被實現為Python方法)且它們的原子性是靠不住的. 你也不能指望原子變數賦值(因為這個反過來依賴字典).
優先使用Queue模組的 Queue 資料型別作為執行緒間的資料通訊方式. 另外, 使用threading模組及其鎖原語(locking primitives). 瞭解條件變數的合適使用方式, 這樣你就可以使用 threading.Condition 來取代低級別的鎖了.
威力過大的特性
Tip
避免使用這些特性
定義:
Python是一種異常靈活的語言, 它為你提供了很多花哨的特性, 諸如元類(metaclasses), 位元組碼訪問, 任意編譯(on-the-fly compilation), 動態繼承, 物件父類重定義(object reparenting), 匯入黑客(import hacks), 反射, 系統內修改(modification of system internals), 等等.
優點:
強大的語言特性, 能讓你的程式碼更緊湊.
缺點:
使用這些很”酷”的特性十分誘人, 但不是絕對必要. 使用奇技淫巧的程式碼將更加難以閱讀和除錯. 開始可能還好(對原作者而言), 但當你回顧程式碼, 它們可能會比那些稍長一點但是很直接的程式碼更加難以理解.
結論:
在你的程式碼中避免這些特性.