背景

Python 是 Google主要的指令碼語言。這本風格指南主要包含的是針對python的程式設計準則。

為幫助讀者能夠將程式碼準確格式化，我們提供了針對 Vim的配置檔案 。對於Emacs使用者，保持預設設定即可。

Python語言規範

Lint

對你的程式碼執行pylint

定義:pylint是一個在Python原始碼中查詢bug的工具. 對於C和C++這樣的不那麼動態的(譯者注: 原文是less dynamic)語言, 這些bug通常由編譯器來捕獲. 由於Python的動態特性, 有些警告可能不對. 不過偽告警應該很少.優點:可以捕獲容易忽視的錯誤, 例如輸入錯誤, 使用未賦值的變數等.缺點:pylint不完美. 要利用其優勢, 我們有時侯需要: a) 圍繞著它來寫程式碼 b) 抑制其告警 c) 改進它, 或者d) 忽略它.結論:確保對你的程式碼執行pylint.抑制不準確的警告,以便能夠將其他警告暴露出來。你可以通過設定一個行註釋來抑制告警. 例如:

dict = 'something awful'  # Bad Idea... pylint: disable=redefined-builtin

pylint警告是以一個數字編號(如 C0112 )和一個符號名(如 empty-docstring )來標識的. 在編寫新程式碼或更新已有程式碼時對告警進行醫治, 推薦使用符號名來標識.

如果警告的符號名不夠見名知意，那麼請對其增加一個詳細解釋。

採用這種抑制方式的好處是我們可以輕鬆查詢抑制並回顧它們.

你可以使用命令 pylint --list-msgs 來獲取pylint告警列表. 你可以使用命令 pylint --help-msg=C6409 , 以獲取關於特定訊息的更多資訊.

相比較於之前使用的 pylint: disable-msg , 本文推薦使用 pylint: disable .

要抑制”引數未使用”告警, 你可以用”_”作為引數識別符號, 或者在引數名前加”unused_”. 遇到不能改變引數名的情況, 你可以通過在函式開頭”提到”它們來消除告警. 例如:

def foo(a, unused_b, unused_c, d=None, e=None):
    _ = d, e
    return a

匯入

僅對包和模組使用匯入

定義:模組間共享程式碼的重用機制.優點:名稱空間管理約定十分簡單. 每個識別符號的源都用一種一致的方式指示. x.Obj表示Obj物件定義在模組x中.缺點:模組名仍可能衝突. 有些模組名太長, 不太方便.結論:使用 import x 來匯入包和模組.使用 from x import y , 其中x是包字首, y是不帶字首的模組名.使用 from x import y as z, 如果兩個要匯入的模組都叫做y或者y太長了.例如, 模組 sound.effects.echo 可以用如下方式匯入:

from sound.effects import echo
...
echo.EchoFilter(input, output, delay=0.7, atten=4)

匯入時不要使用相對名稱. 即使模組在同一個包中, 也要使用完整包名. 這能幫助你避免無意間匯入一個包兩次.

包

使用模組的全路徑名來匯入每個模組

優點:避免模組名衝突. 查詢包更容易.缺點:部署程式碼變難, 因為你必須複製包層次.結論:所有的新程式碼都應該用完整包名來匯入每個模組.應該像下面這樣匯入:

# Reference in code with complete name.
import sound.effects.echo

# Reference in code with just module name (preferred).
from sound.effects import echo

異常

允許使用異常, 但必須小心

定義:異常是一種跳出程式碼塊的正常控制流來處理錯誤或者其它異常條件的方式.優點:正常操作程式碼的控制流不會和錯誤處理程式碼混在一起. 當某種條件發生時, 它也允許控制流跳過多個框架. 例如, 一步跳出N個巢狀的函式, 而不必繼續執行錯誤的程式碼.缺點:可能會導致讓人困惑的控制流. 呼叫庫時容易錯過錯誤情況.結論:異常必須遵守特定條件:

1. 像這樣觸發異常: raise MyException("Error message") 或者 raise MyException . 不要使用兩個引數的形式( raise MyException, "Error message" )或者過時的字串異常( raise "Error message" ).
2. 模組或包應該定義自己的特定域的異常基類, 這個基類應該從內建的Exception類繼承. 模組的異常基類應該叫做”Error”.

   class Error(Exception):
       pass

3. 永遠不要使用 except: 語句來捕獲所有異常, 也不要捕獲 Exception 或者 StandardError , 除非你打算重新觸發該異常, 或者你已經在當前執行緒的最外層(記得還是要列印一條錯誤訊息). 在異常這方面, Python非常寬容, except: 真的會捕獲包括Python語法錯誤在內的任何錯誤. 使用 except: 很容易隱藏真正的bug.
4. 儘量減少try/except塊中的程式碼量. try塊的體積越大, 期望之外的異常就越容易被觸發. 這種情況下, try/except塊將隱藏真正的錯誤.
5. 使用finally子句來執行那些無論try塊中有沒有異常都應該被執行的程式碼. 這對於清理資源常常很有用, 例如關閉檔案.
6. 當捕獲異常時, 使用 as 而不要用逗號. 例如

   try:
       raise Error
   except Error as error:
       pass

全域性變數

避免全域性變數

定義:定義在模組級的變數.優點:偶爾有用.缺點:匯入時可能改變模組行為, 因為匯入模組時會對模組級變數賦值.結論:避免使用全域性變數, 用類變數來代替. 但也有一些例外:

1. 指令碼的預設選項.
2. 模組級常量. 例如:　PI = 3.14159. 常量應該全大寫, 用下劃線連線.
3. 有時候用全域性變數來快取值或者作為函式返回值很有用.
4. 如果需要, 全域性變數應該僅在模組內部可用, 並通過模組級的公共函式來訪問.

巢狀/區域性/內部類或函式

鼓勵使用巢狀/本地/內部類或函式

定義:類可以定義在方法, 函式或者類中. 函式可以定義在方法或函式中. 封閉區間中定義的變數對巢狀函式是隻讀的.優點:允許定義僅用於有效範圍的工具類和函式.缺點:巢狀類或區域性類的例項不能序列化(pickled).結論:推薦使用.

列表推導(List Comprehensions)

可以在簡單情況下使用

定義:列表推導(list comprehensions)與生成器表示式(generator expression)提供了一種簡潔高效的方式來建立列表和迭代器, 而不必藉助map(), filter(), 或者lambda.優點:簡單的列表推導可以比其它的列表建立方法更加清晰簡單. 生成器表示式可以十分高效, 因為它們避免了建立整個列表.缺點:複雜的列表推導或者生成器表示式可能難以閱讀.結論:適用於簡單情況. 每個部分應該單獨置於一行: 對映表示式, for語句, 過濾器表示式. 禁止多重for語句或過濾器表示式. 複雜情況下還是使用迴圈.

Yes:
  result = []
  for x in range(10):
      for y in range(5):
          if x * y > 10:
              result.append((x, y))

  for x in xrange(5):
      for y in xrange(5):
          if x != y:
              for z in xrange(5):
                  if y != z:
                      yield (x, y, z)

  return ((x, complicated_transform(x))
          for x in long_generator_function(parameter)
          if x is not None)

  squares = [x * x for x in range(10)]

  eat(jelly_bean for jelly_bean in jelly_beans
      if jelly_bean.color == 'black')

No:
  result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]

  return ((x, y, z)
          for x in xrange(5)
          for y in xrange(5)
          if x != y
          for z in xrange(5)
          if y != z)

預設迭代器和操作符

如果型別支援, 就使用預設迭代器和操作符. 比如列表, 字典及檔案等.

定義:容器型別, 像字典和列表, 定義了預設的迭代器和關係測試操作符(in和not in)優點:預設操作符和迭代器簡單高效, 它們直接表達了操作, 沒有額外的方法呼叫. 使用預設操作符的函式是通用的. 它可以用於支援該操作的任何型別.缺點:你沒法通過閱讀方法名來區分物件的型別(例如, has_key()意味著字典). 不過這也是優點.結論:如果型別支援, 就使用預設迭代器和操作符, 例如列表, 字典和檔案. 內建型別也定義了迭代器方法. 優先考慮這些方法, 而不是那些返回列表的方法. 當然，這樣遍歷容器時，你將不能修改容器.

Yes:  for key in adict: ...
      if key not in adict: ...
      if obj in alist: ...
      for line in afile: ...
      for k, v in dict.iteritems(): ...

No:   for key in adict.keys(): ...
      if not adict.has_key(key): ...
      for line in afile.readlines(): ...

生成器

按需使用生成器.

定義:所謂生成器函式, 就是每當它執行一次生成(yield)語句, 它就返回一個迭代器, 這個迭代器生成一個值. 生成值後, 生成器函式的執行狀態將被掛起, 直到下一次生成.優點:簡化程式碼, 因為每次呼叫時, 區域性變數和控制流的狀態都會被儲存. 比起一次建立一系列值的函式, 生成器使用的記憶體更少.缺點:沒有.結論:鼓勵使用. 注意在生成器函式的文件字串中使用”Yields:”而不是”Returns:”.(譯者注: 參看 註釋 )

Lambda函式

適用於單行函式

定義:與語句相反, lambda在一個表示式中定義匿名函式. 常用於為 map() 和 filter() 之類的高階函式定義回撥函式或者操作符.優點:方便.缺點:比本地函式更難閱讀和除錯. 沒有函式名意味著堆疊跟蹤更難理解. 由於lambda函式通常只包含一個表示式, 因此其表達能力有限.結論:適用於單行函式. 如果程式碼超過60-80個字元, 最好還是定義成常規(巢狀)函式.對於常見的操作符，例如乘法操作符，使用 operator 模組中的函式以代替lambda函式. 例如, 推薦使用 operator.mul , 而不是 lambda x, y: x * y .

條件表示式

適用於單行函式

定義:條件表示式是對於if語句的一種更為簡短的句法規則. 例如: x = 1 if cond else 2 .優點:比if語句更加簡短和方便.缺點:比if語句難於閱讀. 如果表示式很長， 難於定位條件.結論:適用於單行函式. 在其他情況下，推薦使用完整的if語句.

預設引數值

適用於大部分情況.

定義:你可以在函式引數列表的最後指定變數的值, 例如, def foo(a, b = 0): . 如果呼叫foo時只帶一個引數, 則b被設為0. 如果帶兩個引數, 則b的值等於第二個引數.優點:你經常會碰到一些使用大量預設值的函式, 但偶爾(比較少見)你想要覆蓋這些預設值. 預設引數值提供了一種簡單的方法來完成這件事, 你不需要為這些罕見的例外定義大量函式. 同時, Python也不支援過載方法和函式, 預設引數是一種”仿造”過載行為的簡單方式.缺點:預設引數只在模組載入時求值一次. 如果引數是列表或字典之類的可變型別, 這可能會導致問題. 如果函式修改了物件(例如向列表追加項), 預設值就被修改了.結論:鼓勵使用, 不過有如下注意事項:不要在函式或方法定義中使用可變物件作為預設值.

Yes: def foo(a, b=None):
         if b is None:
             b = []

No:  def foo(a, b=[]):
         ...
No:  def foo(a, b=time.time()):  # The time the module was loaded???
         ...
No:  def foo(a, b=FLAGS.my_thing):  # sys.argv has not yet been parsed...
         ...

屬性(properties)

訪問和設定資料成員時, 你通常會使用簡單, 輕量級的訪問和設定函式. 建議用屬性（properties）來代替它們.

定義:一種用於包裝方法呼叫的方式. 當運算量不大, 它是獲取和設定屬性(attribute)的標準方式.優點:通過消除簡單的屬性(attribute)訪問時顯式的get和set方法呼叫, 可讀性提高了. 允許懶惰的計算. 用Pythonic的方式來維護類的介面. 就效能而言, 當直接訪問變數是合理的, 新增訪問方法就顯得瑣碎而無意義. 使用屬性(properties)可以繞過這個問題. 將來也可以在不破壞介面的情況下將訪問方法加上.缺點:屬性(properties)是在get和set方法宣告後指定, 這需要使用者在接下來的程式碼中注意: set和get是用於屬性(properties)的(除了用 @property 裝飾器建立的只讀屬性). 必須繼承自object類. 可能隱藏比如操作符過載之類的副作用. 繼承時可能會讓人困惑.結論:你通常習慣於使用訪問或設定方法來訪問或設定資料, 它們簡單而輕量. 不過我們建議你在新的程式碼中使用屬性. 只讀屬性應該用 @property 裝飾器 來建立.如果子類沒有覆蓋屬性, 那麼屬性的繼承可能看上去不明顯. 因此使用者必須確保訪問方法間接被呼叫, 以保證子類中的過載方法被屬性呼叫(使用模板方法設計模式).

Yes: import math

     class Square(object):
         """A square with two properties: a writable area and a read-only perimeter.

         To use:
         >>> sq = Square(3)
         >>> sq.area
         9
         >>> sq.perimeter
         12
         >>> sq.area = 16
         >>> sq.side
         4
         >>> sq.perimeter
         16
         """

         def __init__(self, side):
             self.side = side

         def __get_area(self):
             """Calculates the 'area' property."""
             return self.side ** 2

         def ___get_area(self):
             """Indirect accessor for 'area' property."""
             return self.__get_area()

         def __set_area(self, area):
             """Sets the 'area' property."""
             self.side = math.sqrt(area)

         def ___set_area(self, area):
             """Indirect setter for 'area' property."""
             self._SetArea(area)

         area = property(___get_area, ___set_area,
                         doc="""Gets or sets the area of the square.""")

         @property
         def perimeter(self):
             return self.side * 4

(譯者注: 老實說, 我覺得這段示例程式碼很不恰當, 有必要這麼蛋疼嗎?)

True/False的求值

儘可能使用隱式false

定義:Python在布林上下文中會將某些值求值為false. 按簡單的直覺來講, 就是所有的”空”值都被認為是false. 因此0， None, [], {}, “” 都被認為是false.優點:使用Python布林值的條件語句更易讀也更不易犯錯. 大部分情況下, 也更快.缺點:對C/C++開發人員來說, 可能看起來有點怪.結論:儘可能使用隱式的false, 例如: 使用 if foo: 而不是 if foo != []: . 不過還是有一些注意事項需要你銘記在心:

1. 永遠不要用==或者!=來比較單件, 比如None. 使用is或者is not.
2. 注意: 當你寫下 if x: 時, 你其實表示的是 if x is not None . 例如: 當你要測試一個預設值是None的變數或引數是否被設為其它值. 這個值在布林語義下可能是false!
3. 永遠不要用==將一個布林量與false相比較. 使用 if not x: 代替. 如果你需要區分false和None, 你應該用像 if not x and x is not None: 這樣的語句.
4. 對於序列(字串, 列表, 元組), 要注意空序列是false. 因此 if not seq: 或者 if seq: 比 if len(seq): 或 if not len(seq): 要更好.
5. 處理整數時, 使用隱式false可能會得不償失(即不小心將None當做0來處理). 你可以將一個已知是整型(且不是len()的返回結果)的值與0比較.

   Yes: if not users:
            print 'no users'
   
        if foo == 0:
            self.handle_zero()
   
        if i % 10 == 0:
            self.handle_multiple_of_ten()

   No:  if len(users) == 0:
            print 'no users'
   
        if foo is not None and not foo:
            self.handle_zero()
   
        if not i % 10:
            self.handle_multiple_of_ten()

6. 注意‘0’(字串)會被當做true.

過時的語言特性

儘可能使用字串方法取代字串模組. 使用函式呼叫語法取代apply(). 使用列表推導, for迴圈取代filter(), map()以及reduce().

定義:當前版本的Python提供了大家通常更喜歡的替代品.結論:我們不使用不支援這些特性的Python版本, 所以沒理由不用新的方式.

Yes: words = foo.split(':')

     [x[1] for x in my_list if x[2] == 5]

     map(math.sqrt, data)    # Ok. No inlined lambda expression.

     fn(*args, **kwargs)

No:  words = string.split(foo, ':')

     map(lambda x: x[1], filter(lambda x: x[2] == 5, my_list))

     apply(fn, args, kwargs)

詞法作用域(Lexical Scoping)

推薦使用

定義:巢狀的Python函式可以引用外層函式中定義的變數, 但是不能夠對它們賦值. 變數繫結的解析是使用詞法作用域, 也就是基於靜態的程式文字. 對一個塊中的某個名稱的任何賦值都會導致Python將對該名稱的全部引用當做區域性變數, 甚至是賦值前的處理. 如果碰到global宣告, 該名稱就會被視作全域性變數.一個使用這個特性的例子:

def get_adder(summand1):
    """Returns a function that adds numbers to a given number."""
    def adder(summand2):
        return summand1 + summand2

    return adder

(譯者注: 這個例子有點詭異, 你應該這樣使用這個函式: sum = get_adder(summand1)(summand2) )

優點:通常可以帶來更加清晰, 優雅的程式碼. 尤其會讓有經驗的Lisp和Scheme(還有Haskell, ML等)程式設計師感到欣慰.缺點:可能導致讓人迷惑的bug. 例如下面這個依據 PEP-0227 的例子:

i = 4
def foo(x):
    def bar():
        print i,
    # ...
    # A bunch of code here
    # ...
    for i in x:  # Ah, i *is* local to Foo, so this is what Bar sees
        print i,
    bar()

因此 foo([1, 2, 3]) 會列印 1 2 3 3 , 不是 1 2 3 4 .

(譯者注: x是一個列表, for迴圈其實是將x中的值依次賦給i.這樣對i的賦值就隱式的發生了, 整個foo函式體中的i都會被當做區域性變數, 包括bar()中的那個. 這一點與C++之類的靜態語言還是有很大差別的.)

結論:鼓勵使用.

函式與方法裝飾器

如果好處很顯然, 就明智而謹慎的使用裝飾器

定義:用於函式及方法的裝飾器 (也就是@標記). 最常見的裝飾器是@classmethod 和@staticmethod, 用於將常規函式轉換成類方法或靜態方法. 不過, 裝飾器語法也允許使用者自定義裝飾器. 特別地, 對於某個函式 my_decorator , 下面的兩段程式碼是等效的:

class C(object):
   @my_decorator
   def method(self):
       # method body ...

class C(object):
    def method(self):
        # method body ...
    method = my_decorator(method)

優點:優雅的在函式上指定一些轉換. 該轉換可能減少一些重複程式碼, 保持已有函式不變(enforce invariants), 等.缺點:裝飾器可以在函式的引數或返回值上執行任何操作, 這可能導致讓人驚異的隱藏行為. 而且, 裝飾器在匯入時執行. 從裝飾器程式碼的失敗中恢復更加不可能.結論:如果好處很顯然, 就明智而謹慎的使用裝飾器. 裝飾器應該遵守和函式一樣的匯入和命名規則. 裝飾器的python文件應該清晰的說明該函式是一個裝飾器. 請為裝飾器編寫單元測試.避免裝飾器自身對外界的依賴(即不要依賴於檔案, socket, 資料庫連線等), 因為裝飾器執行時這些資源可能不可用(由 pydoc 或其它工具匯入). 應該保證一個用有效引數呼叫的裝飾器在所有情況下都是成功的.裝飾器是一種特殊形式的”頂級程式碼”. 參考後面關於 Main 的話題.

執行緒

不要依賴內建型別的原子性.

雖然Python的內建型別例如字典看上去擁有原子操作, 但是在某些情形下它們仍然不是原子的(即: 如果__hash__或__eq__被實現為Python方法)且它們的原子性是靠不住的. 你也不能指望原子變數賦值(因為這個反過來依賴字典).

優先使用Queue模組的 Queue 資料型別作為執行緒間的資料通訊方式. 另外, 使用threading模組及其鎖原語(locking primitives). 瞭解條件變數的合適使用方式, 這樣你就可以使用 threading.Condition 來取代低階別的鎖了.

威力過大的特性

避免使用這些特性

定義:Python是一種異常靈活的語言, 它為你提供了很多花哨的特性, 諸如元類(metaclasses), 位元組碼訪問, 任意編譯(on-the-fly compilation), 動態繼承, 物件父類重定義(object reparenting), 匯入黑客(import hacks), 反射, 系統內修改(modification of system internals), 等等.優點:強大的語言特性, 能讓你的程式碼更緊湊.缺點:使用這些很”酷”的特性十分誘人, 但不是絕對必要. 使用奇技淫巧的程式碼將更加難以閱讀和除錯. 開始可能還好(對原作者而言), 但當你回顧程式碼, 它們可能會比那些稍長一點但是很直接的程式碼更加難以理解.結論:在你的程式碼中避免這些特性.

Python風格規範

分號

不要在行尾加分號, 也不要用分號將兩條命令放在同一行.

行長度

每行不超過80個字元

例外:

1. 長的匯入模組語句
2. 註釋裡的URL

不要使用反斜槓連線行.

Python會將 圓括號, 中括號和花括號中的行隱式的連線起來 , 你可以利用這個特點. 如果需要, 你可以在表示式外圍增加一對額外的圓括號.

Yes: foo_bar(self, width, height, color='black', design=None, x='foo',
             emphasis=None, highlight=0)

     if (width == 0 and height == 0 and
         color == 'red' and emphasis == 'strong'):

如果一個文字字串在一行放不下, 可以使用圓括號來實現隱式行連線:

x = ('This will build a very long long '
     'long long long long long long string')

在註釋中，如果必要，將長的URL放在一行上。

Yes:  # See details at
      # http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html

No:  # See details at
     # http://www.example.com/us/developer/documentation/api/content/\
     # v2.0/csv_file_name_extension_full_specification.html

注意上面例子中的元素縮排; 你可以在本文的 縮排 部分找到解釋.

括號

寧缺毋濫的使用括號

除非是用於實現行連線, 否則不要在返回語句或條件語句中使用括號. 不過在元組兩邊使用括號是可以的.

Yes: if foo:
         bar()
     while x:
         x = bar()
     if x and y:
         bar()
     if not x:
         bar()
     return foo
     for (x, y) in dict.items(): ...

No:  if (x):
         bar()
     if not(x):
         bar()
     return (foo)

縮排

用4個空格來縮排程式碼

絕對不要用tab, 也不要tab和空格混用. 對於行連線的情況, 你應該要麼垂直對齊換行的元素(見 行長度 部分的示例), 或者使用4空格的懸掛式縮排(這時第一行不應該有引數):

Yes:   # Aligned with opening delimiter
       foo = long_function_name(var_one, var_two,
                                var_three, var_four)

       # Aligned with opening delimiter in a dictionary
       foo = {
           long_dictionary_key: value1 +
                                value2,
           ...
       }

       # 4-space hanging indent; nothing on first line
       foo = long_function_name(
           var_one, var_two, var_three,
           var_four)

       # 4-space hanging indent in a dictionary
       foo = {
           long_dictionary_key:
               long_dictionary_value,
           ...
       }

No:    # Stuff on first line forbidden
      foo = long_function_name(var_one, var_two,
          var_three, var_four)

      # 2-space hanging indent forbidden
      foo = long_function_name(
        var_one, var_two, var_three,
        var_four)

      # No hanging indent in a dictionary
      foo = {
          long_dictionary_key:
              long_dictionary_value,
              ...
      }

空行

頂級定義之間空兩行, 方法定義之間空一行

頂級定義之間空兩行, 比如函式或者類定義. 方法定義, 類定義與第一個方法之間, 都應該空一行. 函式或方法中, 某些地方要是你覺得合適, 就空一行.

空格

按照標準的排版規範來使用標點兩邊的空格

括號內不要有空格.

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

引數列表, 索引或切片的左括號前不應加空格.

Yes: spam(1)

no: spam (1)

Yes: dict['key'] = list[index]

No:  dict ['key'] = list [index]

在二元操作符兩邊都加上一個空格, 比如賦值(=), 比較(==, <, >, !=, <>, <=, >=, in, not in, is, is not), 布林(and, or, not). 至於算術操作符兩邊的空格該如何使用, 需要你自己好好判斷. 不過兩側務必要保持一致.

Yes: x == 1

No:  x<1

當’=’用於指示關鍵字引數或預設引數值時, 不要在其兩側使用空格.

Yes: def complex(real, imag=0.0): return magic(r=real, i=imag)

No:  def complex(real, imag = 0.0): return magic(r = real, i = imag)

不要用空格來垂直對齊多行間的標記, 因為這會成為維護的負擔(適用於:, #, =等):

Yes:
     foo = 1000  # comment
     long_name = 2  # comment that should not be aligned

     dictionary = {
         "foo": 1,
         "long_name": 2,
         }

No:
     foo       = 1000  # comment
     long_name = 2     # comment that should not be aligned

     dictionary = {
         "foo"      : 1,
         "long_name": 2,
         }

Shebang

大部分.py檔案不必以#!作為檔案的開始. 根據 PEP-394 , 程式的main檔案應該以 #!/usr/bin/python2或者 #!/usr/bin/python3開始.

(譯者注: 在電腦科學中, Shebang (也稱為Hashbang)是一個由井號和歎號構成的字串行(#!), 其出現在文字檔案的第一行的前兩個字元. 在檔案中存在Shebang的情況下, 類Unix作業系統的程式載入器會分析Shebang後的內容, 將這些內容作為直譯器指令, 並呼叫該指令, 並將載有Shebang的檔案路徑作為該直譯器的引數. 例如, 以指令#!/bin/sh開頭的檔案在執行時會實際呼叫/bin/sh程式.)

#!先用於幫助核心找到Python直譯器, 但是在匯入模組時, 將會被忽略. 因此只有被直接執行的檔案中才有必要加入#!.

註釋

確保對模組, 函式, 方法和行內註釋使用正確的風格

文件字串

Python有一種獨一無二的的註釋方式: 使用文件字串. 文件字串是包, 模組, 類或函式裡的第一個語句. 這些字串可以通過物件的__doc__成員被自動提取, 並且被pydoc所用. (你可以在你的模組上執行pydoc試一把, 看看它長什麼樣). 我們對文件字串的慣例是使用三重雙引號”“”( PEP-257 ). 一個文件字串應該這樣組織: 首先是一行以句號, 問號或驚歎號結尾的概述(或者該文件字串單純只有一行). 接著是一個空行. 接著是文件字串剩下的部分, 它應該與文件字串的第一行的第一個引號對齊. 下面有更多文件字串的格式化規範.

模組

每個檔案應該包含一個許可樣板. 根據專案使用的許可(例如, Apache 2.0, BSD, LGPL, GPL), 選擇合適的樣板.

函式和方法

下文所指的函式,包括函式, 方法, 以及生成器.

一個函式必須要有文件字串, 除非它滿足以下條件:

1. 外部不可見
2. 非常短小
3. 簡單明瞭

文件字串應該包含函式做什麼, 以及輸入和輸出的詳細描述. 通常, 不應該描述”怎麼做”, 除非是一些複雜的演算法. 文件字串應該提供足夠的資訊, 當別人編寫程式碼呼叫該函式時, 他不需要看一行程式碼, 只要看文件字串就可以了. 對於複雜的程式碼, 在程式碼旁邊加註釋會比使用文件字串更有意義.

關於函式的幾個方面應該在特定的小節中進行描述記錄， 這幾個方面如下文所述. 每節應該以一個標題行開始. 標題行以冒號結尾. 除標題行外, 節的其他內容應被縮排2個空格.

Args:列出每個引數的名字, 並在名字後使用一個冒號和一個空格, 分隔對該引數的描述.如果描述太長超過了單行80字元,使用2或者4個空格的懸掛縮排(與檔案其他部分保持一致). 描述應該包括所需的型別和含義. 如果一個函式接受*foo(可變長度引數列表)或者**bar (任意關鍵字引數), 應該詳細列出*foo和**bar.Returns: (或者 Yields: 用於生成器)描述返回值的型別和語義. 如果函式返回None, 這一部分可以省略.Raises:列出與介面有關的所有異常.

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """
    pass

類

類應該在其定義下有一個用於描述該類的文件字串. 如果你的類有公共屬性(Attributes), 那麼文件中應該有一個屬性(Attributes)段. 並且應該遵守和函式引數相同的格式.

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

塊註釋和行註釋

最需要寫註釋的是程式碼中那些技巧性的部分. 如果你在下次 程式碼審查 的時候必須解釋一下, 那麼你應該現在就給它寫註釋. 對於複雜的操作, 應該在其操作開始前寫上若干行註釋. 對於不是一目瞭然的程式碼, 應在其行尾新增註釋.

# We use a weighted dictionary search to find out where i is in
# the array.  We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.

if i & (i-1) == 0:        # true iff i is a power of 2

為了提高可讀性, 註釋應該至少離開程式碼2個空格.

另一方面, 絕不要描述程式碼. 假設閱讀程式碼的人比你更懂Python, 他只是不知道你的程式碼要做什麼.

# BAD COMMENT: Now go through the b array and make sure whenever i occurs
# the next element is i+1

類

如果一個類不繼承自其它類, 就顯式的從object繼承. 巢狀類也一樣.

Yes: class SampleClass(object):
         pass

     class OuterClass(object):

         class InnerClass(object):
             pass

     class ChildClass(ParentClass):
         """Explicitly inherits from another class already."""

No: class SampleClass:
        pass

    class OuterClass:

        class InnerClass:
            pass

繼承自 object 是為了使屬性(properties)正常工作, 並且這樣可以保護你的程式碼, 使其不受 PEP-3000 的一個特殊的潛在不相容性影響. 這樣做也定義了一些特殊的方法, 這些方法實現了物件的預設語義, 包括 __new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, and __str__ .

字串

即使引數都是字串, 使用%操作符或者格式化方法格式化字串. 不過也不能一概而論, 你需要在+和%之間好好判定.

Yes: x = a + b
     x = '%s, %s!' % (imperative, expletive)
     x = '{}, {}!'.format(imperative, expletive)
     x = 'name: %s; score: %d' % (name, n)
     x = 'name: {}; score: {}'.format(name, n)

No: x = '%s%s' % (a, b)  # use + in this case
    x = '{}{}'.format(a, b)  # use + in this case
    x = imperative + ', ' + expletive + '!'
    x = 'name: ' + name + '; score: ' + str(n)

避免在迴圈中用+和+=操作符來累加字串. 由於字串是不可變的, 這樣做會建立不必要的臨時物件, 並且導致二次方而不是線性的執行時間. 作為替代方案, 你可以將每個子串加入列表, 然後在迴圈結束後用 .join 連線列表. (也可以將每個子串寫入一個 cStringIO.StringIO 快取中.)

Yes: items = ['<table>']
     for last_name, first_name in employee_list:
         items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
     items.append('</table>')
     employee_table = ''.join(items)

No: employee_table = '<table>'
    for last_name, first_name in employee_list:
        employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
    employee_table += '</table>'

在同一個檔案中, 保持使用字串引號的一致性. 使用單引號’或者雙引號”之一用以引用字串, 並在同一檔案中沿用. 在字串內可以使用另外一種引號, 以避免在字串中使用. GPyLint已經加入了這一檢查.

(譯者注:GPyLint疑為筆誤, 應為PyLint.)

Yes:
     Python('Why are you hiding your eyes?')
     Gollum("I'm scared of lint errors.")
     Narrator('"Good!" thought a happy Python reviewer.')

No:
     Python("Why are you hiding your eyes?")
     Gollum('The lint. It burns. It burns us.')
     Gollum("Always the great lint. Watching. Watching.")

為多行字串使用三重雙引號”“”而非三重單引號’‘’. 當且僅當專案中使用單引號’來引用字串時, 才可能會使用三重’‘’為非文件字串的多行字串來標識引用. 文件字串必須使用三重雙引號”“”. 不過要注意, 通常用隱式行連線更清晰, 因為多行字串與程式其他部分的縮排方式不一致.

Yes:
    print ("This is much nicer.\n"
           "Do it this way.\n")

No:
      print """This is pretty ugly.
  Don't do this.
  """

檔案和sockets

在檔案和sockets結束時, 顯式的關閉它.

除檔案外, sockets或其他類似檔案的物件在沒有必要的情況下開啟, 會有許多副作用, 例如:

1. 它們可能會消耗有限的系統資源, 如檔案描述符. 如果這些資源在使用後沒有及時歸還系統, 那麼用於處理這些物件的程式碼會將資源消耗殆盡.
2. 持有檔案將會阻止對於檔案的其他諸如移動、刪除之類的操作.
3. 僅僅是從邏輯上關閉檔案和sockets, 那麼它們仍然可能會被其共享的程式在無意中進行讀或者寫操作. 只有當它們真正被關閉後, 對於它們嘗試進行讀或者寫操作將會跑出異常, 並使得問題快速顯現出來.

而且, 幻想當檔案物件析構時, 檔案和sockets會自動關閉, 試圖將檔案物件的生命週期和檔案的狀態繫結在一起的想法, 都是不現實的. 因為有如下原因:

1. 沒有任何方法可以確保執行環境會真正的執行檔案的析構. 不同的Python實現採用不同的記憶體管理技術, 比如延時垃圾處理機制. 延時垃圾處理機制可能會導致物件生命週期被任意無限制的延長.
2. 對於檔案意外的引用,會導致對於檔案的持有時間超出預期(比如對於異常的跟蹤, 包含有全域性變數等).

推薦使用 “with”語句 以管理檔案:

with open("hello.txt") as hello_file:
    for line in hello_file:
        print line

對於不支援使用”with”語句的類似檔案的物件,使用 contextlib.closing():

import contextlib

with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
    for line in front_page:
        print line

Legacy AppEngine 中Python 2.5的程式碼如使用”with”語句, 需要新增 “from __future__ import with_statement”.

TODO註釋

為臨時程式碼使用TODO註釋, 它是一種短期解決方案. 不算完美, 但夠好了.

TODO註釋應該在所有開頭處包含”TODO”字串, 緊跟著是用括號括起來的你的名字, email地址或其它識別符號. 然後是一個可選的冒號. 接著必須有一行註釋, 解釋要做什麼. 主要目的是為了有一個統一的TODO格式, 這樣新增註釋的人就可以搜尋到(並可以按需提供更多細節). 寫了TODO註釋並不保證寫的人會親自解決問題. 當你寫了一個TODO, 請註上你的名字.

# TODO(kl@gmail.com): Use a "*" here for string repetition.
# TODO(Zeke) Change this to use relations.

如果你的TODO是”將來做某事”的形式, 那麼請確保你包含了一個指定的日期(“2009年11月解決”)或者一個特定的事件(“等到所有的客戶都可以處理XML請求就移除這些程式碼”).

匯入格式

每個匯入應該獨佔一行

Yes: import os
     import sys

No:  import os, sys

匯入總應該放在檔案頂部, 位於模組註釋和文件字串之後, 模組全域性變數和常量之前. 匯入應該按照從最通用到最不通用的順序分組:

1. 標準庫匯入
2. 第三方庫匯入
3. 應用程式指定匯入

每種分組中, 應該根據每個模組的完整包路徑按字典序排序, 忽略大小寫.

import foo
from foo import bar
from foo.bar import baz
from foo.bar import Quux
from Foob import ar

語句

通常每個語句應該獨佔一行

不過, 如果測試結果與測試語句在一行放得下, 你也可以將它們放在同一行. 如果是if語句, 只有在沒有else時才能這樣做. 特別地, 絕不要對 try/except 這樣做, 因為try和except不能放在同一行.

Yes:

  if foo: bar(foo)

No:

  if foo: bar(foo)
  else:   baz(foo)

  try:               bar(foo)
  except ValueError: baz(foo)

  try:
      bar(foo)
  except ValueError: baz(foo)

訪問控制

在Python中, 對於瑣碎又不太重要的訪問函式, 你應該直接使用公有變數來取代它們, 這樣可以避免額外的函式呼叫開銷. 當新增更多功能時, 你可以用屬性(property)來保持語法的一致性.

(譯者注: 重視封裝的物件導向程式設計師看到這個可能會很反感, 因為他們一直被教育: 所有成員變數都必須是私有的! 其實, 那真的是有點麻煩啊. 試著去接受Pythonic哲學吧)

另一方面, 如果訪問更復雜, 或者變數的訪問開銷很顯著, 那麼你應該使用像 get_foo() 和 set_foo()這樣的函式呼叫. 如果之前的程式碼行為允許通過屬性(property)訪問 , 那麼就不要將新的訪問函式與屬性繫結. 這樣, 任何試圖通過老方法訪問變數的程式碼就沒法執行, 使用者也就會意識到複雜性發生了變化.

命名

module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.

應該避免的名稱

1. 單字元名稱, 除了計數器和迭代器.
2. 包/模組名中的連字元(-)
3. 雙下劃線開頭並結尾的名稱(Python保留, 例如__init__)

命名約定

1. 所謂”內部(Internal)”表示僅模組內可用, 或者, 在類內是保護或私有的.
2. 用單下劃線(_)開頭表示模組變數或函式是protected的(使用import * from時不會包含).
3. 用雙下劃線(__)開頭的例項變數或方法表示類內私有.
4. 將相關的類和頂級函式放在同一個模組裡. 不像Java, 沒必要限制一個類一個模組.
5. 對類名使用大寫字母開頭的單詞(如CapWords, 即Pascal風格), 但是模組名應該用小寫加下劃線的方式(如lower_with_under.py). 儘管已經有很多現存的模組使用類似於CapWords.py這樣的命名, 但現在已經不鼓勵這樣做, 因為如果模組名碰巧和類名一致, 這會讓人困擾.

Python之父Guido推薦的規範

Type	Public	Internal
Modules	lower_with_under	_lower_with_under
Packages	lower_with_under
Classes	CapWords	_CapWords
Exceptions	CapWords
Functions	lower_with_under()	_lower_with_under()
Global/Class Constants	CAPS_WITH_UNDER	_CAPS_WITH_UNDER
Global/Class Variables	lower_with_under	_lower_with_under
Instance Variables	lower_with_under	_lower_with_under (protected) or __lower_with_under (private)
Method Names	lower_with_under()	_lower_with_under() (protected) or __lower_with_under() (private)
Function/Method Parameters	lower_with_under
Local Variables	lower_with_under

Main

即使是一個打算被用作指令碼的檔案, 也應該是可匯入的. 並且簡單的匯入不應該導致這個指令碼的主功能(main functionality)被執行, 這是一種副作用. 主功能應該放在一個main()函式中.

在Python中, pydoc以及單元測試要求模組必須是可匯入的. 你的程式碼應該在執行主程式前總是檢查 if __name__ == '__main__' , 這樣當模組被匯入時主程式就不會被執行.

def main():
      ...

if __name__ == '__main__':
    main()

所有的頂級程式碼在模組匯入時都會被執行. 要小心不要去呼叫函式, 建立物件, 或者執行那些不應該在使用pydoc時執行的操作.