如何创建仅在__init__中声明的Python/Sphinx文档对象属性？

Question

我有带有对象属性的Python类,它们只被声明为运行构造函数的一部分,如下所示:

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))

如果我现在使用help(Foo)或尝试Foo在Sphinx中记录,则不显示self.basepath和self.availableruns属性.这对我们API的用户来说是一个问题.

我已经尝试寻找一种标准方法来确保解析器可以找到这些"动态声明"的属性(最好是docstring'd),但到目前为止还没有运气.有什么建议？谢谢.

Answer 1

我已经尝试寻找一种标准方法来确保解析器可以找到这些"动态声明"的属性(最好是docstring'd),但到目前为止还没有运气.有什么建议？

它们永远不会被任何解析器"检测".

Python有setattr.在任何意义上,完整的属性集都不会"可检测".

你绝对必须在docstring中描述它们.

[除非你想做一堆元编程,从你收集的东西inspect或其他东西生成docstrings .即使这样,一旦你开始使用,你的"解决方案"就会完整setattr.]

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

Answer 2

您可以定义一个与实例变量同名的类变量。当您设置该类变量时，该类变量将被实例变量隐藏。例如：

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

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

事实上，如果实例变量具有有用的不可变默认值（例如 None 或空元组），那么您可以通过不设置变量（如果应该具有默认值）来节省一点内存。当然，如果您正在谈论可能想要删除的实例变量（例如，del foo.availableruns），则这种方法将不起作用 - 但我发现这不是很常见的情况。

如果您使用的是 sphinx，并且设置了“自动属性”，那么这应该得到适当的记录。或者，根据您正在执行的操作的上下文，您可以直接使用 Sphinx.. py:attribute::指令。