Comment documenter les attributs de classe en Python? [fermé]

J'écris une classe légère dont les attributs sont destinés à être accessibles au public, et parfois seulement remplacés dans des instanciations spécifiques. Il n'y a aucune disposition dans le langage Python pour créer des docstrings pour les attributs de classe, ou toute sorte d'attributs, d'ailleurs. Quelle est la manière attendue et prise en charge, devrait-il y en avoir une, pour documenter ces attributs? Actuellement, je fais ce genre de chose:

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)

Cela se traduira par la docstring de la classe contenant la section docstring standard initiale, ainsi que les lignes ajoutées pour chaque attribut via une affectation augmentée à __doc__.

Bien que ce style ne semble pas être expressément interdit dans les directives de style docstring , il n'est pas non plus mentionné comme une option. L'avantage ici est qu'il fournit un moyen de documenter les attributs avec leurs définitions, tout en créant une docstring de classe présentable, et en évitant d'avoir à écrire des commentaires qui réitèrent les informations de la docstring. Je suis toujours un peu ennuyé de devoir écrire les attributs deux fois; J'envisage d'utiliser les représentations sous forme de chaîne des valeurs dans la docstring pour au moins éviter la duplication des valeurs par défaut.

Est-ce une violation odieuse des conventions communautaires ad hoc? Ça va? Y a-t-il un meilleur moyen? Par exemple, il est possible de créer un dictionnaire contenant des valeurs et des docstrings pour les attributs, puis d'ajouter le contenu à la classe __dict__et à la docstring vers la fin de la déclaration de classe; cela éviterait de devoir taper deux fois les noms et valeurs d'attribut. edit : cette dernière idée n'est, je pense, pas réellement possible, du moins pas sans construire dynamiquement toute la classe à partir de données, ce qui semble être une très mauvaise idée à moins qu'il n'y ait une autre raison de le faire.

Je suis assez nouveau en python et je travaille toujours sur les détails du style de codage, donc les critiques sans rapport sont également les bienvenues.

Pour éviter toute confusion: le terme propriété a une signification spécifique en python. Ce dont vous parlez, c'est ce que nous appelons les attributs de classe . Puisqu'ils sont toujours utilisés à travers leur classe, je trouve qu'il est logique de les documenter dans la doc string de la classe. Quelque chose comme ça:

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"

Je pense que c'est beaucoup plus facile pour les yeux que l'approche de votre exemple. Si je voulais vraiment qu'une copie des valeurs d'attribut apparaisse dans la chaîne doc, je les placerais à côté ou en dessous de la description de chaque attribut.

Gardez à l'esprit qu'en Python, les chaînes doc sont des membres réels des objets qu'elles documentent, pas simplement des annotations de code source. Puisque les variables d'attribut de classe ne sont pas des objets eux-mêmes mais des références à des objets, elles n'ont aucun moyen de contenir leurs propres chaînes de documents. Je suppose que vous pourriez faire un cas pour les chaînes doc sur les références, peut-être pour décrire "ce qui devrait aller ici" au lieu de "ce qui est réellement ici", mais je trouve assez facile de le faire dans la chaîne doc de la classe contenant.

Vous citez le PEP257: Docstring Conventions, dans la section Qu'est - ce qu'une docstring, il est indiqué:

Les chaînes littérales apparaissant ailleurs dans le code Python peuvent également servir de documentation. Ils ne sont pas reconnus par le compilateur bytecode Python et ne sont pas accessibles en tant qu'attributs d'objet d'exécution (c'est-à-dire non assignés à __doc__), mais deux types de docstrings supplémentaires peuvent être extraits par des outils logiciels:

Les littéraux de chaîne apparaissant immédiatement après une simple affectation au niveau supérieur d'un module, d'une classe ou d'une méthode __init__ sont appelés "docstrings d'attribut".

Et ceci est expliqué plus en détail dans PEP 258: docstrings d'attribut. Comme expliqué ci-dessus ʇsәɹoɈ. un attribut n'est pas un objet qui peut posséder un __doc__ donc il n'apparaîtra pas dans help()ou pydoc. Ces docstrings ne peuvent être utilisées que pour la documentation générée.

Ils sont utilisés dans Sphinx avec la directive autoattribute

Sphinx peut utiliser des commentaires sur une ligne avant une affectation ou un commentaire spécial après une affectation ou une docstring après la définition qui sera autodocumentée.

Vous pourriez abuser des propriétés à cet effet. Les propriétés contiennent un getter, un setter, un deleter et une docstring . Naïvement, cela deviendrait très verbeux:

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

Ensuite, vous aurez une docstring appartenant à Cx:

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

Faire cela pour de nombreux attributs est fastidieux, mais vous pouvez envisager une fonction d'assistance 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!

Ensuite, appeler Pythons interactif helpdonnera:

Help on class C in module __main__:

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

ce qui, je pense, devrait être à peu près ce que vous recherchez.

Edit : Je me rends compte maintenant que nous pouvons peut-être éviter de devoir passer le premier argument myprop, car le nom interne n'a pas d'importance. Si les appels ultérieurs de myproppeuvent d'une manière ou d'une autre communiquer entre eux, il pourrait automatiquement décider d'un nom d'attribut interne long et improbable. Je suis sûr qu'il existe des moyens de mettre en œuvre cela, mais je ne suis pas sûr qu'ils en valent la peine.