web-dev-qa-db-ja.com

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

pythonheadercomments
446
Ashwin Nanjappa

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

最初のものはモジュールのdocstringです、それはすでに Peterの答え で説明されています。

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

各ファイルの最初の行は#!/usr/bin/env pythonです。 これにより、ファイルをインタプリタを暗黙的に呼び出すスクリプトとして実行することが可能になります。 CGIの文脈で。

次は説明付きの文字列です。説明が長い場合、最初の行はそれ自体が意味をなす短い要約で、残りは改行で区切ります。

import文を含むすべてのコードはdocstringに従うべきです。 そうでなければ、docstringはインタプリタによって認識されず、対話型セッションで（すなわち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__ = "[email protected]"
__status__ = "Production"

ステータスは通常、 "Prototype"、 "Development"、または "Production"のいずれかになります。 __maintainer__はバグを修正しインポートされたら改善する人です。 __credits__は__author__とは異なります。__credits__はバグ修正を報告したり、提案をしたりしたが実際にはコードを書かなかった人々を含みます。

ここ__author__、__authors__、__contact__、__copyright__、__license__、__deprecated__、__date__および__version__をメタデータとして認識した上で、さらに詳しい情報があります。

509
Esteban Küber

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

  • これが実行可能スクリプトの場合はhashbang（#!行）
  • モジュールのdocstring
  • 標準的な方法でグループ化されたインポート。例：
  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule

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

他のすべては時間の無駄、視覚的なスペースであり、そして積極的に誤解を招くものです。

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

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

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

151
Jonathan Hartley

上記の答えは完全に完成していますが、早くて汚いヘッダをコピー＆ペーストしたい場合は、これを使用してください。

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

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

なぜこれが良いものです：

  • 1行目は* nixユーザー用です。ユーザーパスでPythonインタプリタが選択されるため、ユーザーが選択したインタプリタが自動的に選択されます。
  • 二つ目はファイルのエンコーディングです。今日では、すべてのファイルはエンコードされている必要があります。 UTF-8はどこでも動作します。従来のプロジェクトだけが他のエンコーディングを使用します。
  • そして非常に単純な文書です。それは複数の行を埋めることができます。

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

各ファイルにクラスを書くだけなら、ドキュメンテーションは必要ありません（クラスdocの中に入ります）。

24
neves

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

抽象

このPEPはPythonソースファイルのエンコーディングを宣言する構文を導入することを提案します。エンコーディング情報は、Pythonパーサーによって、与えられたエンコーディングを使ってファイルを解釈するために使われます。最も注目に値するのは、これがソースコード内のUnicodeリテラルの解釈を向上させ、例えば、 Unicode対応のエディタで直接UTF-8。

問題

Python 2.1では、UnicodeリテラルはLatin-1ベースのエンコーディング "unicode-escape"を使ってしか書くことができません。これは、プログラミング環境を、多くのアジア諸国のようなラテン語1以外のロケールで生活し仕事をしているPythonユーザーにとってはやや不親切なものにしています。プログラマは好みのエンコーディングを使って8ビット文字列を書くことができますが、Unicodeリテラルの場合は "unicode-escape"エンコーディングに束縛されます。

提案された解決策

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

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

エンコーディングの定義

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

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

      # coding=<encoding name>

または（一般的な編集者によって認識されている形式を使用して）

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

または

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

...

21
John La Rooy