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

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 在狮身人面 self.basepath 和 self.availableruns 属性未显示。对于我们的API用户来说，这是一个问题。

我尝试搜索一种标准方法，以确保解析器可以找到这些“动态声明”属性（并且最好是DocString'D），但到目前为止尚无运气。有什么建议么？谢谢。

Answer 1

您可以定义具有与实例变量相同名称的类变量。然后，当您设置该类变量时，该类变量将被实例变量遮蔽。例如：

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

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

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

如果您使用的是狮身人面像，并且具有“自动划分”设置，则应适当记录。或者，根据您所做的事情的背景，您可以直接使用狮身人面像 .. py:attribute:: 指示。

Answer 2

我尝试搜索一种标准方法，以确保解析器可以找到这些“动态声明”属性（并且最好是DocString'D），但到目前为止尚无运气。有什么建议么？

任何解析器都无法“检测到”它们。

Python有 setattr. 。从任何意义上讲，完整的属性集绝不能“可检测”。

您绝对必须在Docstring中描述它们。

除非您想进行一堆元编程以从您收集的东西中生成docstrings inspect 或者其他的东西。即使那样，一旦您开始使用，您的“解决方案”还是不完整的 setattr.]

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