如何在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)

这将导致该类的docstring包含初始的标准docstring部分，以及通过对的扩展分配为每个属性添加的行__doc__。

尽管在文档字符串样式指南中似乎并未明确禁止使用这种样式，但也没有作为一种选择提及它。这样做的好处是，它提供了一种在定义的同时记录属性的方法，同时仍然创建了一个可显示的类docstring，并且避免了编写注释以重申该docstring中的信息。我仍然对必须两次写入属性感到不安。我正在考虑使用文档字符串中值的字符串表示形式来至少避免重复默认值。

这是对特设社区惯例的严重违反吗？可以吗
有没有更好的办法？例如，可以创建一个包含属性值和文档字符串的字典，然后__dict__在类声明的末尾将内容添加到该类和文档字符串中。这样可以减少两次键入属性名称和值的需要。
编辑 ：我认为，最后一个想法实际上是不可能的，至少没有没有根据数据动态构建整个类的想法，除非有其他原因，否则这似乎是一个坏主意。

我是python的新手，仍然在研究编码风格的细节，因此也欢迎无关的批评。

Answer 1

为避免混淆：术语 property
在python中具有特定含义。您所说的是所谓的
类属性
。由于始终在类中对它们进行操作，因此我发现将它们记录在类的文档字符串中是有意义的。像这样：

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"

我认为这比示例中的方法容易得多。如果我确实希望属性值的副本出现在doc字符串中，则可以将它们放在每个属性的描述的旁边或下方。

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