Python PEP8 編碼規范中文版

 

英文原文：PEP 8 -- Style Guide for Python Code

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

 

1. Introduction 介紹

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

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

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

許多項目有自己的編碼規范，在出現規范沖突時，項目自身的規范優先。

 

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

Guido的一條重要的見解是代碼閱讀比寫更加頻繁。這里提供的指導原則主要用於提升代碼的可讀性，使得在大量的Python代碼中保持一致。就像PEP 20提到的，“Readability counts”。

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

然而，應該知道什么時候應該不一致，有時候編碼規范的建議並不適用。當存在模棱兩可的情況時，使用自己的判斷。看看其他的示例再決定哪一種是最好的，不要羞於發問。

特別是不要為了遵守PEP約定而破壞兼容性！

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

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

 

3. Code lay-out 代碼布局

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

 

3.2 Tabs or Spaces？ 制表符還是空格？

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

 

3.3 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語句。
確保在續行進行適當的縮進。

 

3.4 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的樣式。

 

3.5 Blank Lines 空行

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

 

3.6 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）作者的名稱。作者的名字如果不使用拉丁字母拼寫，必須提供一個拉丁字母的音譯。
鼓勵具有全球受眾的開放源碼項目采取類似的政策。

 

3.7 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實現的接口，以及重寫那些事先不知道的定義）。

當以這種方式重新發布名稱時，以下關於公共和內部接口的准則仍然適用。

 

3.8 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

 

4. String Quotes 字符串引號

在Python中，單引號和雙引號字符串是相同的。PEP不會為這個給出建議。選擇一條規則並堅持使用下去。當一個字符串中包含單引號或者雙引號字符的時候，使用和最外層不同的符號來避免使用反斜杠，從而提高可讀性。 

對於三引號字符串，總是使用雙引號字符來與PEP 257中的文檔字符串約定保持一致。

 

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

5.1 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

 

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

 

6. Comments 注釋

與代碼相矛盾的注釋比沒有注釋還糟，當代碼更改時，優先更新對應的注釋！ 

注釋應該是完整的句子。如果一個注釋是一個短語或句子，它的第一個單詞應該大寫，除非它是以小寫字母開頭的標識符(永遠不要改變標識符的大小寫！)。
如果注釋很短，結尾的句號可以省略。塊注釋一般由完整句子的一個或多個段落組成，並且每句話結束有個句號。
在句尾結束的時候應該使用兩個空格。
當用英文書寫時，遵循Strunk and White （譯注：《Strunk and White, The Elements of Style》）的書寫風格。
在非英語國家的Python程序員，請使用英文寫注釋，除非你120%的確信你的代碼不會被使用其他語言的人閱讀。

6.1 Block Comments 塊注釋

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

6.2 Inline Comments 行內注釋

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

x = x + 1                 # Increment x

但有時，這樣做很有用：

x = x + 1                 # Compensate for border

6.3 Documentation Strings 文檔字符串

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

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

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""

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

7. Naming Conventions 命名規范

Python庫的命名規范很亂，從來沒能做到完全一致。但是目前有一些推薦的命名標准。新的模塊和包（包括第三方框架）應該用這套標准，但當一個已有庫采用了不同的風格，推薦保持內部一致性。

7.1 Overriding Principle 最重要的原則

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

7.2 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__。除了作為文檔之外，永遠不要命這樣的名。

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

7.3.1 Names to Avoid 應避免的名字

永遠不要使用字母‘l’（小寫的L），‘O’（大寫的O），或者‘I’（大寫的I）作為單字符變量名。
在有些字體里，這些字符無法和數字0和1區分，如果想用‘l’，用‘L’代替。

7.3.2 Package and Module Names 包名和模塊名

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

7.3.3 Class Names 類名

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

7.3.4 Exception Names 異常名

因為異常一般都是類，所有類的命名方法在這里也適用。然而，你需要在異常名后面加上“Error”后綴（如果異常確實是一個錯誤）。

7.3.5 Global Variable Names 全局變量名

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

7.3.6 Function Names 函數名

函數名應該小寫，如果想提高可讀性可以用下划線分隔。
大小寫混合僅在為了兼容原來主要以大小寫混合風格的情況下使用（比如 threading.py），保持向后兼容性。

7.3.7 Function and method arguments 函數和方法參數

始終要將 self 作為實例方法的的第一個參數。
始終要將 cls 作為類靜態方法的第一個參數。 如果函數的參數名和已有的關鍵詞沖突，在最后加單一下划線比縮寫或隨意拼寫更好。因此 class_ 比 clss 更好。（也許最好用同義詞來避免這種沖突）

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

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

7.3.9 Constants 常量

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

7.3.10 Designing for inheritance 繼承的設計

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

• 公共屬性不應該有前綴下划線。
• 如果公共屬性名和關鍵字沖突，在屬性名之后增加一個下划線。這比縮寫和隨意拼寫好很多。（然而，盡管有這樣的規則，在作為參數或者變量時，‘cls’是表示‘類’最好的選擇，特別是作為類方法的第一個參數。）

　　　注意1：參考之前的類方法參數命名建議

• 對於單一的共有屬性數據，最好直接對外暴露它的變量名，而不是通過負責的 存取器（accessor）/突變（mutator） 方法。請記住，如果你發現一個簡單的屬性需要成長為一個功能行為，那么Python為這種將來會出現的擴展提供了一個簡單的途徑。在這種情況下，使用屬性去隱藏屬性數據訪問背后的邏輯。

　　　注意1：屬性只在new-style類中起作用。
　　　注意2：盡管功能方法對於類似緩存的負面影響比較小，但還是要盡量避免。
　　　注意3：屬性標記會讓調用者認為開銷（相當的）小，避免用屬性做開銷大的計算。

• 如果你的類打算用來繼承的話，並且這個類里有不希望子類使用的屬性，就要考慮使用雙下划線前綴並且沒有后綴下划線的命名方式。這會調用Python的命名轉換算法，將類的名字加入到屬性名里。這樣做可以幫助避免在子類中不小心包含了相同的屬性名而產生的沖突。

　　　注意1：只有類名才會整合進屬性名，如果子類的屬性名和類名和父類都相同，那么你還是會有命名沖突的問題。
　　　注意2：命名轉換會在某些場景使用起來不太方便，例如調試，__getattr__()。然而命名轉換的算法有很好的文檔說明並且很好操作。
　　　注意3：不是所有人都喜歡命名轉換。盡量避免意外的名字沖突和潛在的高級調用。

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

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

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

 

8.1 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。

 

9. 參考

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 ↩

 

參考：https://blog.csdn.net/ratsniper/article/details/78954852