Python PEP8 編碼規範

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

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 介紹 A Foolish Consistency is the Hobgoblin of Little Minds 盡信書則不如無書 Code lay-out 代碼布局 Indentation 縮排 Tabs or Spaces 定位字元還是空格 Maximum Line Length 行的最大長度 Should a line break before or after a binary operator 在二元運算子之前應該換行嗎 Blank Lines 空行 Source File Encoding 源檔案編碼 Imports 匯入 Module level dunder names 模組層級的呆名 String Quotes 字串引號 Whitespace in Expressions and Statements 運算式和語句中的空格 Pet Peeves 不能忍受的事情 Other Recommendations 其他建議 Comments 注釋 Block Comments 塊注釋 Inline Comments 行內注釋 Documentation Strings 文檔字串 Naming Conventions 命名規範 Overriding Principle 最重要的原則 Descriptive Naming Styles 描述命名風格 Prescriptive Naming Conventions 約定俗成命名規範 Names to Avoid 應避免的名字 Package and Module Names 包名和模組名 Class Names 類名 Exception Names 異常名 Global Variable Names 全域變數名 Function Names 函數名 Function and method arguments 函數和方法參數 Method Names and Instance Variables 方法名和執行個體變數 Constants 常量 Designing for inheritance 繼承的設計 Public and internal interfaces 公用和內部的介面 Programming Recommendations 編程建議 Function Annotations 功能注釋 參考
Introduction 介紹

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

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

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

許多項目有自己的編碼規範，在出現規範衝突時，項目自身的規範優先。 A Foolish Consistency is the Hobgoblin of Little Minds 盡信書,則不如無書

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

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

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

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

幾個很好的理由去忽略特定的規則： 當遵循這份指南之後代碼的可讀性變差，甚至是遵循PEP規範的人也覺得可讀性差。 與周圍的代碼保持一致（也可能出於曆史原因），儘管這也是清理他人混亂（真正的Xtreme Programming風格）的一個機會。 有問題的代碼出現在發現編碼規範之前，而且也沒有充足的理由去修改他們。 當代碼需要相容不支援編碼規範建議的老版本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

匯入總是位於檔案的頂部，在模組注釋和文檔字串之後，在模組的全域變數與常量之前。 
匯入應該按照以下順序分組： 標準庫匯入 相關第三方庫匯入 本地應用/庫特定匯入 
你應該在每一組匯入之間加入空行。

推薦使用絕對路徑匯入，如果匯入系統沒有正確的配置（比如包裡的一個目錄在sys.path裡的路徑後），使用絕對路徑會更加可讀並且效能更好（至少能提供更好的錯誤資訊）:

import mypkg.siblingfrom mypkg import siblingfrom mypkg.sibling import example

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

from . import siblingfrom .sibling import example

標準庫要避免使用複雜的包引入結構，而總是使用絕對路徑。 
不應該使用隱式相對路徑匯入，並且在Python 3中刪除了它。 當從一個包含類的模組中匯入類時，常常這麼寫：

from myclass import MyClassfrom foo.bar.yourclass import YourClass

如果上述的寫法導致名字的衝突，那麼這麼寫：

import myclassimport 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 osimport 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, xNo:  if x == 4 : print x , y ; x , y = y , x