1、Python 代碼風格指南介紹本文檔所提供的編碼規(guī)范，適用于主要的Python發(fā)行版中組成標準庫的Python代碼。請參閱PEP關于Python的C實現(xiàn)的C編碼風格指南的描述。本文檔和PEP257（文檔字符串規(guī)范）改編自Guido的Python Style Guide一文，并從Barrys style guide添加了部分內容作為補充。這篇風格指南隨著時間的推移而逐漸演變，隨著語言本身的變化，一些過去的約定已經過時，并確定了更多新的約定。許多項目都有自己的編碼風格指南。如果有任何沖突，優(yōu)先使用該項目特定的指南。愚蠢地堅持一致性是無知的妖怪Guido的一個重要的見解是，代碼閱讀的次數(shù)比編寫的次數(shù)

2、多。這里提供的指南旨在提高代碼的可讀性，并使各種不同的Python代碼一致。如PEP20所說，“易讀性非常重要”。風格指南是關于一致性的。與本風格指南一致很重要。項目中的一致性更重要。一個模塊或功能中的一致性最重要。最重要的是：知道何時會不一致有時風格指南就不適用了。懷疑時，作出你最佳的判斷?？纯雌渌睦?，并決定什么是最好的。不要猶豫，盡管發(fā)問！特別地：不要只為遵從這個PEP而打破向后兼容性！可以忽略部分風格指南的好理由，不要只為遵從這個PEP而打破向后兼容性！忽視既定指南的一些其他的好理由：1 當應用指南會降低代碼的可讀性，即使對于那些習慣遵照這個PEP來閱讀代碼的人來說。2 與周圍的代碼

3、保持一致也會破壞它（可能是歷史原因）雖然這也是收拾別人爛攤子的好機會（在真正的XP風格中）。3 因為問題代碼先于指南，又沒有其它的修改理由。4 代碼需要兼容老版本，本風格指南不建議使用的Python特性。代碼布局縮進每級縮進用4個空格連續(xù)行的折疊元素應該對齊# 與起始定界符對齊：foo = long_function_name(var_one, var_two, var_three, var_four)# 使用更多的縮進，以區(qū)別于其他代碼def long_function_name( var_one, var_two, var_three, var_four): print(var_one)#

4、 懸掛時，應該增加一級縮進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），加上一個空格，加上開括號，為后面的多行條件創(chuàng)建了一個4個空格的縮進。這會給嵌入if內的縮進語句產生視覺沖突，因為它們也被縮進4個空格。這個PEP沒有明確如何（是否）進一步區(qū)分條件行和if語句內的行。這種情況下，可以接

5、受的選項包括，但不僅限于：# 不增加額外的縮進if (this_is_one_thing and that_is_another_thing): do_something()# 添加一行注釋，這將為支持語法高亮的編輯器提供一些區(qū)分if (this_is_one_thing and that_is_another_thing): # 當兩個條件都是真，我們將要執(zhí)行 do_something()# 在換行的條件語句前，增加額外的縮進if (this_is_one_thing and that_is_another_thing): do_something()多行結構中的結束花括號/中括號/圓括號應

6、該是最后一行的第一個非空白字符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,)制表符還是空格空格是最優(yōu)先的縮進方式當已經使用制表符是，應該保持一致性，繼續(xù)使用制表符Python 3不允許混合使用制表符和空格來縮進。Python 2的代碼中混合使用制表符和空格

7、的縮進，應該轉化為完全使用空格。調用python命令行解釋器時使用-t選項,可對代碼中不合法得混合制表符和空格發(fā)出警告(warnings)。使用-tt時警告(warnings)將變成錯誤(errors).這些選項是被高度推薦的.最大行長度限制所有行最多79個字符。下垂的長塊結構限制為更少的文本（文檔字符串或注釋），行的長度應該限制在72個字符。限制編輯器窗口寬度使得并排打開多個文件成為可能，并且使用代碼審查工具顯示相鄰列的兩個版本工作正常。絕大多數(shù)工具的默認折疊會破壞代碼的可視化結構，使其更難以理解。編輯器中的窗口寬度設置為80個字符。即使該工具將在最后一列中標記字形。一些基于網絡的工具可能不

8、會提供動態(tài)的自動換行。有些團隊強烈喜歡較長的行長度。對于代碼維護完全或主要由一個團隊的，可以在這個問題上達成協(xié)議，象征性的將行長度從80個字符增加到100個字符（有效地增加最大長度到99個字符）也是可以的，提供注釋和文檔字符串仍是72個字符。Python標準庫采取保守做法，要求行限制到79個字符（文檔字符串/注釋到72個字符）。折疊長行的首選方法是使用Pyhon支持的圓括號,方括號(brackets)和花括號(braces)內的行延續(xù)。長行可以在表達式外面使用小括號來變成多行。連續(xù)行使用反斜杠更好。反斜杠有時可能仍然是合適的。例如，長的多行的with語句不能用隱式續(xù)行，可以用反斜杠：# 反斜杠

9、有時可能仍然是合適的。例如，長的多行的with語句不能用隱式續(xù)行，可以用反斜杠：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()另一種類似的情況是在assert語句中確認恰當?shù)乜s進了延續(xù)的行換行應該在二元操作符前面還是后面幾十年來推薦的風格是在二元操作符后換行。但這會通過兩種方式影響可讀性:操作符往往分散在屏幕的不同的列上,并且每個操作符都被移動到遠離其操作數(shù)。在這里,眼

10、睛要做額外的工作看清哪些數(shù)是添加或減去:# 壞的: 操作符遠離它們的操作數(shù)income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)為了解決這個可讀性問題,數(shù)學家和出版商遵循相反的約定。Donald Knuth在他的電腦和排版系列中解釋了傳統(tǒng)規(guī)則:“盡管后一段總是打破內公式二進制操作和關系,顯示公式總是在二進制操作前換行”。以下的數(shù)學運算傳統(tǒng)通?？梢允沟媒Y果更加具有可讀性# 好的: 易于匹配操作數(shù)和操作符income =

11、 (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)#二元運算符首選的換行位置在操作符后面class Rectangle(Blob): def _init_(self, width, height, color=black, emphasis=None, highlight=0): if width = 0 and height = 0 and color = red and emphasis = strong or highli

12、ght 100): raise ValueError(sorry, you lose) if width = 0 and height = 0 and (color = red or emphasis is None): raise ValueError(I dont think so - values are %s, %s % (width, height) Blob._init_(self, width, height, color, emphasis, highlight)在Python代碼中,允許打破之前或之后一個二元運算符的規(guī)則,只要與當前慣例是一致的。為新代碼Knuth的風格?？招?/p>

13、用兩行空行分割頂層函數(shù)和類的定義.類內方法的定義用單個空行分割.額外的空行可被用于(保守的(sparingly)分割一組相關函數(shù)(groups of related functions).在一組相關的單句中間可以省略空行.(例如.一組啞元(a set of dummy implementations).在函數(shù)中使用空行時,請謹慎的用于表示一個邏輯段落(indicate logical sections).Python接受contol-L(即L)換頁符作為空格;Emacs(和一些打印工具) 視這個字符為頁面分割符,因此在你的文件中,可以用他們來為相關片段(sections)分頁。注意，一些編輯器

14、和基于Web的代碼查看器可能不能識別control-L是換頁，將顯示另外的字形。源文件編碼Python核心發(fā)布中的代碼應該始終使用UTF-8（或Python2中用ASCII）。文件使用ASCII（Python2中）或UTF-8（Python3中）不應有編碼聲明。在標準庫中，非默認編碼僅用于測試目的或注釋或文檔字符串需要提及包含非ASCII字符的作者名；否則，使用x，u，U，或N是字符串中包含非ASCII數(shù)據(jù)的首先方式。Python3.0及以上版本，為標準庫（參見PEP 3131）規(guī)定以下策略：Python標準庫中的所有標識符必須使用ASCII標識符，在可行的地方使用英文單詞（在很多例子中，使用

15、非英文的縮寫和專業(yè)術語）。另外，字符串和注釋必須用ASCII。僅有的例外是（a）測試非ASCII的特點，（b）測試作者名。不是基于拉丁字母表的作者名必須提供一個他們名字的拉丁字母表的音譯。開源項目面向全球，鼓勵采用統(tǒng)一策略。導入# 通常應該在單獨的行中導入(Imports)import osimport sys# 這樣也是可以的from subprocess import Popen, PIPEImports 通常被放置在文件的頂部,僅在模塊注釋和文檔字符串之后,在模塊的全局變量和常量之前.Imports 應該有順序地成組安放. 標準庫的導入(Imports ) 相關的第三方導入(即,所有的e

16、mail包在隨后導入) 特定的本地應用/庫導入(imports) 你應該在每組導入之間放置一個空行.把任何相關all規(guī)范放在導入之后。推薦絕對導入，因為它們更易讀，并且如果導入系統(tǒng)配置的不正確（例如當包中的一個目錄在sys.path的最后）它們有更好的表現(xiàn)（或者 至少給出更好的錯誤信息）：import mypkg.siblingfrom mypkg import siblingfrom mypkg.sibling import example明確的相對導入可以被接受用來替代絕對導入，特別是處理復雜的包布局時，絕對導入過于冗長。from . import siblingfrom .sibling

17、 import example標準庫代碼應該避免復雜包布局并使用絕對導入。隱式的相對導入應該永遠不被使用，并且在Python3中已經移除。從一個包含類的模塊中導入類時，下面這樣通常是好的寫法：from myclass import MyClassfrom foo.bar.yourclass import YourClass# 如果這種寫法導致本地名字沖突，那么就這樣寫：import myclassimport foo.bar.yourclass#并使用“myclass.MyClass”和“foo.bar.yourclass.YourClass”來訪問。避免使用通配符導入（from import

18、 *），因為這樣就不清楚哪些名字出現(xiàn)在命名空間，這會讓讀者和許多自動化工具困惑。通配符導入有一種合理的使用情況，重新發(fā)布一個內部接口作為一個公共API的一部分（例如，重寫一個純Python實現(xiàn)的接口，該接口定義從一個可選的加速器模塊并且哪些定義將被重寫提前并不知道）。用這種方式重新命名，下面的有關公共和內部接口的指南仍適用。字符串引號Python中，單引號字符串和雙引號字符串是一樣的,本PEP不建議如此,建議選擇一個并堅持下去。當一個字符串包含單引號字符或雙引號字符時，使用另一種字符串引號來避免字符串中使用反斜杠。這可以提高可讀性。三引號字符串，總是使用雙引號字符，與PEP 257 文檔字符串

19、規(guī)范保持一致。表達式和語句中的空格Guido不喜歡在以下地方出現(xiàn)空格以下情況避免使用多余的空格# 緊挨著圓括號,方括號和花括號的spam(ham1, eggs: 2)# 緊貼在逗號,分號或冒號前的if x = 4: print x, y; x, y = y, x# 在切片中冒號像一個二元操作符，冒號兩側應該有相同數(shù)量的空格（把它看作最低優(yōu)先級的操作符）。# 在一個擴展切片中，兩個冒號必須有相等數(shù)量的空格。# 例外：當一個切片參數(shù)被省略時，該空格也要被省略。ham1:9, ham1:9:3, ham:9:3, ham1:3, ham1:9:hamlower:upper, hamlower:upp

20、er:, hamlower:stephamlower+offset : upper+offsetham: upper_fn(x) : step_fn(x), ham: step_fn(x)hamlower + offset : upper + offset# 緊貼著函數(shù)調用的參數(shù)列表前開式括號(open parenthesis )的spam(1)# 緊貼在索引或切片(slicing?下標?)開始的開式括號前的dctkey = lstindex# 在賦值(或其它)運算符周圍，不要為了與其他的賦值（或其它）操作符對齊，使用不止一個空格。x = 1y = 2long_variable = 3其它建議

21、避免尾隨空格。因為它通常是無形的,它可能會讓人很困惑:如一個反斜杠,后跟一個空格和一個換行符不算作一行延續(xù)標記。有些編輯器不保護它，并且許多項目(如CPython本身)導向鉤子,拒絕它。始終在這些二元運算符兩邊放置一個空格:賦值(=), 比較(=, , !=, , =, in, not in, is, is not), 布爾運算 (and, or, not).如果使用了不同優(yōu)先級的操作符，在低優(yōu)先級操作符周圍增加空格（一個或多個）。不要使用多于一個空格，二元運算符兩側空格數(shù)量相等。i = i + 1submitted += 1x = x*2 - 1hypot2 = x*x + y*yc = (

22、a+b) * (a-b)# 不要在用于指定關鍵字參數(shù)或默認參數(shù)值的=號周圍使用空格,例如:def complex(real, imag=0.0): return magic(r=real, i=imag)# 函數(shù)注釋應該對冒號使用正常規(guī)則，并且，如果存在 - ，兩邊應該有空格def munge(input: AnyStr): .def munge() - AnyStr: .# 結合一個參數(shù)注釋和默認值時,在 = 符號兩邊使用空格(僅僅當那些參數(shù)同時有注釋和一個默認值時)。def munge(sep: AnyStr = None): .def munge(input: AnyStr, sep:

23、AnyStr = None, limit=1000): .# 不要將多條語句寫在同一行上.if foo = blah: do_blah_thing()do_one()do_two()do_three()# 盡管有時可以將if/for/while和一小段主體代碼放在一行，但在一個有多條子句的語句中不要如此。避免折疊長行！# 最好不要if foo = blah: do_blah_thing()for x in lst: total += xwhile t x和x = x和x = y，也可以交換參數(shù)x = y和x != y。sort()和min()操作保證使用 操作符。不管怎樣，最好實現(xiàn)所有六個操作

24、，這樣在其它上下文就不會產生混淆了。 總是使用def語句而不是使用賦值語句綁定lambda表達式到標識符上。風格良好：def f(x): return 2*x風格不良：f = lambda x: 2*x第一種形式意味著所得的函數(shù)對象的名稱是f而不是一般的。這在回溯和字符串表示中更有用。賦值語句的使用消除了lambda表達式可以提供顯示def聲明的唯一好處（例如它可以嵌在更大的表達式里面）。 從Exception而不是BaseException中派生出異常。直接繼承BaseException是保留那些捕捉幾乎總是錯的異常的。設計異常層次結構基于區(qū)別，代碼可能需要捕獲異常，而不是捕獲產生異常的位置

25、。旨在以編程方式回答問題“出了什么問題？”，而不是只說“問題產生了”（參見PEP 3151對這節(jié)課學習內置異常層次結構的一個例子）類的命名規(guī)則適用于此，只是當異常確實是錯誤的時候，需要在異常類名添加“Error”后綴。用于非本地的流控制或其他形式的信號的非錯誤的異常，不需要特殊的后綴。 適當使用異常鏈。Python3中，“raise X from Y”用來表明明確的更換而不失去原來追蹤到的信息。當故意替換一個內部異常（Python 2中使用“raise X”而Python 3.3+中使用“raise X from None”），確保相關的細節(jié)被轉移到新的異常中（比如當轉換KeyError為At

26、tributeError時保留屬性名，或在新的異常消息中嵌入原始異常的文本）。 Python 2中產生異常，使用raise ValueError(message)替換老的形式raise ValueError,message。后一種形式是不合法的Python 3語法。目前使用的形式意味著當異常的參數(shù)很長或包含格式化字符傳時，多虧了小括號,不必再使用續(xù)行符。捕獲異常時，盡可能提及特定的異常，而不是使用空的except：子句。例如，使用：try: import platform_specific_moduleexcept ImportError: platform_specific_module =

27、 None 空的except：子句將捕獲SystemExit和KeyboardInterrupt異常，這使得很難用Control-C來中斷程序，也會掩飾其它的問題。如果想捕獲會導致程序錯誤的所有異常，使用except Exception:（空異常相當于except BaseException:）一條好的經驗法則是限制使用空except子句的兩種情況：1 如果異常處理程序將打印或記錄跟蹤；至少用戶將會意識到有錯誤發(fā)生。2 如果代碼需要做一些清理工作，但是隨后讓異常用raise拋出。處理這種情況用try.finally更好。當用一個名字綁定捕獲異常時，更喜歡Python2.6中添加的明確的名稱綁定

28、語法。try: process_data()except Exception as exc: raise DataProcessingFailedError(str(exc)這是Python3中唯一支持的語法，并避免與舊的基于逗號的語法有關的歧義問題。捕獲操作系統(tǒng)異常時，優(yōu)先使用 Python 3.3引進的明確的異常層次，通過errno值自省。另外，對于所有的try/except子句，限制try子句內只有絕對最少代碼量。這避免掩蓋錯誤。風格良好：try: value = collectionkeyexcept KeyError: return key_not_found(key)else: r

29、eturn handle_value(value)風格不良：try: # 很多代碼 return handle_value(collectionkey)except KeyError: # 捕獲由handle_value()拋出的KeyError return key_not_found(key)當一個資源是一個局部特定的代碼段，它使用后用with語句確保迅速可靠的將它清理掉。也可以使用try/finally語句。無論何時做了除了獲取或釋放資源的一些操作，都應該通過單獨的函數(shù)或方法調用上下文管理器。例如：風格良好：with conn.begin_transaction(): do_stuff_

30、in_transaction(conn)風格不良：with conn: do_stuff_in_transaction(conn)后者的例子沒有提供任何信息表明enter和_exit_方法做了什么，除了事務結束后關閉連接。 在這種情況下，明確是很重要的。返回語句保持一致。函數(shù)中的所有返回語句都有返回值，或都沒有返回值。如果任意一個返回語句有返回值，那么任意沒有返回值的返回語句應該明確指出return None，并且一個顯式的返回語句應該放在函數(shù)結尾（如果可以）。風格良好：def foo(x): if x = 0: return math.sqrt(x) else: return Nonedef

31、 bar(x): if x = 0: return math.sqrt(x)def bar(x): if x 0: return return math.sqrt(x)使用字符串方法代替string模塊。字符串方法總是更快并且與unicode字符串使用相同的API。如果必須向后兼容Python2.0以前的版本，無視這個原則。使用 .startswith() 和 .endswith() 代替字符串切片來檢查前綴和后綴。startswith()和endswith()更清晰，并且減少錯誤率。例如：風格良好：if foo.startswith(bar):風格不良：if foo:3 = bar:對象類型的比較使用isinstance()代替直接比較類型。風格良好：if isi