[解決済み] Pythonでクラス属性を文書化するには？

質問

私は、その属性が一般にアクセス可能で、特定のインスタンスで時々上書きされることを意図した軽量なクラスを書いています。 Python 言語には、クラスの属性、またはそれに関してはどのような種類の属性でも、docstring を作成するための規定はありません。 これらの属性を文書化するために、期待され、サポートされる方法は何でしょうか？ 現在、私はこのようなことを行っています。

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
    """

    flight_speed = 691
    __doc__ += """
        flight_speed (691)
          The maximum speed that such a bird can attain.
    """

    nesting_grounds = "Raymond Luxury-Yacht"
    __doc__ += """
        nesting_grounds ("Raymond Luxury-Yacht")
          The locale where these birds congregate to reproduce.
    """

    def __init__(self, **keyargs):
        """Initialize the Albatross from the keyword arguments."""
        self.__dict__.update(keyargs)

この結果、クラスの docstring は、最初の標準的な docstring セクションと、各属性のために拡張された代入によって追加された行を含む __doc__ .

ではこのスタイルは明示的に禁止されているわけではないようですが docstring スタイル・ガイドライン では明示的に禁止されているわけではありませんが、選択肢として言及されているわけでもありません。 この方法の利点は、属性をその定義と一緒に文書化する方法を提供する一方で、見やすいクラスのdocstringを作成し、docstringからの情報を繰り返すコメントを書く必要がないことです。 私は、少なくともデフォルト値の重複を避けるために、docstringの値の文字列表現を使用することを検討しています。

これはアドホックなコミュニティの規約に対する極悪非道な違反でしょうか？ 大丈夫でしょうか。 もっと良い方法はないでしょうか。 たとえば、属性の値と docstring を含む辞書を作成し、その内容をクラス __dict__ と docstring をクラス宣言の最後に追加することができます。こうすることで、属性名と値を二度入力する必要性を軽減できます。 編集 少なくとも、データからクラス全体を動的に構築することなしには不可能だと思います。

私はpythonにかなり新しく、コーディングスタイルの詳細をまだ解明していないので、関係のない批評も歓迎します。

どのように解決するのですか？

混乱を避けるために: 用語 プロパティ には 特定の意味 を意味します。 あなたが言っているのは、私たちが呼ぶところの クラス属性 . これらの属性は常にそのクラスを通して操作されるので、クラスのdoc文字列の中でそれらを文書化することは理にかなっていると私は思います。 このようなものです。

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
        flight_speed     The maximum speed that such a bird can attain.
        nesting_grounds  The locale where these birds congregate to reproduce.
    """
    flight_speed = 691
    nesting_grounds = "Throatwarbler Man Grove"

あなたの例のアプローチよりも、ずっと目に優しいと思います。 もし私が本当に属性値のコピーをdoc文字列に表示させたいのであれば、各属性の説明の横か下に配置するでしょう。

Pythonでは、doc文字列は単にソースコードの注釈ではなく、ドキュメント化されたオブジェクトの実際のメンバーであることに留意してください。クラス属性変数はオブジェクトそのものではなく、オブジェクトへの参照であるため、彼ら自身のdoc文字列を保持する方法がないのです。おそらく、quot;何が実際にここにあるかquot;の代わりに、quot;何がここに入るべきかquot;を記述するために、参照にdocストリングのケースを作ることができると思いますが、私はそれを含むクラスのdoc文字列で十分に簡単に行うことができると思います。