Comment puis-je faire l'objet document Python / Sphinx uniquement les attributs déclaré dans __init__?

Question

J'ai des classes Python avec les attributs d'objet qui ne mentionnaient dans le cadre de l'exécution du constructeur, comme suit:

class Foo(object):
    def __init__(self, base):
        self.basepath = base

        temp = []
        for run in os.listdir(self.basepath):
            if self.foo(run):
                temp.append(run)
        self.availableruns = tuple(sorted(temp))

Si je l'utilise maintenant soit help(Foo) ou de tenter de documenter Foo dans Sphinx, les attributs de self.basepath et self.availableruns ne sont pas représentés. C'est un problème pour les utilisateurs de notre API.

J'ai essayé de chercher un moyen standard pour faire en sorte que ces « dynamiquement » déclarés attributs peuvent être trouvés (et de préférence docstring'd) par l'analyseur, mais pas de chance jusqu'à présent. Aucune suggestion? Merci.

Answer 1

vous pouvez définir une variable de classe avec le même nom que la variable d'instance. Cette variable de classe sera alors assombrie par la variable d'instance lorsque vous définissez. Par exemple:

class Foo(object):
     #: Doc comment for availableruns
     availableruns = ()

    def __init__(self, base):
        ...
        self.availableruns = tuple(sorted(temp))

En effet, si la variable d'instance a un outil utile immuable valeur par défaut (par exemple Aucun ou tuple vide), alors vous pouvez enregistrer un peu de mémoire en réglant tout simplement pas la variable si devrait avoir sa valeur par défaut . Bien sûr, cette approche ne fonctionnera pas si vous parlez d'une variable d'instance que vous pouvez supprimer (par exemple, del foo.availableruns) -. Mais je trouve ce n'est pas un cas très fréquent

Si vous utilisez sphynx, et ont mis de « autoattribute », alors cela devrait se documenté de façon appropriée. Ou, selon le contexte de ce que vous faites, vous pouvez simplement utiliser directement la directive .. py:attribute:: Sphinx.

Answer 2

  

J'ai essayé de chercher un moyen standard pour faire en sorte que ces « dynamiquement » déclarés attributs peuvent être trouvés (et de préférence docstring'd) par l'analyseur, mais pas de chance jusqu'à présent. Aucune suggestion?

Ils ne peuvent jamais « détecté » par un analyseur syntaxique.

Python a setattr. L'ensemble des attributs est jamais « détectable », dans tous les sens du mot.

Vous devez absolument les décrire dans le docstring.

[Sauf si vous voulez faire un tas de méta-programmation pour générer docstrings de choses que vous recueillies auprès inspect ou quelque chose. Même alors, votre « solution » serait incomplète dès que vous commencer à l'aide setattr.]

class Foo(object):
    """
    :ivar basepath:
    :ivar availableruns:
    """
    def __init__(self, base):