Comment puis-je faire des attributs d'objet de document Python/Sphinx uniquement déclarés dans init?

j'ai des classes Python avec des attributs d'objet qui ne sont déclarés que dans le cadre de l'exécution du constructeur, comme ceci:

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 j'utilise maintenant help(Foo) ou si je tente de documenter Foo dans Sphinx, les attributs self.basepath et self.availableruns ne sont pas affichés. C'est un problème pour les utilisateurs de notre API.

j'ai essayé de trouver un moyen standard pour s'assurer que ces attributs "dynamiquement déclarés" peuvent être trouvés (et de préférence docstring avais) par l'analyseur, mais pas de chance jusqu'à présent. Toutes les suggestions? Grâce.

8
demandé sur mzjn 2010-10-18 17:25:50

2 réponses

, Vous pouvez définir une variable de classe avec le même nom que la variable d'instance. Cette variable de classe est ensuite suivi 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 une valeur par défaut utile immuable (par exemple None ou le tuple vide), alors vous pouvez sauver un peu de mémoire en ne définissant 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 pourriez vouloir supprimer (par exemple, del foo.availableruns )-- mais je trouve que ce n'est pas un cas très courant.

si vous utilisez sphinx, et avez" autoattribute " ensemble, alors cela devrait être documenté de manière appropriée. Ou, selon le contexte de ce que vous faites, vous pouvez juste utiliser directement la directive Sphinx .. py:attribute:: .

2
répondu Edward Loper 2011-07-18 18:58:48

j'ai essayé de trouver un moyen standard pour s'assurer que ces attributs" dynamiquement déclarés " peuvent être trouvés (et de préférence docstring'D) par l'analyseur, mais aucune chance jusqu'à présent. Toutes les suggestions?

ils ne peuvent jamais être" détectés " par aucun analyseur.

Python a setattr . L'ensemble des attributs n'est jamais "détectable", dans tous les sens du terme.

vous devez absolument décrire dans la docstring.

[à moins que vous ne vouliez faire un tas de méta-programmation pour générer des docstrings à partir de choses que vous avez recueillies à partir de inspect ou quelque chose comme ça. Même dans ce cas, votre "solution" sera incomplète dès que vous commencerez à utiliser setattr .]

class Foo(object):
    """
    :ivar basepath:
    :ivar availableruns:
    """
    def __init__(self, base):
8
répondu S.Lott 2010-10-18 14:20:13