Python PEP 8 編碼規範中文版

避免通配符的導入（from import *），由於這樣作會不知道命名空間中存在哪些名字，會使得讀取接口和許多自動化工具之間產生混淆。對於通配符的導入，有一個防護性的作法，即將內部接口從新發布爲公共API的一部分（例如，用可選加速器模塊的定義覆蓋純Python實現的接口，以及重寫那些事先不知道的定義）。
當以這種方式從新發布名稱時，如下關於公共和內部接口的準則仍然適用。

Module level dunder names 模塊級的「呆」名

像__all__ , __author__ , __version__ 等這樣的模塊級「呆名「（也就是名字裏有兩個前綴下劃線和兩個後綴下劃線），應該放在文檔字符串的後面，以及除from __future__ 以外的import表達式前面。Python要求未來在模塊中的導入，必須出如今除文檔字符串以外的其餘代碼以前。
好比：

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

String Quotes 字符串引號

在Python中，單引號和雙引號字符串是相同的。PEP不會爲這個給出建議。選擇一條規則並堅持使用下去。當一個字符串中包含單引號或者雙引號字符的時候，使用和最外層不一樣的符號來避免使用反斜槓，從而提升可讀性。
對於三引號字符串，老是使用雙引號字符來與PEP 257中的文檔字符串約定保持一致。

Whitespace in Expressions and Statements 表達式和語句中的空格

Pet Peeves 不能忍受的事情

在下列狀況下，避免使用無關的空格：

緊跟在小括號，中括號或者大括號後。

Yes: spam(ham[1], {eggs: 2})

No: spam( ham[ 1 ], { eggs: 2 } )

1緊貼在逗號、分號或者冒號以前。

Yes: if x == 4: print x, y; x, y = y, x

No: if x == 4 : print x , y ; x , y = y , x

1然而，冒號在切片中就像二元運算符，在兩邊應該有相同數量的空格（把它當作優先級最低的操做符）。在擴展的切片操做中，全部的冒號必須有相同的間距。例外狀況：當一個切片參數被省略時，空格就被省略了。
推薦：

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]

1緊貼在函數參數的左括號以前。

Yes: spam(1)

No: spam (1)

緊貼索引或者切片的左括號以前。

Yes: dct['key'] = lst[index]

No: dct ['key'] = lst [index]

爲了和另外一個賦值語句對齊，在賦值運算符附件加多個空格。
推薦：

x = 1

y = 2

long_variable = 3

不推薦：

x = 1

y = 2

long_variable = 3

Other Recommendations 其餘建議

避免在尾部添加空格。由於尾部的空格一般都看不見，會產生混亂：好比，一個反斜槓後面跟一個空格的換行符，不算續行標記。有些編輯器不會保留尾空格，而且不少項目（像CPython）在pre-commit的掛鉤調用中會過濾掉尾空格。
老是在二元運算符兩邊加一個空格：賦值（=），增量賦值（+=，-=），比較（==,<,>,!=,<>,<=,>=,in,not,in,is,is not），布爾（and, or, not）。
若是使用具備不一樣優先級的運算符，請考慮在具備最低優先級的運算符周圍添加空格。有時須要經過本身來判斷；可是，不要使用一個以上的空格，而且在二元運算符的兩邊使用相同數量的空格。
推薦：

i = i + 1

submitted += 1

x = x*2 - 1

hypot2 = x*x + y*y

c = (a+b) * (a-b)

不推薦：

i=i+1

submitted +=1

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): ...

1不推薦：

def munge(input: AnyStr=None): ...

def munge(input: AnyStr, limit = 1000): ...

複合語句(同一行中的多個語句)一般是不容許的。
推薦：

if foo == 'blah':

do_blah_thing()

do_one()

do_two()

do_three()

4最好別這樣：

if foo == 'blah': do_blah_thing()

do_one(); do_two(); do_three()

1雖然有時候將小的代碼塊和 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()

Comments 註釋

與代碼相矛盾的註釋比沒有註釋還糟，當代碼更改時，優先更新對應的註釋！
註釋應該是完整的句子。若是一個註釋是一個短語或句子，它的第一個單詞應該大寫，除非它是以小寫字母開頭的標識符(永遠不要改變標識符的大小寫！)。
若是註釋很短，結尾的句號能夠省略。塊註釋通常由完整句子的一個或多個段落組成，而且每句話結束有個句號。
在句尾結束的時候應該使用兩個空格。
當用英文書寫時，遵循Strunk and White （譯註：《Strunk and White, The Elements of Style》）的書寫風格。
在非英語國家的Python程序員，請使用英文寫註釋，除非你120%的確信你的代碼不會被使用其餘語言的人閱讀。

Block Comments 塊註釋

塊註釋一般適用於跟隨它們的某些（或所有）代碼，並縮進到與代碼相同的級別。塊註釋的每一行開頭使用一個#和一個空格（除非塊註釋內部縮進文本）。
塊註釋內部的段落經過只有一個#的空行分隔。

Inline Comments 行內註釋

有節制地使用行內註釋。
行內註釋是與代碼語句同行的註釋。行內註釋和代碼至少要有兩個空格分隔。註釋由#和一個空格開始。
事實上，若是狀態明顯的話，行內註釋是沒必要要的，反而會分散注意力。好比說下面這樣就不須要：

x = x + 1 # Increment x

但有時，這樣作頗有用：

x = x + 1 # Compensate for border

Documentation Strings 文檔字符串

編寫好的文檔說明（也叫「docstrings」）的約定在PEP 257中永恆不變。

要爲全部的公共模塊，函數，類以及方法編寫文檔說明。非公共的方法沒有必要，可是應該有一個描述方法具體做用的註釋。這個註釋應該在def那一行以後。
PEP 257 描述了寫出好的文檔說明相關的約定。特別須要注意的是，多行文檔說明使用的結尾三引號應該自成一行，例如：

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.

"""

1對於單行的文檔說明，尾部的三引號應該和文檔在同一行。

Naming Conventions 命名規範

Python庫的命名規範很亂，歷來沒能作到徹底一致。可是目前有一些推薦的命名標準。新的模塊和包（包括第三方框架）應該用這套標準，但當一個已有庫採用了不一樣的風格，推薦保持內部一致性。

Overriding Principle 最重要的原則

那些暴露給用戶的API接口的命名，應該遵循反映使用場景而不是實現的原則。

Descriptive: Naming Styles 描述：命名風格

有許多不一樣的命名風格。這裏可以幫助你們識別正在使用什麼樣的命名風格，而不考慮他們爲何使用。
如下是常見的命名方式：

b（單個小寫字母）
B（單個大寫字母）
lowercase 小寫字母
lower_case_with_underscores 使用下劃線分隔的小寫字母
UPPERCASE 大寫字母
UPPER_CASE_WITH_UNDERSCORES 使用下劃線分隔的大寫字母
CapitalizedWords（或者叫 CapWords，或者叫CamelCase 駝峯命名法 —— 這麼命名是由於字母看上去有起伏的外觀5）。有時候也被稱爲StudlyCaps。
注意：當在首字母大寫的風格中用到縮寫時，全部縮寫的字母用大寫，所以，HTTPServerError 比 HttpServerError 好。
mixedCase（不一樣於首字母大寫，第一個單詞的首字母小寫）
Capitalized_Words_With_Underscores（巨醜無比！）

也有用惟一的短前綴把相關命名組織在一塊兒的方法。這在Python中不經常使用，但仍是提一下。好比，os.stat()函數中包含相似以st_mode，st_size，st_mtime這種傳統命名方式命名的變量。（這麼作是爲了與 POSIX 系統的調用一致，以幫助程序員熟悉它。）
X11庫的全部公共函數都加了前綴X。在Python裏面不必這麼作，由於屬性和方法在調用的時候都會用類名作前綴，函數名用模塊名作前綴。
另外，下面這種用前綴或結尾下劃線的特殊格式是被承認的（一般和一些約定相結合）：

_single_leading_underscore：（單下劃線開頭）弱「內部使用」指示器。好比 from M import * 是不會導入如下劃線開始的對象的。
single_trailing_underscore_：（單下劃線結尾）這是避免和Python內部關鍵詞衝突的一種約定，好比：Tkinter.Toplevel(master, class_=’ClassName’)
__double_leading_underscore：（雙下劃線開頭）當這樣命名一個類的屬性時，調用它的時候名字會作矯正（在類FooBar中，__boo變成了_FooBar__boo；見下文）。
__double_leading_and_trailing_underscore__：（雙下劃線開頭，雙下劃線結尾）「magic」對象或者存在於用戶控制的命名空間內的屬性，例如：__init__,__import__或者__file__。除了做爲文檔以外，永遠不要命這樣的名。

Prescriptive: Naming Conventions 約定俗成：命名約定

Names to Avoid 應避免的名字

永遠不要使用字母‘l’（小寫的L），‘O’（大寫的O），或者‘I’（大寫的I）做爲單字符變量名。
在有些字體裏，這些字符沒法和數字0和1區分，若是想用‘l’，用‘L’代替。

Package and Module Names 包名和模塊名

模塊應該用簡短全小寫的名字，若是爲了提高可讀性，下劃線也是能夠用的。Python包名也應該使用簡短全小寫的名字，但不建議用下劃線。
當使用C或者C++編寫了一個依賴於提供高級（更面向對象）接口的Python模塊的擴展模塊，這個C/C++模塊須要一個下劃線前綴（例如：_socket）

Class Names 類名

類名通常使用首字母大寫的約定。
在接口被文檔化而且主要被用於調用的狀況下，可使用函數的命名風格代替。
注意，對於內置的變量命名有一個單獨的約定：大部份內置變量是單個單詞（或者兩個單詞鏈接在一塊兒），首字母大寫的命名法只用於異常名或者內部的常量。

Exception Names 異常名

由於異常通常都是類，全部類的命名方法在這裏也適用。然而，你須要在異常名後面加上「Error」後綴（若是異常確實是一個錯誤）。

Global Variable Names 全局變量名

（咱們但願這一類變量只在模塊內部使用。）約定和函數命名規則同樣。
經過 from M import * 導入的模塊應該使用all機制去防止內部的接口對外暴露，或者使用在全局變量前加下劃線的方式（代表這些全局變量是模塊內非公有）。

Function Names 函數名

函數名應該小寫，若是想提升可讀性能夠用下劃線分隔。
大小寫混合僅在爲了兼容原來主要以大小寫混合風格的狀況下使用（好比 threading.py），保持向後兼容性。

Function and method arguments 函數和方法參數

始終要將 self 做爲實例方法的的第一個參數。
始終要將 cls 做爲類靜態方法的第一個參數。
若是函數的參數名和已有的關鍵詞衝突，在最後加單一下劃線比縮寫或隨意拼寫更好。所以 class_ 比 clss 更好。（也許最好用同義詞來避免這種衝突）

Method Names and Instance Variables 方法名和實例變量

遵循這樣的函數命名規則：使用下劃線分隔小寫單詞以提升可讀性。
在非共有方法和實例變量前使用單下劃線。
經過雙下劃線前綴觸發Python的命名轉換規則來避免和子類的命名衝突。
Python經過類名對這些命名進行轉換：若是類 Foo 有一個叫 __a 的成員變量，它沒法經過 Foo.__a 訪問。（執着的用戶能夠經過 Foo._Foo__a 訪問。）通常來講，前綴雙下劃線用來避免類中的屬性命名與子類衝突的狀況。
注意：關於__names的用法存在爭論（見下文）。

Constants 常量

常量一般定義在模塊級，經過下劃線分隔的全大寫字母命名。例如： MAX_OVERFLOW 和 TOTAL。

Designing for inheritance 繼承的設計

始終要考慮到一個類的方法和實例變量（統稱：屬性）應該是共有仍是非共有。若是存在疑問，那就選非共有；由於將一個非共有變量轉爲共有比反過來更容易。
公共屬性是那些與類無關的客戶使用的屬性，並承諾避免向後不兼容的更改。非共有屬性是那些不打算讓第三方使用的屬性；你不須要承諾非共有屬性不會被修改或被刪除。
咱們不使用「私有（private）」這個說法，是由於在Python中目前尚未真正的私有屬性（爲了不大量沒必要要的常規工做）。
另外一種屬性做爲子類API的一部分（在其餘語言中一般被稱爲「protected」）。有些類是專爲繼承設計的，用來擴展或者修改類的一部分行爲。當設計這樣的類時，要謹慎決定哪些屬性時公開的，哪些是做爲子類的API，哪些只能在基類中使用。
貫徹這樣的思想，一下是一些讓代碼Pythonic的準則：

公共屬性不該該有前綴下劃線。
若是公共屬性名和關鍵字衝突，在屬性名以後增長一個下劃線。這比縮寫和隨意拼寫好不少。（然而，儘管有這樣的規則，在做爲參數或者變量時，‘cls’是表示‘類’最好的選擇，特別是做爲類方法的第一個參數。）
注意1：參考以前的類方法參數命名建議
對於單一的共有屬性數據，最好直接對外暴露它的變量名，而不是經過負責的存取器（accessor）/突變（mutator）方法。請記住，若是你發現一個簡單的屬性須要成長爲一個功能行爲，那麼Python爲這種未來會出現的擴展提供了一個簡單的途徑。在這種狀況下，使用屬性去隱藏屬性數據訪問背後的邏輯。
注意1：屬性只在new-style類中起做用。
注意2：儘管功能方法對於相似緩存的負面影響比較小，但仍是要儘可能避免。
注意3：屬性標記會讓調用者認爲開銷（至關的）小，避免用屬性作開銷大的計算。
若是你的類打算用來繼承的話，而且這個類裏有不但願子類使用的屬性，就要考慮使用雙下劃線前綴而且沒有後綴下劃線的命名方式。這會調用Python的命名轉換算法，將類的名字加入到屬性名裏。這樣作能夠幫助避免在子類中不當心包含了相同的屬性名而產生的衝突。
注意1：只有類名纔會整合進屬性名，若是子類的屬性名和類名和父類都相同，那麼你仍是會有命名衝突的問題。
注意2：命名轉換會在某些場景使用起來不太方便，例如調試，__getattr__()。然而命名轉換的算法有很好的文檔說明而且很好操做。
注意3：不是全部人都喜歡命名轉換。儘可能避免意外的名字衝突和潛在的高級調用。

Public and internal interfaces 公共和內部的接口

任何向後兼容保證只適用於公共接口，所以，用戶清晰地區分公共接口和內部接口很是重要。
文檔化的接口被認爲是公開的，除非文檔明確聲明它們是臨時或內部接口，不受一般的向後兼容性保證。全部未記錄的接口都應該是內部的。
爲了更好地支持內省（introspection），模塊應該使用__all__屬性顯式地在它們的公共API中聲明名稱。將__all__設置爲空列表表示模塊沒有公共API。
即便經過__all__設置過，內部接口（包，模塊，類，方法，屬性或其餘名字）依然須要單個下劃線前綴。
若是一個命名空間（包，模塊，類）被認爲是內部的，那麼包含它的接口也應該被認爲是內部的。
導入的名稱應該始終被視做是一個實現的細節。其餘模塊必須不能間接訪問這樣的名稱，除非它是包含它的模塊中有明確的文檔說明的API，例如 os.path 或者是一個包裏從子模塊公開函數接口的 __init__ 模塊。

Programming Recommendations 編程建議

代碼應該用不損害其餘Python實現的方式去編寫（PyPy，Jython，IronPython，Cython，Psyco 等）。
好比，不要依賴於在CPython中高效的內置字符鏈接語句 a += b 或者 a = a + b。這種優化甚至在CPython中都是脆弱的（它只適用於某些類型）而且沒有出如今不使用引用計數的實現中。在性能要求比較高的庫中，能夠種」.join() 代替。這能夠確保字符關聯在不一樣的實現中均可以以線性時間發生。
和像None這樣的單例對象進行比較的時候應該始終用 is 或者 is not，永遠不要用等號運算符。
另外，若是你在寫 if x 的時候，請注意你是否表達的意思是 if x is not None。舉個例子，當測試一個默認值爲None的變量或者參數是否被設置爲其餘值的時候。這個其餘值應該是在上下文中能成爲bool類型false的值。
使用 is not 運算符，而不是 not … is 。雖然這兩種表達式在功能上徹底相同，但前者更易於閱讀，因此優先考慮。
推薦：

if foo is not None:

不推薦：

if not foo is None:

1
- 當使用富比較（rich comparisons，一種複雜的對象間比較的新機制，容許返回值不爲-1,0,1）實現排序操做的時候，最好實現所有的六個操做符（__eq__, __ne__, __lt__, __gt__, __ge__）而不是依靠其餘的代碼去實現特定的比較。
  爲了最大程度減小這一過程的開銷， functools.total_ordering() 修飾符提供了用於生成缺乏的比較方法的工具。
  PEP 207 指出Python實現了反射機制。所以，解析器會將 y > x 轉變爲 x < y，將 y >= x 轉變爲 x <= y，也會轉換x == y 和 x != y的參數。sort() 和 min()方法確保使用<操做符，max()使用>操做符。然而，最好仍是實現所有六個操做符，以避免在其餘地方出現衝突。
- 始終使用def表達式，而不是經過賦值語句將lambda表達式綁定到一個變量上。
  推薦：

def f(x): return 2*x

不推薦：

f = lambda x: 2*x

第一個形式意味着生成的函數對象的名稱是「f」而不是泛型「< lambda >」。這在回溯和字符串顯示的時候更有用。賦值語句的使用消除了lambda表達式優於顯式def表達式的惟一優點（即lambda表達式能夠內嵌到更大的表達式中）。

從Exception繼承異常，而不是BaseException。直接繼承BaseException的異常適用於幾乎不用來捕捉的異常。
設計異常的等級，要基於撲捉異常代碼的須要，而不是異常拋出的位置。以編程的方式去回答「出了什麼問題？」，而不是隻是確認「出現了問題」（內置異常結構的例子參考 PEP 3151 ）
類的命名規範適用於這裏，可是你須要添加一個「Error」的後綴到你的異常類，若是異常是一個Error的話。非本地流控制或者其餘形式的信號的非錯誤異常不須要特殊的後綴。
適當地使用異常連接。在Python 3裏，爲了避免丟失原始的根源，能夠顯式指定「raise X from Y」做爲替代。
當故意替換一個內部異常時（Python 2 使用「raise X」， Python 3.3 以後使用「raise X from None」），確保相關的細節轉移到新的異常中（好比把AttributeError轉爲KeyError的時候保留屬性名，或者將原始異常信息的文本內容內嵌到新的異常中）。
在Python 2中拋出異常時，使用 rasie ValueError(‘message’) 而不是用老的形式 raise ValueError, ‘message’。
第二種形式在Python3 的語法中不合法
使用小括號，意味着當異常裏的參數很是長，或者包含字符串格式化的時候，不須要使用換行符。
當捕獲到異常時，若是能夠的話寫上具體的異常名，而不是隻用一個except: 塊。
好比說：

try:

import platform_specific_module

except ImportError:

platform_specific_module = None

若是隻有一個except: 塊將會捕獲到SystemExit和KeyboardInterrupt異常，這樣會很難經過Control-C中斷程序，並且會掩蓋掉其餘問題。若是你想捕獲全部指示程序出錯的異常，使用 except Exception: （只有except等價於 except BaseException:）。
兩種狀況不該該只使用‘excpet’塊：

1. 若是異常處理的代碼會打印或者記錄log；至少讓用戶知道發生了一個錯誤。

2. 若是代碼須要作清理工做，使用 raise..try…finally 能很好處理這種狀況而且能讓異常繼續上浮。

1. 當給捕捉的異常綁定一個名字時，推薦使用在Python 2.6中加入的顯式命名綁定語法：

try:

process_data()

except Exception as exc:

raise DataProcessingFailedError(str(exc))

爲了不和原來基於逗號分隔的語法出現歧義，Python3只支持這一種語法。

當捕捉操做系統的錯誤時，推薦使用Python 3.3 中errno內定數值指定的異常等級。
另外，對於全部的 try/except 語句塊，在try語句中只填充必要的代碼，這樣能避免掩蓋掉bug。
推薦：

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)

1當代碼片斷局部使用了某個資源的時候，使用with 表達式來確保這個資源使用完後被清理乾淨。用try/finally也能夠。
- 不管什麼時候獲取和釋放資源，都應該經過單獨的函數或方法調用上下文管理器。舉個例子：
  推薦：

with conn.begin_transaction():

do_stuff_in_transaction(conn)

不推薦：

with conn:

do_stuff_in_transaction(conn)

1第二個例子沒有提供任何信息去指明__enter__和__exit__方法在事務以後作出了關閉鏈接以外的其餘事情。這種狀況下，明確指明很是重要。
- 返回的語句保持一致。函數中的返回語句都應該返回一個表達式，或者都不返回。若是一個返回語句須要返回一個表達式，那麼在沒有值能夠返回的狀況下，須要用 return None 顯式指明，而且在函數的最後顯式指定一條返回語句（若是能跑到那的話）。
  推薦：

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)

使用字符串方法代替字符串模塊。
字符串方法老是更快，而且和unicode字符串分享相同的API。若是須要兼容Python2.0以前的版本能夠不用考慮這個規則。
使用」.startswith() 和」.endswith() 代替經過字符串切割的方法去檢查前綴和後綴。
startswith()和endswith()更乾淨，出錯概率更小。好比：