PEP8 規範

時間  2019-12-11
標籤 pep8 pep 規範 简体版
原文   原文鏈接

 

Python PEP8 編碼規範中文版

 

原文連接：http://legacy.python.org/dev/peps/pep-0008/css

item detail
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 介紹

本文提供的Python代碼編碼規範基於Python主要發行版本的標準庫。Python的C語言實現的C代碼規範請查看相應的PEP指南1。java

這篇文檔以及PEP 257（文檔字符串的規範）改編自Guido原始的《Python Style Guide》一文，同時添加了一些來自Barry的風格指南2。python

這篇規範指南隨着時間的推移而逐漸演變，隨着語言自己的變化，過去的約定也被淘汰了。git

許多項目有本身的編碼規範，在出現規範衝突時，項目自身的規範優先。程序員

A Foolish Consistency is the Hobgoblin of Little Minds 盡信書,則不如無書

Guido的一條重要的看法是代碼閱讀比寫更加頻繁。這裏提供的指導原則主要用於提高代碼的可讀性，使得在大量的Python代碼中保持一致。就像PEP 20提到的，「Readability counts」。github

這是一份關於一致性的風格指南。這份風格指南的風格一致性是很是重要的。更重要的是項目的風格一致性。在一個模塊或函數的風格一致性是最重要的。算法

然而，應該知道何時應該不一致，有時候編碼規範的建議並不適用。當存在模棱兩可的狀況時，使用本身的判斷。看看其餘的示例再決定哪種是最好的，不要羞於發問。express

特別是不要爲了遵照PEP約定而破壞兼容性！編程

幾個很好的理由去忽略特定的規則：api

  1. 當遵循這份指南以後代碼的可讀性變差，甚至是遵循PEP規範的人也以爲可讀性差。
  2. 與周圍的代碼保持一致（也可能出於歷史緣由），儘管這也是清理他人混亂（真正的Xtreme Programming風格）的一個機會。
  3. 有問題的代碼出如今發現編碼規範以前，並且也沒有充足的理由去修改他們。
  4. 當代碼須要兼容不支持編碼規範建議的老版本Python。

Code lay-out 代碼佈局

Indentation 縮進

每一級縮進使用4個空格。

續行應該與其包裹元素對齊，要麼使用圓括號、方括號和花括號內的隱式行鏈接來垂直對齊，要麼使用掛行縮進對齊3。當使用掛行縮進時，應該考慮到第一行不該該有參數，以及使用縮進以區分本身是續行。

推薦：

# 與左括號對齊
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)

不推薦：

# 沒有使用垂直對齊時，禁止把參數放在第一行
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)

四空格的規則對於續行是可選的。

可選：

# 掛行縮進不必定要用4個空格
foo = long_function_name(
  var_one, var_two,
  var_three, var_four)

當if語句的條件部分長到須要換行寫的時候，注意能夠在兩個字符關鍵字的鏈接處（好比if），增長一個空格，再增長一個左括號來創造一個4空格縮進的多行條件。這會與if語句內一樣使用4空格縮進的代碼產生視覺衝突。PEP沒有明確指明要如何區分i發的條件代碼和內嵌代碼。可以使用的選項包括但不限於下面幾種狀況：

# 沒有額外的縮進
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()

# 在條件判斷的語句添加額外的縮進
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

（能夠參考下面關因而否在二進制運算符以前或以後截斷的討論）
在多行結構中的大括號/中括號/小括號的右括號能夠與內容對齊單獨起一行做爲最後一行的第一個字符，就像這樣：

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',
)

Tabs or Spaces？ 製表符仍是空格？

空格是首選的縮進方式。
製表符只能用於與一樣使用製表符縮進的代碼保持一致。
Python3不容許同時使用空格和製表符的縮進。
混合使用製表符和空格縮進的Python2代碼應該統一轉成空格。
當在命令行加入-t選項執行Python2時，它會發出關於非法混用製表符與空格的警告。當使用–tt時，這些警告會變成錯誤。強烈建議使用這樣的參數。

Maximum Line Length 行的最大長度

全部行限制的最大字符數爲79。
沒有結構化限制的大塊文本（文檔字符或者註釋），每行的最大字符數限制在72。
限制編輯器窗口寬度可使多個文件並行打開，而且在使用代碼檢查工具(在相鄰列中顯示這兩個版本)時工做得很好。
大多數工具中的默認封裝破壞了代碼的可視化結構，使代碼更難以理解。避免使用編輯器中默認配置的80窗口寬度，即便工具在幫你折行時在最後一列放了一個標記符。某些基於Web的工具可能根本不提供動態折行。
一些團隊更喜歡較長的行寬。若是代碼主要由一個團隊維護，那這個問題就能達成一致，能夠把行長度從80增長到100個字符（更有效的作法是將行最大長度增長到99個字符），前提是註釋和文檔字符串依然已72字符折行。
Python標準庫比較保守，須要將行寬限制在79個字符（文檔/註釋限制在72）。
較長的代碼行選擇Python在小括號，中括號以及大括號中的隱式續行方式。經過小括號內表達式的換行方式將長串折成多行。這種方式應該優先使用，而不是使用反斜槓續行。
反斜槓有時依然頗有用。好比，比較長的，多個with狀態語句，不能使用隱式續行，因此反斜槓是能夠接受的：

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())

（請參閱前面關於多行if-語句的討論，以得到關於這種多行with-語句縮進的進一步想法。）
另外一種相似狀況是使用assert語句。
確保在續行進行適當的縮進。

Should a line break before or after a binary operator? 在二元運算符以前應該換行嗎？

幾十年來，推薦的風格是在二元運算符以後中斷。可是這回影響可讀性，緣由有二：操做符通常分佈在屏幕上不一樣的列中，並且每一個運算符被移到了操做數的上一行。下面例子這個狀況就須要額外注意，那些變量是相加的，那些變量是相減的：

# 不推薦: 操做符離操做數太遠
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

爲了解決這種可讀性的問題，數學家和他們的出版商遵循了相反的約定。Donald Knuth在他的Computers and Typesetting系列中解釋了傳統規則：「儘管段落中的公式老是在二元運算符和關係以後中斷，顯示出來的公式老是要在二元運算符以前中斷」4。
遵循數學的傳統能產出更多可讀性高的代碼：

# 推薦：運算符和操做數很容易進行匹配
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction           - student_loan_interest)

在Python代碼中，容許在二元運算符以前或以後中斷，只要本地的約定是一致的。對於新代碼，建議使用Knuth的樣式。

Blank Lines 空行

頂層函數和類的定義，先後用兩個空行隔開。
類裏的方法定義用一個空行隔開。
相關的功能組能夠用額外的空行（謹慎使用）隔開。一堆相關的單行代碼之間的空白行能夠省略（例如，一組虛擬實現 dummy implementations）。
在函數中使用空行來區分邏輯段（謹慎使用）。
Python接受control-L（即^L）換頁符做爲空格；許多工具把這些字符看成頁面分隔符，因此你能夠在文件中使用它們來分隔相關段落。請注意，一些編輯器和基於Web的代碼閱讀器可能沒法識別control-L爲換頁，將在其位置顯示另外一個字形。

Source File Encoding 源文件編碼

Python核心發佈版本中的代碼老是以UTF-8格式編碼（或者在Python2中用ASCII編碼）。
使用ASCII（在Python2中）或UTF-8（在Python3中）編碼的文件不該具備編碼聲明。
在標準庫中，非默認的編碼應該只用於測試，或者當一個註釋或者文檔字符串須要說起一個包含內ASCII字符編碼的做者名字的時候；不然，使用\x,\u,\U , 或者 \N 進行轉義來包含非ASCII字符。
對於Python 3和更高版本，標準庫規定了如下策略（參見 PEP 3131）：Python標準庫中的全部標識符必須使用ASCII標識符，並在可行的狀況下使用英語單詞（在許多狀況下，縮寫和技術術語是非英語的）。此外，字符串文字和註釋也必須是ASCII。惟一的例外是（a）測試非ASCII特徵的測試用例，以及（b）做者的名稱。做者的名字若是不使用拉丁字母拼寫，必須提供一個拉丁字母的音譯。
鼓勵具備全球受衆的開放源碼項目採起相似的政策。

Imports 導入

  • 導入一般在分開的行，例如：
推薦: import os
     import sys

不推薦:  import sys, os

可是能夠這樣：

from subprocess import Popen, PIPE

  • 導入老是位於文件的頂部，在模塊註釋和文檔字符串以後，在模塊的全局變量與常量以前。
    導入應該按照如下順序分組：

    1. 標準庫導入
    2. 相關第三方庫導入
    3. 本地應用/庫特定導入
      你應該在每一組導入之間加入空行。

  • 推薦使用絕對路徑導入，若是導入系統沒有正確的配置（好比包裏的一個目錄在sys.path裏的路徑後），使用絕對路徑會更加可讀而且性能更好（至少能提供更好的錯誤信息）:

import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example

然而，顯示的指定相對導入路徑是使用絕對路徑的一個可接受的替代方案，特別是在處理使用絕對路徑導入沒必要要冗長的複雜包佈局時：

from . import sibling
from .sibling import example

標準庫要避免使用複雜的包引入結構，而老是使用絕對路徑。
不該該使用隱式相對路徑導入，而且在Python 3中刪除了它。

  • 當從一個包含類的模塊中導入類時，經常這麼寫：
from myclass import MyClass
from foo.bar.yourclass import YourClass

若是上述的寫法致使名字的衝突，那麼這麼寫：

import myclass
import foo.bar.yourclass

而後使用「myclass.MyClass」和「foo.bar.yourclass.YourClass」。

  • 避免通配符的導入（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 } )
  • 緊貼在逗號、分號或者冒號以前。
Yes: if x == 4: print x, y; x, y = y, x
No:  if x == 4 : print x , y ; x , y = y , x
  • 然而，冒號在切片中就像二元運算符，在兩邊應該有相同數量的空格（把它當作優先級最低的操做符）。在擴展的切片操做中，全部的冒號必須有相同的間距。例外狀況：當一個切片參數被省略時，空格就被省略了。
    推薦：
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]
  • 緊貼在函數參數的左括號以前。
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): ...

不推薦：

def munge(input: AnyStr=None): ...
def munge(input: AnyStr, limit = 1000): ...
  • 複合語句(同一行中的多個語句)一般是不容許的。
    推薦：
if foo == 'blah':
    do_blah_thing()
do_one()
do_two()
do_three()

最好別這樣：

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 += 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. """
  • 對於單行的文檔說明，尾部的三引號應該和文檔在同一行。

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:
  • 當使用富比較（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 能很好處理這種狀況而且能讓異常繼續上浮。

    • 當給捕捉的異常綁定一個名字時，推薦使用在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)
  • 當代碼片斷局部使用了某個資源的時候，使用with 表達式來確保這個資源使用完後被清理乾淨。用try/finally也能夠。
  • 不管什麼時候獲取和釋放資源，都應該經過單獨的函數或方法調用上下文管理器。舉個例子：
    推薦：
with conn.begin_transaction():
    do_stuff_in_transaction(conn)

不推薦：

with conn:
    do_stuff_in_transaction(conn)

第二個例子沒有提供任何信息去指明__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()更乾淨，出錯概率更小。好比：
推薦: if foo.startswith('bar'):
糟糕: if foo[:3] == 'bar':
  • 對象類型的比較應該用isinstance()而不是直接比較type。
正確: if isinstance(obj, int):

糟糕: if type(obj) is type(1):

當檢查一個對象是否爲string類型時，記住，它也有多是unicode string！在Python2中，str和unicode都有相同的基類：basestring，因此你能夠這樣：

if isinstance(obj, basestring):

注意，在Python3中，unicode和basestring都不存在了（只有str）而且bytes類型的對象再也不是string類型的一種（它是整數序列）

  • 對於序列來講（strings，lists，tuples），可使用空序列爲false的狀況。
正確: if not seq:
      if seq:

糟糕: if len(seq):
      if not len(seq):
  • 書寫字符串時不要依賴單詞結尾的空格，這樣的空格在視覺上難以區分，有些編輯器會自動去掉他們（好比 reindent.py （譯註：re indent 從新縮進））
  • 不要用 == 去和True或者False比較：
正確: if greeting:
糟糕: if greeting == True:
更糟: if greeting is True:

Function Annotations 功能註釋

隨着PEP 484的引入，功能型註釋的風格規範有些變化。

  • 爲了向前兼容，在Python3代碼中的功能註釋應該使用 PEP 484的語法規則。（在前面的章節中對註釋有格式化的建議。）
  • 再也不鼓勵使用以前在PEP中推薦的實驗性樣式。
  • 然而，在stdlib庫以外，在PEP 484中的實驗性規則是被鼓勵的。好比用PEP 484的樣式標記大型的第三方庫或者應用程序，回顧添加這些註釋是否簡單，並觀察是否增長了代碼的可讀性。
  • Python的標準庫代碼應該保守使用這種註釋，但新的代碼或者大型的重構可使用這種註釋。
  • 若是代碼但願對功能註釋有不一樣的用途，建議在文件的頂部增長一個這種形式的註釋：
# type: ignore

這會告訴檢查器忽略全部的註釋。（在 PEP 484中能夠找到從類型檢查器禁用投訴的更細粒度的方法。）

  • 像linters同樣，類型檢測器是可選的可獨立的工具。默認狀況下，Python解釋器不該該由於類型檢查而發出任何消息，也不該該基於註釋改變它們的行爲。

  • 不想使用類型檢測的用戶能夠忽略他們。然而，第三方庫的用戶可能但願在這些庫上運行類型檢測。爲此， PEP 484 建議使用存根文件類型：.pyi文件，這種文件類型相比於.py文件會被類型檢測器讀取。存根文件能夠和庫一塊兒，或者經過typeshed repo6獨立發佈（經過庫做者的許可）

  • 對於須要向後兼容的代碼，能夠以註釋的形式添加功能型註釋。參見PEP 484的相關部分7。

參考

  1. PEP 7, Style Guide for C Code, van Rossum ↩
  2. Barry’s GNU Mailman style guide http://barry.warsaw.us/software/STYLEGUIDE.txt ↩
  3. 掛行縮進是一種類型設置樣式，其中除第一行以外，段落中的全部行都縮進。在Python中，這個術語是用來描述一種風格：在被括號括起來的語句中，左括號是這一行最後一個非空格字符，隨後括號內的內容每一行進行縮進，直到遇到右括號。 ↩
  4. Donald Knuth’s The TeXBook, pages 195 and 196 ↩
  5. http://www.wikipedia.com/wiki/CamelCase ↩
  6. Typeshed repo https://github.com/python/typeshed ↩
  7. Suggested syntax for Python 2.7 and straddling code https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code ↩
相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程