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ソースヘッダーのガイドラインを共有します:-)

Foobarモジュールのすべてのメタデータ。

最初のものはdocstringモジュールのであり、ピーターの回答ですでに説明されています。

モジュール（ソースファイル）を整理するにはどうすればよいですか？（アーカイブ）

各ファイルの最初の行はです#!/usr/bin/env python。これにより、たとえばCGIコンテキストなどでインタプリタを暗黙的に呼び出すスクリプトとしてファイルを実行できます。

次は、説明付きのdocstringです。説明が長い場合、最初の行は、それ自体で意味のある短い要約であり、残りは改行で区切られている必要があります。

importステートメントを含むすべてのコードは、docstringに従う必要があります。そうしないと、docstringはインタープリターによって認識されず、対話型セッション（つまりを介したobj.__doc__）で、または自動ツールでドキュメントを生成するときにアクセスできなくなります。

最初に組み込みモジュールをインポートし、次にサードパーティモジュールをインポートしてから、パスと独自のモジュールを変更します。特に、モジュールのパスと名前への追加は急速に変化する可能性があります。1か所にまとめておくと、モジュールを見つけやすくなります。

次は著者情報です。この情報は、次の形式に従う必要があります。

__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__などのバグ修正、作られた提案を、報告されたが、実際にコードを書いていない人が含まれています。

ここであなたはより多くの情報を持っている、リスト__author__、__authors__、__contact__、__copyright__、__license__、__deprecated__、__date__および__version__認識しメタデータとして。

最小限のファイルヘッダーを強く支持します。

• #!これが実行可能なスクリプトの場合、ハッシュバング（行）
• モジュールdocstring
• 標準的な方法でグループ化されたインポート。例：

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

すなわち。インポートの3つのグループ。それらの間に1つの空白行があります。各グループ内で、インポートはソートされます。最後のグループであるローカルソースからのインポートは、図のように絶対インポートにすることも、明示的な相対インポートにすることもできます。

他のすべては時間と視覚空間の無駄であり、積極的に誤解を招くものです。

法的免責事項またはライセンス情報がある場合、それは別のファイルに入ります。すべてのソースコードファイルに感染する必要はありません。あなたの著作権はこれの一部であるべきです。LICENSEランダムなソースコードではなく、ファイル内で見つけられるようにする必要があります。

著者や日付などのメタデータは、ソース管理によってすでに維持されています。詳細情報が少なく、エラーがあり、古いバージョンの同じ情報をファイル自体に追加する必要はありません。

誰もがすべてのソースファイルに入力する必要がある他のデータがあるとは思いません。あなたにはそうするための特定の要件があるかもしれませんが、そのような事柄は、定義により、あなただけに適用されます。それらは、「すべての人に推奨される一般的なヘッダー」にはありません。

上記の答えは本当に完全ですが、すばやくダーティなヘッダーをコピーして貼り付けたい場合は、これを使用してください：

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

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

なぜこれが良いのか：

• 最初の行は* nixユーザー向けです。ユーザーパスでPythonインタープリターが選択されるため、ユーザーが優先するインタープリターが自動的に選択されます。
• 2つ目はファイルのエンコードです。現在、すべてのファイルにはエンコーディングが関連付けられている必要があります。UTF-8はどこでも機能します。レガシープロジェクトは他のエンコーディングを使用します。
• そして、非常にシンプルなドキュメント。複数行を埋めることができます。

以下も参照してください。 https //www.python.org/dev/peps/pep-0263/

各ファイルにクラスを記述するだけの場合、ドキュメントは必要ありません（クラスドキュメント内にあります）。

非ASCII文字セットを使用している場合は、PEP 263も参照してください。

概要

このPEPは、Pythonソースファイルのエンコーディングを宣言する構文を導入することを提案しています。エンコーディング情報は、Pythonパーサーによって使用され、指定されたエンコーディングを使用してファイルを解釈します。特に、これにより、ソースコード内のUnicodeリテラルの解釈が強化され、Unicode対応のエディターで直接UTF-8などを使用してUnicodeリテラルを書き込むことが可能になります。

問題

Python 2.1では、Unicodeリテラルは、Latin-1ベースのエンコーディング「unicode-escape」を使用してのみ記述できます。これにより、多くのアジア諸国など、Latin-1以外のロケールで生活して作業するPythonユーザーにとって、プログラミング環境はやや不便になります。プログラマーは好みのエンコーディングを使用して8ビット文字列を書き込むことができますが、Unicodeリテラルの「ユニコードエスケープ」エンコーディングにバインドされています。

提案されたソリューション

ファイルの先頭にある特別なコメントを使用してエンコーディングを宣言することにより、ソースファイルごとにPythonソースコードエンコーディングを表示および変更可能にすることを提案します。

Pythonにこのエンコーディング宣言を認識させるには、Pythonソースコードデータの処理に関して、いくつかの概念の変更が必要です。

エンコーディングの定義

他のエンコーディングヒントが指定されていない場合、Pythonはデフォルトで標準エンコーディングとしてASCIIを使用します。

ソースコードエンコーディングを定義するには、次のように、ファイルの1行目または2行目としてソースファイルにマジックコメントを配置する必要があります。

      # coding=<encoding name>

または（人気のあるエディターによって認識されるフォーマットを使用）

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

または

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

...