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

【问题标题】：How can I make Python/Sphinx document object attributes only declared in __init__?如何使 Python/Sphinx 文档对象属性仅在 __init__ 中声明？
【发布时间】：2010-10-18 13:25:50
【问题描述】：

我有带有对象属性的 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) 或尝试在 Sphinx 中记录 Foo，则不会显示 self.basepath 和 self.availableruns 属性。这对我们 API 的用户来说是个问题。

我尝试寻找一种标准方法来确保解析器可以找到（最好是文档字符串）这些“动态声明的”属性，但到目前为止还没有运气。有什么建议？谢谢。

【问题讨论】：

标签： python attributes python-sphinx docstring

【解决方案1】：

我尝试寻找一种标准方法来确保解析器可以找到（最好是文档字符串）这些“动态声明的”属性，但到目前为止还没有运气。有什么建议？

它们永远不会被任何解析器“检测到”。

Python 有setattr。从任何意义上说，完整的属性集永远是“不可检测的”。

您绝对必须在文档字符串中描述它们。

[除非你想做一堆元编程来从你从inspect 或其他东西收集到的东西生成文档字符串。即便如此，一旦您开始使用setattr，您的“解决方案”将是不完整的。]

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

【讨论】：

谢谢。是的，我很欣赏这些属性通常是不可计算的，只是不确定是否有启发式方法可以通过例如简单/标准的方式来获取其中的一些声明。源扫描而不是类对象检查。或者通过修改代码将这些属性声明为属性，以便 Sphinx/help 可以“找到”它们。但无论如何，指向 Sphinx 语法的指针用于声明它们的存在以用于文档目的就可以了：干杯！
"或者通过修改代码将这些属性声明为属性"？ “声明”不是 Python 概念。如果您要自动记录成员，则为您的属性使用属性方法函数将起作用。这似乎比简单地将它们记录在文档字符串中更多工作。
但这意味着它们与其他方法在平等的基础上被记录，我认为这显着提高了文档的质量。如果它不会影响性能或使代码难以理解，我准备为此做更多的工作。这就是最初问题的重点：我确信我可以找到一种方法来做到这一点，但我想知道是否有一种（事实上的）标准方法可以最大限度地减少不利因素。
“如果有（事实上的）标准方法”。是的。 :ivar name: 是标准方法。创建一堆属性根本不会“显着提高文档的质量”。它不会以任何方式改进:ivar name:。而且您将做大量工作以获得更好的文档。
@Joe White：由于self. 引用，只有从代码检查中显而易见的子集。创建无法检测到的属性真的很容易。使用 __getattr__ 或 __getattribute__ 将阻止 IDE 检测。

【解决方案2】：

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

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

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

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

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

【讨论】：