Python文件的常見標頭格式是什麼？

在有關Python編碼準則的文檔中，我遇到了如下Python源文件的頭格式：

#!/usr/bin/env python

"""Foobar.py: Description of what foobar does."""

__author__      = "Barack Obama"
__copyright__   = "Copyright 2009, Planet Earth"

這是Python世界中標頭的標準格式嗎？ 我還能夠在標題中添加哪些其餘字段/信息？ Python專家分享了有關好的Python源標頭的指南：-)

---

#1樓

Foobar模塊的全部元數據。

第一個是模塊的docstring ，已經在Peter的答案中進行瞭解釋。

如何組織模塊（源文件）？ （存檔）

每一個文件的第一行應該是#!/usr/bin/env python 。 這樣就能夠將文件做爲腳本運行，例如在CGI上下文中隱式調用解釋器。

接下來應該是帶有說明的文檔字符串。 若是描述很長，則第一行應該是一個簡短的摘要，該摘要應具備其自身的意義，並以換行符分隔其他部分。

全部代碼，包括導入語句，都應遵循文檔字符串。 不然，解釋器將沒法識別該文檔字符串，而且您將沒法在交互式會話中（即經過obj.__doc__ ）或使用自動化工具生成文檔時訪問該文檔字符串。

首先導入內置模塊，而後導入第三方模塊，而後再導入路徑和您本身的模塊。 特別是，模塊的路徑和名稱的添加可能會快速更改：將它們放在一個位置可使它們更容易找到。

接下來應該是做者信息。 此信息應遵循如下格式：

__author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell" __copyright__ = "Copyright 2007, The Cogent Project" __credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley", "Matthew Wakefield"] __license__ = "GPL" __version__ = "1.0.1" __maintainer__ = "Rob Knight" __email__ = "rob@spot.colorado.edu" __status__ = "Production"

狀態一般應爲「原型」，「開發」或「生產」之一。 __maintainer__應該是修復錯誤並進行改進（若是導入）的人。 __credits__不一樣於__author__在__credits__包括誰報告bug修復，提出建議等，但實際上並無寫代碼的人。

在這裏，您__author__更多信息，列出__author__ __authors__ ， __contact__ __copyright__ __license__ ， __deprecated__ ， __date__ __version__ __author__ ， __authors__ __contact__ __copyright__ ， __license__ __deprecated__ ， __date__和__version__做爲公認的元數據。

---

#2樓

若是使用的是非ASCII字符集，另請參閱PEP 263

抽象

該PEP建議引入一種語法，以聲明Python源文件的編碼。 而後，Python解析器將使用編碼信息使用給定的編碼來解釋文件。 最值得注意的是，這加強了源代碼中Unicode文字的解釋，並使得能夠在例如Unicode的編輯器中直接使用UTF-8編寫Unicode文字。

問題

在Python 2.1中，只能使用基於Latin-1的編碼「 unicode-escape」編寫Unicode文字。 這使得編程環境對在許多亞洲國家這樣的非拉丁1語言環境中生活和工做的Python用戶而言至關不利。 程序員可使用最喜歡的編碼來編寫其8位字符串，可是綁定到Unicode文字的「 unicode-escape」編碼。

擬議的解決方案

我建議經過在文件頂部使用特殊註釋來聲明該編碼，從而使每一個源文件均可以看到和更改Python源代碼。

爲了使Python知道此編碼聲明，在處理Python源代碼數據方面須要進行一些概念上的更改。

定義編碼

若是沒有其餘編碼提示，Python將默認使用ASCII做爲標準編碼。

要定義源代碼編碼，必須將魔術註釋做爲源文件的第一行或第二行放置在源文件中，例如：

# coding=<encoding name>

或（使用流行的編輯器承認的格式）

#!/usr/bin/python # -*- coding: <encoding name> -*-

要麼

#!/usr/bin/python # vim: set fileencoding=<encoding name> :

...

---

#3樓

上面的答案確實很完整，可是若是您想要一個快速且髒的標題來複制粘貼，請使用如下命令：

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""Module documentation goes here
   and here
   and ...
"""

爲何這是一個好人：

• 第一行適用於* nix用戶。 它將在用戶路徑中選擇Python解釋器，所以將自動選擇用戶首選的解釋器。
• 第二個是文件編碼。 現在，每一個文件都必須具備關聯的編碼。 UTF-8能夠在任何地方使用。 只是遺留項目會使用其餘編碼。
• 和一個很是簡單的文檔。 它能夠填充多行。

另請參閱： https : //www.python.org/dev/peps/pep-0263/

若是僅在每一個文件中編寫一個類，則甚至不須要文檔（它會放在類doc中）。

---

#4樓

我強烈同意使用最少的文件頭，個人意思是：

• hashbang（ #!行）（若是這是可執行腳本）
• 模塊文檔字符串
• 導入，以標準方式分組，例如：

import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule

即。 三組進口，它們之間有一個空白行。 在每一個組中，對進口進行排序。 最後一組，從本地來源進口，能夠是如圖所示的絕對進口，也能夠是明確的相對進口。

其餘全部內容都浪費時間，佔用視覺空間，而且會產生誤導。

若是您有法律免責聲明或許可信息，它將進入一個單獨的文件中。 它不須要感染每一個源代碼文件。 您的版權應該是其中的一部分。 人們應該可以在您的LICENSE文件中找到它，而不是隨機的源代碼。

源代碼控件已經維護了諸如做者身份和日期之類的元數據。 無需在文件自己中添加更詳細，錯誤且過期的相同信息版本。

我不認爲每一個人都須要將任何其餘數據放入其全部源文件中。 您可能有這樣作的特定要求，可是根據定義，這些事情僅適用於您。 它們在「爲全部人推薦的通用標題」中沒有位置。