Python PEP8 编码规范中文版
Python PEP8 編碼規(guī)范中文版
2018年01月02日 19:21:09?閱讀數(shù)：22140?標(biāo)簽：?python?更多 個人分類：?Python原文鏈接：http://legacy.python.org/dev/peps/pep-0008/
| PEP | 8 |
| Title | Style Guide for Python Code |
| Version | c451868df657 |
| Last-Modified | 2016-06-08 10:43:53 -0400 (Wed, 08 Jun 2016) |
| Author | Guido van Rossum?<guido at python.org>, Barry Warsaw?<barry at python.org>, Nick Coghlan?<ncoghlan at gmail.com> |
| Status | Active |
| Type | Process |
| Content-Type | text/x-rst |
| Created | 05-Jul-2001 |
| Post-History | 05-Jul-2001, 01-Aug-2013 |
?
- Introduction 介紹
- A Foolish Consistency is the Hobgoblin of Little Minds 盡信書則不如無書
- Code lay-out 代碼布局
- Indentation 縮進(jìn)
- Tabs or Spaces 制表符還是空格
- Maximum Line Length 行的最大長度
- Should a line break before or after a binary operator 在二元運(yùn)算符之前應(yīng)該換行嗎
- Blank Lines 空行
- Source File Encoding 源文件編碼
- Imports 導(dǎo)入
- Module level dunder names 模塊級的呆名
- String Quotes 字符串引號
- Whitespace in Expressions and Statements 表達(dá)式和語句中的空格
- Pet Peeves 不能忍受的事情
- Other Recommendations 其他建議
- Comments 注釋
- Block Comments 塊注釋
- Inline Comments 行內(nèi)注釋
- Documentation Strings 文檔字符串
- Naming Conventions 命名規(guī)范
- Overriding Principle 最重要的原則
- Descriptive Naming Styles 描述命名風(fēng)格
- Prescriptive Naming Conventions 約定俗成命名約定
- Names to Avoid 應(yīng)避免的名字
- Package and Module Names 包名和模塊名
- Class Names 類名
- Exception Names 異常名
- Global Variable Names 全局變量名
- Function Names 函數(shù)名
- Function and method arguments 函數(shù)和方法參數(shù)
- Method Names and Instance Variables 方法名和實(shí)例變量
- Constants 常量
- Designing for inheritance 繼承的設(shè)計(jì)
- Public and internal interfaces 公共和內(nèi)部的接口
- Programming Recommendations 編程建議
- Function Annotations 功能注釋
- 參考
?
Introduction 介紹
本文提供的Python代碼編碼規(guī)范基于Python主要發(fā)行版本的標(biāo)準(zhǔn)庫。Python的C語言實(shí)現(xiàn)的C代碼規(guī)范請查看相應(yīng)的PEP指南1。
這篇文檔以及PEP 257（文檔字符串的規(guī)范）改編自Guido原始的《Python Style Guide》一文，同時添加了一些來自Barry的風(fēng)格指南2。
這篇規(guī)范指南隨著時間的推移而逐漸演變，隨著語言本身的變化，過去的約定也被淘汰了。
許多項(xiàng)目有自己的編碼規(guī)范，在出現(xiàn)規(guī)范沖突時，項(xiàng)目自身的規(guī)范優(yōu)先。
A Foolish Consistency is the Hobgoblin of Little Minds 盡信書,則不如無書
Guido的一條重要的見解是代碼閱讀比寫更加頻繁。這里提供的指導(dǎo)原則主要用于提升代碼的可讀性，使得在大量的Python代碼中保持一致。就像PEP 20提到的，“Readability counts”。
這是一份關(guān)于一致性的風(fēng)格指南。這份風(fēng)格指南的風(fēng)格一致性是非常重要的。更重要的是項(xiàng)目的風(fēng)格一致性。在一個模塊或函數(shù)的風(fēng)格一致性是最重要的。
然而，應(yīng)該知道什么時候應(yīng)該不一致，有時候編碼規(guī)范的建議并不適用。當(dāng)存在模棱兩可的情況時，使用自己的判斷。看看其他的示例再決定哪一種是最好的，不要羞于發(fā)問。
特別是不要為了遵守PEP約定而破壞兼容性！
幾個很好的理由去忽略特定的規(guī)則：
Code lay-out 代碼布局
Indentation 縮進(jìn)
每一級縮進(jìn)使用4個空格。
續(xù)行應(yīng)該與其包裹元素對齊，要么使用圓括號、方括號和花括號內(nèi)的隱式行連接來垂直對齊，要么使用掛行縮進(jìn)對齊3。當(dāng)使用掛行縮進(jìn)時，應(yīng)該考慮到第一行不應(yīng)該有參數(shù)，以及使用縮進(jìn)以區(qū)分自己是續(xù)行。
推薦：
# 與左括號對齊 foo = long_function_name(var_one, var_two,var_three, var_four)# 用更多的縮進(jìn)來與其他行區(qū)分 def long_function_name( var_one, var_two, var_three, var_four): print(var_one) # 掛行縮進(jìn)應(yīng)該再換一行 foo = long_function_name( var_one, var_two, var_three, var_four)- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
不推薦：
# 沒有使用垂直對齊時，禁止把參數(shù)放在第一行 foo = long_function_name(var_one, var_two,var_three, var_four)# 當(dāng)縮進(jìn)沒有與其他行區(qū)分時，要增加縮進(jìn) def long_function_name( var_one, var_two, var_three, var_four): print(var_one)- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
四空格的規(guī)則對于續(xù)行是可選的。
可選：
# 掛行縮進(jìn)不一定要用4個空格 foo = long_function_name(var_one, var_two,var_three, var_four)- 1
- 2
- 3
- 4
當(dāng)if語句的條件部分長到需要換行寫的時候，注意可以在兩個字符關(guān)鍵字的連接處（比如if），增加一個空格，再增加一個左括號來創(chuàng)造一個4空格縮進(jìn)的多行條件。這會與if語句內(nèi)同樣使用4空格縮進(jìn)的代碼產(chǎn)生視覺沖突。PEP沒有明確指明要如何區(qū)分i發(fā)的條件代碼和內(nèi)嵌代碼。可使用的選項(xiàng)包括但不限于下面幾種情況：
# 沒有額外的縮進(jìn) if (this_is_one_thing andthat_is_another_thing):do_something()# 增加一個注釋，在能提供語法高亮的編輯器中可以有一些區(qū)分 if (this_is_one_thing and that_is_another_thing): # Since both conditions are true, we can frobnicate. do_something() # 在條件判斷的語句添加額外的縮進(jìn) if (this_is_one_thing and that_is_another_thing): do_something()- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
（可以參考下面關(guān)于是否在二進(jìn)制運(yùn)算符之前或之后截?cái)嗟挠懻?#xff09;?
在多行結(jié)構(gòu)中的大括號/中括號/小括號的右括號可以與內(nèi)容對齊單獨(dú)起一行作為最后一行的第一個字符，就像這樣：
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
或者也可以與多行結(jié)構(gòu)的第一行第一個字符對齊，就像這樣：
my_list = [1, 2, 3,4, 5, 6, ] result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
Tabs or Spaces？ 制表符還是空格？
空格是首選的縮進(jìn)方式。?
制表符只能用于與同樣使用制表符縮進(jìn)的代碼保持一致。?
Python3不允許同時使用空格和制表符的縮進(jìn)。?
混合使用制表符和空格縮進(jìn)的Python2代碼應(yīng)該統(tǒng)一轉(zhuǎn)成空格。?
當(dāng)在命令行加入-t選項(xiàng)執(zhí)行Python2時，它會發(fā)出關(guān)于非法混用制表符與空格的警告。當(dāng)使用–tt時，這些警告會變成錯誤。強(qiáng)烈建議使用這樣的參數(shù)。
Maximum Line Length 行的最大長度
所有行限制的最大字符數(shù)為79。?
沒有結(jié)構(gòu)化限制的大塊文本（文檔字符或者注釋），每行的最大字符數(shù)限制在72。?
限制編輯器窗口寬度可以使多個文件并行打開，并且在使用代碼檢查工具(在相鄰列中顯示這兩個版本)時工作得很好。?
大多數(shù)工具中的默認(rèn)封裝破壞了代碼的可視化結(jié)構(gòu)，使代碼更難以理解。避免使用編輯器中默認(rèn)配置的80窗口寬度，即使工具在幫你折行時在最后一列放了一個標(biāo)記符。某些基于Web的工具可能根本不提供動態(tài)折行。?
一些團(tuán)隊(duì)更喜歡較長的行寬。如果代碼主要由一個團(tuán)隊(duì)維護(hù)，那這個問題就能達(dá)成一致，可以把行長度從80增加到100個字符（更有效的做法是將行最大長度增加到99個字符），前提是注釋和文檔字符串依然已72字符折行。?
Python標(biāo)準(zhǔn)庫比較保守，需要將行寬限制在79個字符（文檔/注釋限制在72）。?
較長的代碼行選擇Python在小括號，中括號以及大括號中的隱式續(xù)行方式。通過小括號內(nèi)表達(dá)式的換行方式將長串折成多行。這種方式應(yīng)該優(yōu)先使用，而不是使用反斜杠續(xù)行。?
反斜杠有時依然很有用。比如，比較長的，多個with狀態(tài)語句，不能使用隱式續(xù)行，所以反斜杠是可以接受的：
- 1
- 2
- 3
（請參閱前面關(guān)于多行if-語句的討論，以獲得關(guān)于這種多行with-語句縮進(jìn)的進(jìn)一步想法。）?
另一種類似情況是使用assert語句。?
確保在續(xù)行進(jìn)行適當(dāng)?shù)目s進(jìn)。
Should a line break before or after a binary operator? 在二元運(yùn)算符之前應(yīng)該換行嗎？
幾十年來，推薦的風(fēng)格是在二元運(yùn)算符之后中斷。但是這回影響可讀性，原因有二：操作符一般分布在屏幕上不同的列中，而且每個運(yùn)算符被移到了操作數(shù)的上一行。下面例子這個情況就需要額外注意，那些變量是相加的，那些變量是相減的：
# 不推薦: 操作符離操作數(shù)太遠(yuǎn) income = (gross_wages +taxable_interest +(dividends - qualified_dividends) -ira_deduction -student_loan_interest)- 1
- 2
- 3
- 4
- 5
- 6
為了解決這種可讀性的問題，數(shù)學(xué)家和他們的出版商遵循了相反的約定。Donald Knuth在他的Computers and Typesetting系列中解釋了傳統(tǒng)規(guī)則：“盡管段落中的公式總是在二元運(yùn)算符和關(guān)系之后中斷，顯示出來的公式總是要在二元運(yùn)算符之前中斷”4。?
遵循數(shù)學(xué)的傳統(tǒng)能產(chǎn)出更多可讀性高的代碼：
- 1
- 2
- 3
- 4
- 5
- 6
在Python代碼中，允許在二元運(yùn)算符之前或之后中斷，只要本地的約定是一致的。對于新代碼，建議使用Knuth的樣式。
Blank Lines 空行
頂層函數(shù)和類的定義，前后用兩個空行隔開。?
類里的方法定義用一個空行隔開。?
相關(guān)的功能組可以用額外的空行（謹(jǐn)慎使用）隔開。一堆相關(guān)的單行代碼之間的空白行可以省略（例如，一組虛擬實(shí)現(xiàn) dummy implementations）。?
在函數(shù)中使用空行來區(qū)分邏輯段（謹(jǐn)慎使用）。?
Python接受control-L（即^L）換頁符作為空格；許多工具把這些字符當(dāng)作頁面分隔符，所以你可以在文件中使用它們來分隔相關(guān)段落。請注意，一些編輯器和基于Web的代碼閱讀器可能無法識別control-L為換頁，將在其位置顯示另一個字形。
Source File Encoding 源文件編碼
Python核心發(fā)布版本中的代碼總是以UTF-8格式編碼（或者在Python2中用ASCII編碼）。?
使用ASCII（在Python2中）或UTF-8（在Python3中）編碼的文件不應(yīng)具有編碼聲明。?
在標(biāo)準(zhǔn)庫中，非默認(rèn)的編碼應(yīng)該只用于測試，或者當(dāng)一個注釋或者文檔字符串需要提及一個包含內(nèi)ASCII字符編碼的作者名字的時候；否則，使用\x,\u,\U , 或者 \N 進(jìn)行轉(zhuǎn)義來包含非ASCII字符。?
對于Python 3和更高版本，標(biāo)準(zhǔn)庫規(guī)定了以下策略（參見?PEP 3131）：Python標(biāo)準(zhǔn)庫中的所有標(biāo)識符必須使用ASCII標(biāo)識符，并在可行的情況下使用英語單詞（在許多情況下，縮寫和技術(shù)術(shù)語是非英語的）。此外，字符串文字和注釋也必須是ASCII。唯一的例外是（a）測試非ASCII特征的測試用例，以及（b）作者的名稱。作者的名字如果不使用拉丁字母拼寫，必須提供一個拉丁字母的音譯。?
鼓勵具有全球受眾的開放源碼項(xiàng)目采取類似的政策。
Imports 導(dǎo)入
- 導(dǎo)入通常在分開的行，例如：
- 1
- 2
- 3
- 4
但是可以這樣：
from subprocess import Popen, PIPE- 1
-
導(dǎo)入總是位于文件的頂部，在模塊注釋和文檔字符串之后，在模塊的全局變量與常量之前。?
導(dǎo)入應(yīng)該按照以下順序分組： - 標(biāo)準(zhǔn)庫導(dǎo)入
- 相關(guān)第三方庫導(dǎo)入
- 本地應(yīng)用/庫特定導(dǎo)入?
你應(yīng)該在每一組導(dǎo)入之間加入空行。 -
推薦使用絕對路徑導(dǎo)入，如果導(dǎo)入系統(tǒng)沒有正確的配置（比如包里的一個目錄在sys.path里的路徑后），使用絕對路徑會更加可讀并且性能更好（至少能提供更好的錯誤信息）:
- 1
- 2
- 3
然而，顯示的指定相對導(dǎo)入路徑是使用絕對路徑的一個可接受的替代方案，特別是在處理使用絕對路徑導(dǎo)入不必要冗長的復(fù)雜包布局時：
from . import sibling from .sibling import example- 1
- 2
標(biāo)準(zhǔn)庫要避免使用復(fù)雜的包引入結(jié)構(gòu)，而總是使用絕對路徑。?
不應(yīng)該使用隱式相對路徑導(dǎo)入，并且在Python 3中刪除了它。
- 當(dāng)從一個包含類的模塊中導(dǎo)入類時，常常這么寫：
- 1
- 2
如果上述的寫法導(dǎo)致名字的沖突，那么這么寫：
import myclass import foo.bar.yourclass- 1
- 2
然后使用“myclass.MyClass”和“foo.bar.yourclass.YourClass”。
- 避免通配符的導(dǎo)入（from import *），因?yàn)檫@樣做會不知道命名空間中存在哪些名字，會使得讀取接口和許多自動化工具之間產(chǎn)生混淆。對于通配符的導(dǎo)入，有一個防御性的做法，即將內(nèi)部接口重新發(fā)布為公共API的一部分（例如，用可選加速器模塊的定義覆蓋純Python實(shí)現(xiàn)的接口，以及重寫那些事先不知道的定義）。?
當(dāng)以這種方式重新發(fā)布名稱時，以下關(guān)于公共和內(nèi)部接口的準(zhǔn)則仍然適用。
Module level dunder names 模塊級的“呆”名
像__all__?,?__author__?,?__version__?等這樣的模塊級“呆名“（也就是名字里有兩個前綴下劃線和兩個后綴下劃線），應(yīng)該放在文檔字符串的后面，以及除from?__future__?之外的import表達(dá)式前面。Python要求將來在模塊中的導(dǎo)入，必須出現(xiàn)在除文檔字符串之外的其他代碼之前。?
比如：
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
String Quotes 字符串引號
在Python中，單引號和雙引號字符串是相同的。PEP不會為這個給出建議。選擇一條規(guī)則并堅(jiān)持使用下去。當(dāng)一個字符串中包含單引號或者雙引號字符的時候，使用和最外層不同的符號來避免使用反斜杠，從而提高可讀性。?
對于三引號字符串，總是使用雙引號字符來與PEP 257中的文檔字符串約定保持一致。
Whitespace in Expressions and Statements 表達(dá)式和語句中的空格
Pet Peeves 不能忍受的事情
在下列情況下，避免使用無關(guān)的空格：
- 緊跟在小括號，中括號或者大括號后。
- 1
- 2
- 緊貼在逗號、分號或者冒號之前。
- 1
- 2
- 然而，冒號在切片中就像二元運(yùn)算符，在兩邊應(yīng)該有相同數(shù)量的空格（把它當(dāng)做優(yōu)先級最低的操作符）。在擴(kuò)展的切片操作中，所有的冒號必須有相同的間距。例外情況：當(dāng)一個切片參數(shù)被省略時，空格就被省略了。?
推薦：
- 1
- 2
- 3
- 4
- 5
不推薦：
ham[lower + offset:upper + offset] ham[1: 9], ham[1 :9], ham[1:9 :3] ham[lower : : upper] ham[ : upper]- 1
- 2
- 3
- 4
- 緊貼在函數(shù)參數(shù)的左括號之前。
- 1
- 2
- 緊貼索引或者切片的左括號之前。
- 1
- 2
- 為了和另一個賦值語句對齊，在賦值運(yùn)算符附件加多個空格。?
推薦：
- 1
- 2
- 3
不推薦：
x = 1 y = 2 long_variable = 3- 1
- 2
- 3
Other Recommendations 其他建議
- 避免在尾部添加空格。因?yàn)槲膊康目崭裢ǔ６伎床灰?#xff0c;會產(chǎn)生混亂：比如，一個反斜杠后面跟一個空格的換行符，不算續(xù)行標(biāo)記。有些編輯器不會保留尾空格，并且很多項(xiàng)目（像CPython）在pre-commit的掛鉤調(diào)用中會過濾掉尾空格。
- 總是在二元運(yùn)算符兩邊加一個空格：賦值（=），增量賦值（+=，-=），比較（==,<,>,!=,<>,<=,>=,in,not,in,is,is not），布爾（and, or, not）。
- 如果使用具有不同優(yōu)先級的運(yùn)算符，請考慮在具有最低優(yōu)先級的運(yùn)算符周圍添加空格。有時需要通過自己來判斷；但是，不要使用一個以上的空格，并且在二元運(yùn)算符的兩邊使用相同數(shù)量的空格。?
推薦：
- 1
- 2
- 3
- 4
- 5
不推薦：
i=i+1 submitted +=1 x = x * 2 - 1 hypot2 = x * x + y * y c = (a + b) * (a - b)- 1
- 2
- 3
- 4
- 5
- 在制定關(guān)鍵字參數(shù)或者默認(rèn)參數(shù)值的時候，不要在=附近加上空格。?
推薦：
- 1
- 2
不推薦：
def complex(real, imag = 0.0): return magic(r = real, i = imag)- 1
- 2
- 功能型注釋應(yīng)該使用冒號的一般性規(guī)則，并且在使用->的時候要在兩邊加空格。（參考下面的功能注釋得到能夠多信息）?
推薦：
- 1
- 2
不推薦：
def munge(input:AnyStr): ... def munge()->PosInt: ...- 1
- 2
- 當(dāng)給有類型備注的參數(shù)賦值的時候，在=兩邊添加空格（僅針對那種有類型備注和默認(rèn)值的參數(shù)）。?
推薦：
- 1
- 2
不推薦：
def munge(input: AnyStr=None): ... def munge(input: AnyStr, limit = 1000): ...- 1
- 2
- 復(fù)合語句(同一行中的多個語句)通常是不允許的。?
推薦：
- 1
- 2
- 3
- 4
- 5
最好別這樣：
if foo == 'blah': do_blah_thing() do_one(); do_two(); do_three()- 1
- 2
- 雖然有時候?qū)⑿〉拇a塊和 if/for/while 放在同一行沒什么問題，多行語句塊的情況不要這樣用，同樣也要避免代碼行太長！?
最好別這樣：
- 1
- 2
- 3
絕對別這樣：
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()- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
Comments 注釋
與代碼相矛盾的注釋比沒有注釋還糟，當(dāng)代碼更改時，優(yōu)先更新對應(yīng)的注釋！?
注釋應(yīng)該是完整的句子。如果一個注釋是一個短語或句子，它的第一個單詞應(yīng)該大寫，除非它是以小寫字母開頭的標(biāo)識符(永遠(yuǎn)不要改變標(biāo)識符的大小寫！)。?
如果注釋很短，結(jié)尾的句號可以省略。塊注釋一般由完整句子的一個或多個段落組成，并且每句話結(jié)束有個句號。?
在句尾結(jié)束的時候應(yīng)該使用兩個空格。?
當(dāng)用英文書寫時，遵循Strunk and White （譯注：《Strunk and White, The Elements of Style》）的書寫風(fēng)格。?
在非英語國家的Python程序員，請使用英文寫注釋，除非你120%的確信你的代碼不會被使用其他語言的人閱讀。
Block Comments 塊注釋
塊注釋通常適用于跟隨它們的某些（或全部）代碼，并縮進(jìn)到與代碼相同的級別。塊注釋的每一行開頭使用一個#和一個空格（除非塊注釋內(nèi)部縮進(jìn)文本）。?
塊注釋內(nèi)部的段落通過只有一個#的空行分隔。
Inline Comments 行內(nèi)注釋
有節(jié)制地使用行內(nèi)注釋。?
行內(nèi)注釋是與代碼語句同行的注釋。行內(nèi)注釋和代碼至少要有兩個空格分隔。注釋由#和一個空格開始。?
事實(shí)上，如果狀態(tài)明顯的話，行內(nèi)注釋是不必要的，反而會分散注意力。比如說下面這樣就不需要：
- 1
但有時，這樣做很有用：
x = x + 1 # Compensate for border- 1
Documentation Strings 文檔字符串
編寫好的文檔說明（也叫“docstrings”）的約定在PEP 257中永恒不變。
- 要為所有的公共模塊，函數(shù)，類以及方法編寫文檔說明。非公共的方法沒有必要，但是應(yīng)該有一個描述方法具體作用的注釋。這個注釋應(yīng)該在def那一行之后。
- PEP 257?描述了寫出好的文檔說明相關(guān)的約定。特別需要注意的是，多行文檔說明使用的結(jié)尾三引號應(yīng)該自成一行，例如：
- 1
- 2
- 3
- 4
- 對于單行的文檔說明，尾部的三引號應(yīng)該和文檔在同一行。
Naming Conventions 命名規(guī)范
Python庫的命名規(guī)范很亂，從來沒能做到完全一致。但是目前有一些推薦的命名標(biāo)準(zhǔn)。新的模塊和包（包括第三方框架）應(yīng)該用這套標(biāo)準(zhǔn)，但當(dāng)一個已有庫采用了不同的風(fēng)格，推薦保持內(nèi)部一致性。
Overriding Principle 最重要的原則
那些暴露給用戶的API接口的命名，應(yīng)該遵循反映使用場景而不是實(shí)現(xiàn)的原則。
Descriptive: Naming Styles 描述：命名風(fēng)格
有許多不同的命名風(fēng)格。這里能夠幫助大家識別正在使用什么樣的命名風(fēng)格，而不考慮他們?yōu)槭裁词褂谩?
以下是常見的命名方式：
- b（單個小寫字母）
- B（單個大寫字母）
- lowercase 小寫字母
- lower_case_with_underscores 使用下劃線分隔的小寫字母
- UPPERCASE 大寫字母
- UPPER_CASE_WITH_UNDERSCORES 使用下劃線分隔的大寫字母
- CapitalizedWords（或者叫 CapWords，或者叫CamelCase 駝峰命名法 —— 這么命名是因?yàn)樽帜缚瓷先ビ衅鸱耐庥^5）。有時候也被稱為StudlyCaps。?
注意：當(dāng)在首字母大寫的風(fēng)格中用到縮寫時，所有縮寫的字母用大寫，因此，HTTPServerError 比 HttpServerError 好。 - mixedCase（不同于首字母大寫，第一個單詞的首字母小寫）
- Capitalized_Words_With_Underscores（巨丑無比！）
也有用唯一的短前綴把相關(guān)命名組織在一起的方法。這在Python中不常用，但還是提一下。比如，os.stat()函數(shù)中包含類似以st_mode，st_size，st_mtime這種傳統(tǒng)命名方式命名的變量。（這么做是為了與 POSIX 系統(tǒng)的調(diào)用一致，以幫助程序員熟悉它。）?
X11庫的所有公共函數(shù)都加了前綴X。在Python里面沒必要這么做，因?yàn)閷傩院头椒ㄔ谡{(diào)用的時候都會用類名做前綴，函數(shù)名用模塊名做前綴。?
另外，下面這種用前綴或結(jié)尾下劃線的特殊格式是被認(rèn)可的（通常和一些約定相結(jié)合）：
- _single_leading_underscore：（單下劃線開頭）弱“內(nèi)部使用”指示器。比如 from M import * 是不會導(dǎo)入以下劃線開始的對象的。
- single_trailing_underscore_：（單下劃線結(jié)尾）這是避免和Python內(nèi)部關(guān)鍵詞沖突的一種約定，比如：Tkinter.Toplevel(master, class_=’ClassName’)
- __double_leading_underscore：（雙下劃線開頭）當(dāng)這樣命名一個類的屬性時，調(diào)用它的時候名字會做矯正（在類FooBar中，__boo變成了_FooBar__boo；見下文）。
- __double_leading_and_trailing_underscore__：（雙下劃線開頭，雙下劃線結(jié)尾）“magic”對象或者存在于用戶控制的命名空間內(nèi)的屬性，例如：__init__,__import__或者_(dá)_file__。除了作為文檔之外，永遠(yuǎn)不要命這樣的名。
Prescriptive: Naming Conventions 約定俗成：命名約定
Names to Avoid 應(yīng)避免的名字
永遠(yuǎn)不要使用字母‘l’（小寫的L），‘O’（大寫的O），或者‘I’（大寫的I）作為單字符變量名。?
在有些字體里，這些字符無法和數(shù)字0和1區(qū)分，如果想用‘l’，用‘L’代替。
Package and Module Names 包名和模塊名
模塊應(yīng)該用簡短全小寫的名字，如果為了提升可讀性，下劃線也是可以用的。Python包名也應(yīng)該使用簡短全小寫的名字，但不建議用下劃線。?
當(dāng)使用C或者C++編寫了一個依賴于提供高級（更面向?qū)ο?#xff09;接口的Python模塊的擴(kuò)展模塊，這個C/C++模塊需要一個下劃線前綴（例如：_socket）
Class Names 類名
類名一般使用首字母大寫的約定。?
在接口被文檔化并且主要被用于調(diào)用的情況下，可以使用函數(shù)的命名風(fēng)格代替。?
注意，對于內(nèi)置的變量命名有一個單獨(dú)的約定：大部分內(nèi)置變量是單個單詞（或者兩個單詞連接在一起），首字母大寫的命名法只用于異常名或者內(nèi)部的常量。
Exception Names 異常名
因?yàn)楫惓Ｒ话愣际穷?#xff0c;所有類的命名方法在這里也適用。然而，你需要在異常名后面加上“Error”后綴（如果異常確實(shí)是一個錯誤）。
Global Variable Names 全局變量名
（我們希望這一類變量只在模塊內(nèi)部使用。）約定和函數(shù)命名規(guī)則一樣。?
通過 from M import * 導(dǎo)入的模塊應(yīng)該使用all機(jī)制去防止內(nèi)部的接口對外暴露，或者使用在全局變量前加下劃線的方式（表明這些全局變量是模塊內(nèi)非公有）。
Function Names 函數(shù)名
函數(shù)名應(yīng)該小寫，如果想提高可讀性可以用下劃線分隔。?
大小寫混合僅在為了兼容原來主要以大小寫混合風(fēng)格的情況下使用（比如 threading.py），保持向后兼容性。
Function and method arguments 函數(shù)和方法參數(shù)
始終要將 self 作為實(shí)例方法的的第一個參數(shù)。?
始終要將 cls 作為類靜態(tài)方法的第一個參數(shù)。?
如果函數(shù)的參數(shù)名和已有的關(guān)鍵詞沖突，在最后加單一下劃線比縮寫或隨意拼寫更好。因此 class_ 比 clss 更好。（也許最好用同義詞來避免這種沖突）
Method Names and Instance Variables 方法名和實(shí)例變量
遵循這樣的函數(shù)命名規(guī)則：使用下劃線分隔小寫單詞以提高可讀性。?
在非共有方法和實(shí)例變量前使用單下劃線。?
通過雙下劃線前綴觸發(fā)Python的命名轉(zhuǎn)換規(guī)則來避免和子類的命名沖突。?
Python通過類名對這些命名進(jìn)行轉(zhuǎn)換：如果類 Foo 有一個叫?__a?的成員變量， 它無法通過?Foo.__a訪問。（執(zhí)著的用戶可以通過?Foo._Foo__a?訪問。）一般來說，前綴雙下劃線用來避免類中的屬性命名與子類沖突的情況。?
注意：關(guān)于__names的用法存在爭論（見下文）。
Constants 常量
常量通常定義在模塊級，通過下劃線分隔的全大寫字母命名。例如： MAX_OVERFLOW 和 TOTAL。
Designing for inheritance 繼承的設(shè)計(jì)
始終要考慮到一個類的方法和實(shí)例變量（統(tǒng)稱：屬性）應(yīng)該是共有還是非共有。如果存在疑問，那就選非共有；因?yàn)閷⒁粋€非共有變量轉(zhuǎn)為共有比反過來更容易。?
公共屬性是那些與類無關(guān)的客戶使用的屬性，并承諾避免向后不兼容的更改。非共有屬性是那些不打算讓第三方使用的屬性；你不需要承諾非共有屬性不會被修改或被刪除。?
我們不使用“私有（private）”這個說法，是因?yàn)樵赑ython中目前還沒有真正的私有屬性（為了避免大量不必要的常規(guī)工作）。?
另一種屬性作為子類API的一部分（在其他語言中通常被稱為“protected”）。有些類是專為繼承設(shè)計(jì)的，用來擴(kuò)展或者修改類的一部分行為。當(dāng)設(shè)計(jì)這樣的類時，要謹(jǐn)慎決定哪些屬性時公開的，哪些是作為子類的API，哪些只能在基類中使用。?
貫徹這樣的思想，一下是一些讓代碼Pythonic的準(zhǔn)則：
- 公共屬性不應(yīng)該有前綴下劃線。
- 如果公共屬性名和關(guān)鍵字沖突，在屬性名之后增加一個下劃線。這比縮寫和隨意拼寫好很多。（然而，盡管有這樣的規(guī)則，在作為參數(shù)或者變量時，‘cls’是表示‘類’最好的選擇，特別是作為類方法的第一個參數(shù)。）?
注意1：參考之前的類方法參數(shù)命名建議 - 對于單一的共有屬性數(shù)據(jù)，最好直接對外暴露它的變量名，而不是通過負(fù)責(zé)的 存取器（accessor）/突變（mutator） 方法。請記住，如果你發(fā)現(xiàn)一個簡單的屬性需要成長為一個功能行為，那么Python為這種將來會出現(xiàn)的擴(kuò)展提供了一個簡單的途徑。在這種情況下，使用屬性去隱藏屬性數(shù)據(jù)訪問背后的邏輯。?
注意1：屬性只在new-style類中起作用。?
注意2：盡管功能方法對于類似緩存的負(fù)面影響比較小，但還是要盡量避免。?
注意3：屬性標(biāo)記會讓調(diào)用者認(rèn)為開銷（相當(dāng)?shù)?#xff09;小，避免用屬性做開銷大的計(jì)算。 - 如果你的類打算用來繼承的話，并且這個類里有不希望子類使用的屬性，就要考慮使用雙下劃線前綴并且沒有后綴下劃線的命名方式。這會調(diào)用Python的命名轉(zhuǎn)換算法，將類的名字加入到屬性名里。這樣做可以幫助避免在子類中不小心包含了相同的屬性名而產(chǎn)生的沖突。?
注意1：只有類名才會整合進(jìn)屬性名，如果子類的屬性名和類名和父類都相同，那么你還是會有命名沖突的問題。?
注意2：命名轉(zhuǎn)換會在某些場景使用起來不太方便，例如調(diào)試，__getattr__()。然而命名轉(zhuǎn)換的算法有很好的文檔說明并且很好操作。?
注意3：不是所有人都喜歡命名轉(zhuǎn)換。盡量避免意外的名字沖突和潛在的高級調(diào)用。
Public and internal interfaces 公共和內(nèi)部的接口
任何向后兼容保證只適用于公共接口，因此，用戶清晰地區(qū)分公共接口和內(nèi)部接口非常重要。?
文檔化的接口被認(rèn)為是公開的，除非文檔明確聲明它們是臨時或內(nèi)部接口，不受通常的向后兼容性保證。所有未記錄的接口都應(yīng)該是內(nèi)部的。?
為了更好地支持內(nèi)省（introspection），模塊應(yīng)該使用__all__屬性顯式地在它們的公共API中聲明名稱。將__all__設(shè)置為空列表表示模塊沒有公共API。?
即使通過__all__設(shè)置過，內(nèi)部接口（包，模塊，類，方法，屬性或其他名字）依然需要單個下劃線前綴。?
如果一個命名空間（包，模塊，類）被認(rèn)為是內(nèi)部的，那么包含它的接口也應(yīng)該被認(rèn)為是內(nèi)部的。?
導(dǎo)入的名稱應(yīng)該始終被視作是一個實(shí)現(xiàn)的細(xì)節(jié)。其他模塊必須不能間接訪問這樣的名稱，除非它是包含它的模塊中有明確的文檔說明的API，例如 os.path 或者是一個包里從子模塊公開函數(shù)接口的?__init__?模塊。
Programming Recommendations 編程建議
- 代碼應(yīng)該用不損害其他Python實(shí)現(xiàn)的方式去編寫（PyPy，Jython，IronPython，Cython，Psyco 等）。?
比如，不要依賴于在CPython中高效的內(nèi)置字符連接語句 a += b 或者 a = a + b。這種優(yōu)化甚至在CPython中都是脆弱的（它只適用于某些類型）并且沒有出現(xiàn)在不使用引用計(jì)數(shù)的實(shí)現(xiàn)中。在性能要求比較高的庫中，可以種 ”.join() 代替。這可以確保字符關(guān)聯(lián)在不同的實(shí)現(xiàn)中都可以以線性時間發(fā)生。 - 和像None這樣的單例對象進(jìn)行比較的時候應(yīng)該始終用 is 或者 is not，永遠(yuǎn)不要用等號運(yùn)算符。?
另外，如果你在寫 if x 的時候，請注意你是否表達(dá)的意思是 if x is not None。舉個例子，當(dāng)測試一個默認(rèn)值為None的變量或者參數(shù)是否被設(shè)置為其他值的時候。這個其他值應(yīng)該是在上下文中能成為bool類型false的值。 - 使用 is not 運(yùn)算符，而不是 not … is 。雖然這兩種表達(dá)式在功能上完全相同，但前者更易于閱讀，所以優(yōu)先考慮。?
推薦：
- 1
不推薦：
if not foo is None:- 1
- 當(dāng)使用富比較（rich comparisons，一種復(fù)雜的對象間比較的新機(jī)制，允許返回值不為-1,0,1）實(shí)現(xiàn)排序操作的時候，最好實(shí)現(xiàn)全部的六個操作符（__eq__,?__ne__,?__lt__,?__gt__,?__ge__）而不是依靠其他的代碼去實(shí)現(xiàn)特定的比較。?
為了最大程度減少這一過程的開銷， functools.total_ordering() 修飾符提供了用于生成缺少的比較方法的工具。?
PEP 207?指出Python實(shí)現(xiàn)了反射機(jī)制。因此，解析器會將 y > x 轉(zhuǎn)變?yōu)?x < y，將 y >= x 轉(zhuǎn)變?yōu)?x <= y，也會轉(zhuǎn)換x == y 和 x != y的參數(shù)。sort() 和 min()方法確保使用<操作符，max()使用>操作符。然而，最好還是實(shí)現(xiàn)全部六個操作符，以免在其他地方出現(xiàn)沖突。 - 始終使用def表達(dá)式，而不是通過賦值語句將lambda表達(dá)式綁定到一個變量上。?
推薦：
- 1
不推薦：
f = lambda x: 2*x- 1
第一個形式意味著生成的函數(shù)對象的名稱是“f”而不是泛型“< lambda >”。這在回溯和字符串顯示的時候更有用。賦值語句的使用消除了lambda表達(dá)式優(yōu)于顯式def表達(dá)式的唯一優(yōu)勢（即lambda表達(dá)式可以內(nèi)嵌到更大的表達(dá)式中）。
-
從Exception繼承異常，而不是BaseException。直接繼承BaseException的異常適用于幾乎不用來捕捉的異常。?
設(shè)計(jì)異常的等級，要基于撲捉異常代碼的需要，而不是異常拋出的位置。以編程的方式去回答“出了什么問題？”，而不是只是確認(rèn)“出現(xiàn)了問題”（內(nèi)置異常結(jié)構(gòu)的例子參考?PEP 3151?）?
類的命名規(guī)范適用于這里，但是你需要添加一個“Error”的后綴到你的異常類，如果異常是一個Error的話。非本地流控制或者其他形式的信號的非錯誤異常不需要特殊的后綴。 -
適當(dāng)?shù)厥褂卯惓ｆ溄印Ｔ赑ython 3里，為了不丟失原始的根源，可以顯式指定“raise X from Y”作為替代。?
當(dāng)故意替換一個內(nèi)部異常時（Python 2 使用“raise X”， Python 3.3 之后 使用 “raise X from None”），確保相關(guān)的細(xì)節(jié)轉(zhuǎn)移到新的異常中（比如把AttributeError轉(zhuǎn)為KeyError的時候保留屬性名，或者將原始異常信息的文本內(nèi)容內(nèi)嵌到新的異常中）。 -
在Python 2中拋出異常時，使用 rasie ValueError(‘message’) 而不是用老的形式 raise ValueError, ‘message’。?
第二種形式在Python3 的語法中不合法?
使用小括號，意味著當(dāng)異常里的參數(shù)非常長，或者包含字符串格式化的時候，不需要使用換行符。 -
當(dāng)捕獲到異常時，如果可以的話寫上具體的異常名，而不是只用一個except: 塊。?
比如說：
- 1
- 2
- 3
- 4
如果只有一個except: 塊將會捕獲到SystemExit和KeyboardInterrupt異常，這樣會很難通過Control-C中斷程序，而且會掩蓋掉其他問題。如果你想捕獲所有指示程序出錯的異常，使用 except Exception: （只有except等價(jià)于 except BaseException:）。?
兩種情況不應(yīng)該只使用‘excpet’塊：
如果代碼需要做清理工作，使用 raise..try…finally 能很好處理這種情況并且能讓異常繼續(xù)上浮。
- 當(dāng)給捕捉的異常綁定一個名字時，推薦使用在Python 2.6中加入的顯式命名綁定語法：
- 1
- 2
- 3
- 4
為了避免和原來基于逗號分隔的語法出現(xiàn)歧義，Python3只支持這一種語法。
-
當(dāng)捕捉操作系統(tǒng)的錯誤時，推薦使用Python 3.3 中errno內(nèi)定數(shù)值指定的異常等級。
-
另外，對于所有的 try/except 語句塊，在try語句中只填充必要的代碼，這樣能避免掩蓋掉bug。?
推薦：
- 1
- 2
- 3
- 4
- 5
- 6
不推薦：
try:# Too broad!return handle_value(collection[key]) except KeyError:# Will also catch KeyError raised by handle_value() return key_not_found(key)- 1
- 2
- 3
- 4
- 5
- 6
- 當(dāng)代碼片段局部使用了某個資源的時候，使用with 表達(dá)式來確保這個資源使用完后被清理干凈。用try/finally也可以。
- 無論何時獲取和釋放資源，都應(yīng)該通過單獨(dú)的函數(shù)或方法調(diào)用上下文管理器。舉個例子：?
推薦：
- 1
- 2
不推薦：
with conn:do_stuff_in_transaction(conn)- 1
- 2
第二個例子沒有提供任何信息去指明__enter__和__exit__方法在事務(wù)之后做出了關(guān)閉連接之外的其他事情。這種情況下，明確指明非常重要。
- 返回的語句保持一致。函數(shù)中的返回語句都應(yīng)該返回一個表達(dá)式，或者都不返回。如果一個返回語句需要返回一個表達(dá)式，那么在沒有值可以返回的情況下，需要用 return None 顯式指明，并且在函數(shù)的最后顯式指定一條返回語句（如果能跑到那的話）。?
推薦：
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
不推薦：
def foo(x):if x >= 0: return math.sqrt(x) def bar(x): if x < 0: return return math.sqrt(x)- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 使用字符串方法代替字符串模塊。?
字符串方法總是更快，并且和unicode字符串分享相同的API。如果需要兼容Python2.0之前的版本可以不用考慮這個規(guī)則。 - 使用 ”.startswith() 和 ”.endswith() 代替通過字符串切割的方法去檢查前綴和后綴。?
startswith()和endswith()更干凈，出錯幾率更小。比如：
- 1
- 2
- 對象類型的比較應(yīng)該用isinstance()而不是直接比較type。
- 1
- 2
- 3
當(dāng)檢查一個對象是否為string類型時，記住，它也有可能是unicode string！在Python2中，str和unicode都有相同的基類：basestring，所以你可以這樣：
if isinstance(obj, basestring):- 1
注意，在Python3中，unicode和basestring都不存在了（只有str）并且bytes類型的對象不再是string類型的一種（它是整數(shù)序列）
- 對于序列來說（strings，lists，tuples），可以使用空序列為false的情況。
- 1
- 2
- 3
- 4
- 5
- 書寫字符串時不要依賴單詞結(jié)尾的空格，這樣的空格在視覺上難以區(qū)分，有些編輯器會自動去掉他們（比如 reindent.py （譯注：re indent 重新縮進(jìn)））
- 不要用 == 去和True或者False比較：
- 1
- 2
- 3
Function Annotations 功能注釋
隨著PEP 484的引入，功能型注釋的風(fēng)格規(guī)范有些變化。
- 為了向前兼容，在Python3代碼中的功能注釋應(yīng)該使用 PEP 484的語法規(guī)則。（在前面的章節(jié)中對注釋有格式化的建議。）
- 不再鼓勵使用之前在PEP中推薦的實(shí)驗(yàn)性樣式。
- 然而，在stdlib庫之外，在PEP 484中的實(shí)驗(yàn)性規(guī)則是被鼓勵的。比如用PEP 484的樣式標(biāo)記大型的第三方庫或者應(yīng)用程序，回顧添加這些注釋是否簡單，并觀察是否增加了代碼的可讀性。
- Python的標(biāo)準(zhǔn)庫代碼應(yīng)該保守使用這種注釋，但新的代碼或者大型的重構(gòu)可以使用這種注釋。
- 如果代碼希望對功能注釋有不同的用途，建議在文件的頂部增加一個這種形式的注釋：
- 1
這會告訴檢查器忽略所有的注釋。（在?PEP 484中可以找到從類型檢查器禁用投訴的更細(xì)粒度的方法。）
-
像linters一樣，類型檢測器是可選的可獨(dú)立的工具。默認(rèn)情況下，Python解釋器不應(yīng)該因?yàn)轭愋蜋z查而發(fā)出任何消息，也不應(yīng)該基于注釋改變它們的行為。
-
不想使用類型檢測的用戶可以忽略他們。然而，第三方庫的用戶可能希望在這些庫上運(yùn)行類型檢測。為此，?PEP 484?建議使用存根文件類型：.pyi文件，這種文件類型相比于.py文件會被類型檢測器讀取。存根文件可以和庫一起，或者通過typeshed repo6獨(dú)立發(fā)布（通過庫作者的許可）
-
對于需要向后兼容的代碼，可以以注釋的形式添加功能型注釋。參見PEP 484的相關(guān)部分7。
參考
轉(zhuǎn)載于:https://www.cnblogs.com/think90/p/9559001.html
總結(jié)
以上是生活随笔為你收集整理的Python PEP8 编码规范中文版的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 四则运算系统：分析和设计
- 下一篇： python3 判断大小端的一种方法