如何在 Python 中记录类属性？

Question

我正在编写一个轻量级类，其属性旨在公开访问，并且仅在特定实例化中有时会被覆盖。就此而言，Python 语言中没有为类属性或任何类型的属性创建文档字符串的规定。记录这些属性的预期和支持方式是什么？目前我正在做这样的事情：

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
    """

    flight_speed = 691
    __doc__ += """
        flight_speed (691)
          The maximum speed that such a bird can attain.
    """

    nesting_grounds = "Raymond Luxury-Yacht"
    __doc__ += """
        nesting_grounds ("Raymond Luxury-Yacht")
          The locale where these birds congregate to reproduce.
    """

    def __init__(self, **keyargs):
        """Initialize the Albatross from the keyword arguments."""
        self.__dict__.update(keyargs)

这将导致类的文档字符串包含初始标准文档字符串部分，以及通过对__doc__ 的扩充分配为每个属性添加的行。

虽然docstring style guidelines 中似乎没有明确禁止这种风格，但也没有提到它作为一个选项。这里的优点是它提供了一种在属性定义旁边记录属性的方法，同时仍然创建一个可展示的类文档字符串，并避免编写重复来自文档字符串的信息的 cmets。我仍然有点恼火，我实际上必须写两次属性；我正在考虑使用 docstring 中值的字符串表示形式，至少可以避免默认值的重复。

这是否严重违反了临时社区公约？没事吧？有没有更好的办法？例如，可以创建一个包含属性值和文档字符串的字典，然后将内容添加到类__dict__ 和类声明末尾的文档字符串；这将减少两次键入属性名称和值的需要。 编辑：我认为最后一个想法实际上是不可能的，至少在没有从数据动态构建整个类的情况下是不可能的，这似乎是一个非常糟糕的想法，除非有其他理由这样做。

我对python还很陌生，还在研究编码风格的细节，所以也欢迎无关的批评。

Answer 1

为避免混淆：property 一词在 python 中有一个specific meaning。你所说的就是我们所说的class attributes。因为他们总是通过他们的班级被执行，我发现在班级的文档字符串中记录他们是有意义的。像这样的：

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
        flight_speed     The maximum speed that such a bird can attain.
        nesting_grounds  The locale where these birds congregate to reproduce.
    """
    flight_speed = 691
    nesting_grounds = "Throatwarbler Man Grove"

我认为这比您示例中的方法容易得多。如果我真的想要一个属性值的副本出现在文档字符串中，我会将它们放在每个属性的描述旁边或下方。

请记住，在 Python 中，文档字符串是它们记录的对象的实际成员，而不仅仅是源代码注释。由于类属性变量本身不是对象，而是对对象的引用，因此它们无法保存自己的文档字符串。我想您可以为引用中的文档字符串提供一个案例，也许可以描述“这里应该有什么”而不是“这里实际有什么”，但我发现在包含的类文档字符串中这样做很容易。

Answer 2

您引用了 PEP257: Docstring Conventions，在 What is a docstring 部分中指出：

Python 代码中其他地方出现的字符串文字也可以作为文档。它们不被 Python 字节码编译器识别，也不能作为运行时对象属性访问（即未分配给 __doc__），但软件工具可以提取两种类型的额外文档字符串：

在模块、类或 __init__ 方法的顶层简单赋值之后立即出现的字符串文字称为“属性文档字符串”。

这在 PEP 258: Attribute docstrings 中有更详细的解释。 如上所述ʇsәɹoɈ。 属性不是可以拥有 __doc__ 的对象，因此它们不会出现在 help() 或 pydoc 中。这些文档字符串只能用于生成的文档。

它们在 Sphinx 中与directive autoattribute 一起使用

Sphinx 可以在赋值之前的一行上使用 cmets，也可以在赋值之后的特殊注释或定义之后的文档字符串中使用 cmets，这将被自动记录。

Answer 3

你可以滥用属性来达到这个效果。属性包含一个getter、一个setter、一个deleter、和一个docstring。天真地，这会变得非常冗长：

class C:
    def __init__(self):
        self._x = None

    @property
    def x(self):
        """Docstring goes here."""
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

那么你将拥有一个属于 C.x 的文档字符串：

In [24]: print(C.x.__doc__)
Docstring goes here.

对许多属性执行此操作很麻烦，但您可以设想一个辅助函数 myprop：

def myprop(x, doc):
    def getx(self):
        return getattr(self, '_' + x)

    def setx(self, val):
        setattr(self, '_' + x, val)

    def delx(self):
        delattr(self, '_' + x)

    return property(getx, setx, delx, doc)

class C:
    a = myprop("a", "Hi, I'm A!")
    b = myprop("b", "Hi, I'm B!")

In [44]: c = C()

In [46]: c.b = 42

In [47]: c.b
Out[47]: 42

In [49]: print(C.b.__doc__)
Hi, I'm B!

然后，调用 Pythons 交互式 help 将给出：

Help on class C in module __main__:

class C
 |  Data descriptors defined here:
 |  
 |  a
 |      Hi, I'm A!
 |  
 |  b
 |      Hi, I'm B!

我认为这应该是你所追求的。

编辑：我现在意识到我们或许可以完全避免将第一个参数传递给myprop，因为内部名称并不重要。如果myprop 的后续调用可以以某种方式相互通信，它可以自动决定一个长且不太可能的内部属性名称。我确信有办法实现这一点，但我不确定它们是否值得。

Answer 4

其他答案非常已过时。 PEP-224（在 Python 2.1 中可用！）描述了如何将文档字符串用于属性。奇怪的是，它们出现在 属性之后。

class C:
    "class C doc-string"

    a = 1
    "attribute C.a doc-string (1)"

    b = 2
    "attribute C.b doc-string (2)"

它也适用于这样的类型注释：

class C:
    "class C doc-string"

    a: int
    "attribute C.a doc-string (1)"

    b: str
    "attribute C.b doc-string (2)"

VSCode 支持显示这些。