PEP 8 – Style Guide for Python Code

原文：PEP 8 – Style Guide for Python Code

PEP：8
題目：Python代碼風格指南
做者：Guido van Rossum, www.yszx11.cnBarry Warsaw , Nick Coghlan
狀態：Active
類型：Process
建立：2001-07-05
往期：2001-07-05，2013-08-01

內容：

介紹

該文檔提供了python編程中的一些慣例，包含Python發佈版中的一些基礎庫。 請參閱Python的C語言實現中的C代碼配套信息PEP描述風格指南[1]。
本文檔和PEP 257由Guido的原始Python風格指導文章改編，其中一些添加了Barry的風格指南的內容[2]。
這個風格指南會隨着時間的推移而演變，而過去的慣例會因語言自己的變化而過期。
在不少工程中有本身的編程風格指導。若是工程內的風格指南與本文衝突的話，前者有優先級應該更高。

呆板的堅持一致性簡直傻的沒邊了

（這個PEP8仍是挺有情懷的，標題的英文是《A foolish consistency is the hobgoblin of little minds》，出自愛默生的self reliance）

Guido的主要看法之一是咱們大部分時間是在讀代碼而不是寫。 這裏提供的指導旨在提升代碼的可讀性，使其在普遍的Python代碼中保持一致。就像PEP 20所說的：強調可讀性。
風格指南是關於一致性的。風格指南的一致性很重要。 一個項目的一致性更重要。 一個模塊或功能內的一致性是最重要的。
可是，咱們應該知道什麼時候須要不一致 - 有時風格指南的建議不適用。 若是由此疑惑的話，應當聽從本身的判斷。或者你能夠看看其餘的例子，決定什麼看起來最好。而且不要猶豫去問問題！
特別是：不要只是爲了符合這個PEP 8建議而破壞向後兼容性！

下面有些其餘的緣由可讓咱們忽略特定指導原則：
1.當使用了這個指南致使代碼可讀性不好，甚至是使用過PEP 8的人去讀依舊不好。
2.爲了與原有的代碼風格保持一致，也能夠不遵循PEP 8（多是出於歷史緣由），固然還有一種多是原有代碼的風格是亂的，這樣的話也能夠趁着這個機會整理一下以前混亂的風格。
3.代碼風格問題出現的比指南還要早，並且已經沒有什麼必要再修改。
4.當代碼須要與不支持風格指南推薦功能的舊版本的Python保持兼容時。

代碼的佈局

縮進

一次縮進使用4個空格
連續的行應使用Python的內隱行以垂直對齊的方式鏈接在圓括號、方括號或花括號內，或者使用懸掛式縮進[7]來將封裝的元素對齊。在使用懸掛式縮進時，應注意下面的問題：在第一行中不該該有任何參數（懸掛式縮進時），而且應該使用進一步的縮進來清楚表示參數的延續線。

正確的示範：

#在分界處對齊，var_one與var_three對齊
foo = long_function_name(var_one, var_two,
var_three, var_four)

#使用更多的縮進與其餘部分區分開，var_one和var_four與print()縮進不一樣
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( www.yszx11.cn var_one, var_two,
var_three, var_four)

# 參數的縮進與print()函數縮進相同
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
對於連續的行而言，四個空格的規定不是必須的。

# Hanging indents *may* be indented to other than 4 spaces.
foo = long_function_name(
var_one, var_two,
var_three, var_four)

若是if語句的條件長到須要多行才能寫下，值得注意的是，在多行條件語句中，左括號加空格再加上兩個字符關鍵字的組合的形式會爲多行條件的後續行建立一個天然的4空格縮進。這種形式很像if中的嵌套，這樣就帶來了視覺上的混淆。這個PEP對於如何（或者是否）進一步將這些條件行與if嵌套進行視覺上的區分沒有明確的規定。在這種狀況下可採用以下方式（但不限於此）：
（說了一大串，結果就是咋用都行）

# No extra indentation.
if (this_is_one_thing and
that_is_another_thing):
do_something()

# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
that_is_another_thing):
# Since both conditions are true, we can frobnicate.
do_something()

# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
and that_is_another_thing):
do_something()
（另外能夠參考下面的考慮：關於換行符應在二元運算符以前仍是以後？）

在Python的List數據結構中，右面的（closing brace/opening brace）花括號/方括號/圓括號能夠在列表的最後一行的第一個非空格字符之下排列，以下：

my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'www.yszxylpt.com c',
'd', 'e', 'f',
或者，右括號也能夠和變量名的開頭垂直對齊。

my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
用Tab仍是空格？

推薦使用空格做爲縮進方式。
Tab只有在以前就已經使用了Tab做爲縮進的代碼中繼續使用。
Python 3中禁止縮進時空格和Tab混合使用。
Python 2中混合使用了空格和Tab的代碼最好應該改爲只是用Tab。
當使用-t選項調用Python 2命令行解釋器時，會發出關於非法混合Tab和空格的代碼的警告。當使用-tt調用時，這些警告會變成錯誤。 強烈推薦使用這些選項！

行的最大長度

全部行的最大值爲79個字節。
對於長度較短的文本塊（文本輸入或註釋）較少的結構限制，行長度應限制爲72個字符。

限制所需的編輯器窗口寬度使得能夠並排打開多個文件，而且在使用在相鄰列中呈現兩個版本的代碼審閱工具時能夠正常工做。

大多數工具中的默認包裝會破壞代碼的可視化結構，使其更難於理解。選擇限制以免將窗口寬度設置爲80的編輯器中包圍，即便工具在包裝線時將標記字形放在最後一列中。一些基於Web的工具根本不能提供動態的線條包裝。

一些團隊強烈但願更長的線路長度。對於惟一或主要由可以就此問題達成協議的團隊維護的代碼，能夠將標稱行長度從80增長到100個字符（有效地將最大長度增長到99個字符），前提是註釋和文檔包裝仍然包裝72個字符

Python標準庫是保守的，而且須要將限制行限制爲79個字符（和docstrings /註釋到72）。

換行長行的首選方法是使用括號，括號和大括號內的Python隱含行延續。經過將表達式包含在括號中，能夠在多行上分割長行。這些應優先於使用反斜槓進行行連續使用。

有時，反斜槓可能仍然適用。例如，long，multiple with-statements不能使用隱式繼承，因此反斜槓是能夠接受的：

換行符應在二元運算符以前仍是以後？

幾十年來，都是推崇在二元運算符以後換行的風格。但這可能會在兩個方面損害程序的可讀性：程序員不得不將視線分散到屏幕上的不一樣的行，而且程序員還須要把視線從找到的操做數上移到上一行上。 如此，眼睛必須作額外的工做來判斷哪些項目被添加，哪些被減去：

# No: 操做數裏運算符遠
income = (gross_wages +
taxable_interest +
(dividends - qualified_dividends) -
ira_deduction -
student_loan_interest)
1
2
3
4
5
6
1
2
3
4
5
6
爲了解決易讀性的問題，數學家及其出版商遵循相反的慣例。 唐納德·克努特（Donald Knuth）在他的「電腦和排版」系列中解釋了傳統的規則：「儘管段落中的公式老是在一個二元運算符和關係運算符以後斷開，可是被顯示的公式老是在二元運算符前斷開（說實話我沒太理解這個雖然。。。可是。。。的比較，意思好像是在說在電腦裏面通常是以後斷開，可是在排版的時候是以前斷）」。
遵循數學中傳統的風格每每使代碼變得更易讀：

# Yes: 更容易對運算符和操做數配對
income = (gross_wages
+ taxable_interest
+ (dividends - www.jpg521.com qualified_dividends)
- ira_deduction

在Python代碼中，在運算符前面斷開是合法（就是說這個你的Python版本這樣寫不報錯），可是要和你以前的風格一致。而對於新的代碼，建議使用克努特推薦的風格（在前面斷開）。

空行

在開頭定義的功能和類，帶行空行。

類中定義的方法首位單行空行。

可使用額外的空行（謹慎地）來分離相關功能組。在一系列相關的單線程程序裏（例如，一組虛擬實現），不該該使用空行。

在功能函數中使用空白行，應當謹慎地指示邏輯部分。

Python接受ctrl-L的形式的做爲空格; 許多工具將這些字符視爲頁面分隔符，所以您可使用它們來分隔文件的相關部分的頁面。 請注意，一些編輯器和基於Web的代碼查看器可能不支持ctrl-L，並會在其位置顯示另外一個字形。

源文件的編碼

核心Python發行版中的代碼應始終使用UTF-8（或Python 2中的ASCII）。

使用ASCII（Python 2）或UTF-8（在Python 3中）的文件不該該具備編碼聲明。

在標準庫中，非默認編碼應僅用於測試，註釋或者評論和文檔中用以說起做者的名字。
docstring須要說起包含非ASCII字符的做者名稱時;不然，使用\ x，\ u，\ U或\ N轉義是在字符串文字中包含非ASCII數據的首選方法。

對於Python 3.0及更高版本，標準庫規定了如下策略（參見PEP 3131）：Python標準庫中的全部標識符必須使用只有ASCII的標識符，並應儘量使用英文單詞（在許多狀況下，縮寫和技術術語使用不是英文的術語）。 此外，字符串文字和註釋也必須是ASCII。 惟一的例外是（a）測試非ASCII功能的測試用例，（b）做者名稱。 名字不是拉丁字母的做者必須提供其名字的拉丁音譯。

鼓勵有全球觀衆的開源項目採起相似的政策。

引入

引入應當分行：

Yes: import os
import sys

這樣是能夠的：

from subprocess import Popen, PIPE

import一般在文件的開頭位置，僅僅在模塊的註釋、文檔字符串說明、全局變量和常量以後。

引入應按如下順序分組：

1.標準庫
2.相關第三方庫
3.自定義庫
您應該在每組導入之間留一個空行。

推薦絕對引入的方式，它們一般可讀性更好。若是導入系統配置不正確，至少能夠提供更準確的錯誤消息。（例如，當一個包中的目錄在sys.path中最終出現時）

import mypkg.sibling
from mypkg import sibling
from mypkg.sibling www.wmyl88.com/ import example
1
2
3
1
2
3
固然，明確的相對引入是絕對引入的可接受的替代方案，特別是在處理複雜的佈局時，絕對引入的方式將帶來沒必要要的冗長的字符：

from . import sibling
from .sibling import example
1
2
1
2
標準庫代碼應避免複雜的佈局，並始終使用絕對引入的方式引入。
不明確相對引入的方式步應該被使用，而且已經在Python 3中被刪除了。
若是從類的包含模塊中導入類，一般能夠這樣寫：

from myclass import MyClass
from foo.bar.yourclass import YourClass
1
2
1
2
可是若是這樣寫形成本地命名衝突的話，就這樣寫：

import myclass
import foo.bar.your www.lieqibiji.com class
1
2
1
2
而後這樣使用：
「myclass.MyClass」
「foo.bar.yourclass.YourClass」

應避免使用通配符導入（from <module> import *），由於它們使在名稱空間中的不清楚，從而使不論是讀者仍是許多自動化編譯工具都很困惑。通配符導入有一個防護用例，它是做爲公共API的一部分從新發佈一個內部接口 （例如，覆蓋來自可選加速器模塊的定義的界面的純Python實現，以及將覆蓋哪些定義是未知的）。

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

模塊的雙下劃線命名

具備兩個前導和後下劃線的模塊de 名稱（如__all__，__author__，__version__等）應放置在模塊的字符串說明以後，import操做以前。（除了__future__）
Python要求將來的導入必須出如今的全部其餘引入代碼以後（除了字符串說明）。

例如：

"""
This is the example www.wmyl11.com module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import osimport sys