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からの情報を繰り返すコメントを書く必要を回避することです。実際に属性を2回記述しなければならないのは、いらいらしています。少なくともデフォルト値の重複を避けるために、docstringの値の文字列表現を使用することを検討しています。

これはアドホックコミュニティの慣習の重大な違反ですか？大丈夫ですか？もっと良い方法はありますか？たとえば、属性の値とdocstringを含むディクショナリを作成し、その内容をクラスに追加して__dict__、クラス宣言の最後の方にdocstring を追加することができます。これにより、属性の名前と値を2回入力する必要がなくなります。 編集：この最後のアイデアは、実際には不可能であると私は思います。少なくとも、データからクラス全体を動的に構築することなしにはそうではありません。

私はPythonにかなり慣れていないので、コーディングスタイルの詳細を検討しています。したがって、無関係な批評も歓迎します。

混乱を避けるために、Python ではプロパティという用語に特定の意味があります。あなたが話しているのは、クラス属性と呼ばれるものです。それらは常にクラスを通じて実行されるため、クラスのドキュメント文字列内にドキュメント化することは理にかなっています。このようなもの：

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"

それはあなたの例のアプローチよりもはるかに目に優しいと思います。属性値のコピーをドキュメント文字列に表示したい場合は、各属性の説明の横または下に配置します。

Pythonでは、doc文字列はドキュメント化されたオブジェクトの実際のメンバーであり、単なるソースコードの注釈ではないことに注意してください。クラス属性変数はオブジェクト自体ではなくオブジェクトへの参照であるため、独自のdoc文字列を保持する方法がありません。「実際にここにあるもの」ではなく「何をここに置くべきか」を説明するために、参照にdoc文字列を使用することはできると思いますが、それを含むクラスのdoc文字列でそれを行うのは簡単です。

セクションで、ドキュメンテーション文字列の表記：あなたはPEP257を引用docstringとは何か、それが記載されています。

Pythonコードの他の場所にある文字列リテラルも、ドキュメントとして機能する場合があります。これらはPythonバイトコードコンパイラでは認識されず、ランタイムオブジェクト属性としてアクセスできません（つまり、__ doc__に割り当てられていません）。ただし、ソフトウェアツールによって2種類の追加のdocstringが抽出される場合があります。

モジュール、クラス、または__init__メソッドの最上位レベルでの単純な割り当ての直後に発生する文字列リテラルは、「属性docstrings」と呼ばれます。

これについては、PEP 258：Attribute docstringsで詳しく説明しています。上記で説明したように、属性は__doc__を所有できるオブジェクトではないため、help()またはpydocには表示されません。これらのdocstringは、生成されたドキュメントにのみ使用できます。

これらは、ディレクティブautoattributeとともにSphinxで使用されます。

Sphinxは、割り当ての前の行のコメント、または割り当ての後に続く特別なコメント、または自動ドキュメント化される定義の後のdocstringを使用できます。

この効果にプロパティを悪用する可能性があります。プロパティには、getter、setter、deleter、およびdocstringが含まれます。単純に、これは非常に冗長になります：

class C:
    def __init__(self):
        self._x = None

    @property
    def x(self):
        """Docstring goes here."""
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

次に、Cxに属するdocstringがあります。

In [24]: print(C.x.__doc__)
Docstring goes here.

多くの属性に対してこれを行うのは面倒ですが、ヘルパー関数mypropを想定できます。

def myprop(x, doc):
    def getx(self):
        return getattr(self, '_' + x)

    def setx(self, val):
        setattr(self, '_' + x, val)

    def delx(self):
        delattr(self, '_' + x)

    return property(getx, setx, delx, doc)

class C:
    a = myprop("a", "Hi, I'm A!")
    b = myprop("b", "Hi, I'm B!")

In [44]: c = C()

In [46]: c.b = 42

In [47]: c.b
Out[47]: 42

In [49]: print(C.b.__doc__)
Hi, I'm B!

次に、Pythonをインタラクティブに呼び出す helpなります。

Help on class C in module __main__:

class C
 |  Data descriptors defined here:
 |  
 |  a
 |      Hi, I'm A!
 |  
 |  b
 |      Hi, I'm B!

それはあなたが望んでいるものとほぼ同じだと思います。

編集：myprop内部名は問題ではないので、最初の引数を渡す必要をまったく回避できる可能性があることがわかりました。の後続の呼び出しmypropが何らかの形で相互に通信できる場合、それは長くありそうもない内部属性名を自動的に決定できます。これを実装する方法は確かにありますが、それが価値があるかどうかはわかりません。