如何在Python中记录类属性？ [英] How to document class attributes in Python?

问题描述

我正在编写一个轻量级的类，其属性是要公开访问的，只有在特定实例中有时被覆盖。 Python语言中没有规定为类属性创建docstrings或任何类型的属性。记录这些属性的方法是什么？目前我正在做这样的事情：

  class Albatross（object）：
 
 
属性：

 
 flight_speed = 691 
 __doc__ + =
 flight_speed（691）
这样一只鸟可以达到的最大速度

 
 nesting_grounds =Raymond Luxury-Yacht
 __doc__ + = $
 nesting_grounds（Raymond Luxury-Yacht）
这些鸟类聚集在一起的地方复制

 
 def __init __（self，* * keyargs）：
从关键字参数初始化信天翁。
 self .__ dict __。update（keyargs）
  

这将导致类的docstring包含初始标准的docstring部分，以及通过扩展赋值给每个属性添加的行 __ doc __ 。

阿尔斯在 docstring样式指南中似乎没有明确禁止此样式，也没有提到作为选择。这里的优点在于，它提供了一种将属性与其定义一起记录的方法，同时仍然创建可呈现的类docstring，并避免不必编写从docstring重申信息的注释。我还是很懊恼，我必须实际写两个属性;我正在考虑使用docstring中的值的字符串表示，以至少避免重复默认值。

这是一个令人发指的违反特设社区约定？还好吗有没有更好的办法？例如，可以创建一个包含属性的值和文本字典的字典，然后将该内容添加到类 __ dict __ 中并将其转换为类声明的末尾;这将减轻需要键入属性名称和值两次。 编辑：最后一个想法是，实际上并不是这样，至少没有从数据动态构建整个类，这似乎是一个非常糟糕的主意，除非有其他原因。 / p>

我很崭新的python，仍在制定编码风格的细节，所以无关紧要的批评也是受欢迎的。

解决方案

为了避免混淆：术语属性有一个具体含义在python。你所说的是我们所说的 类属性 。由于它们总是通过他们的课程来执行，我发现在类'doc字符串中记录它们是有意义的。这样的东西：

  class Albatross（object）：
飞行速度超过
 
属性：
 flight_speed这样一只鸟可以达到的最大速度
 nesting_grounds这些鸟聚集在一起的场所复制
 
 flight_speed = 691 
 nesting_grounds =Throatwarbler Man Grove
  

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

编辑：

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

I'm writing a lightweight class whose attributes are intended to be publicly accessible, and only sometimes overridden in specific instantiations. There's no provision in the Python language for creating docstrings for class attributes, or any sort of attributes, for that matter. What is the accepted way, should there be one, to document these attributes? Currently I'm doing this sort of thing:

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)

This will result in the class's docstring containing the initial standard docstring section, as well as the lines added for each attribute via augmented assignment to __doc__.

Although this style doesn't seem to be expressly forbidden in the docstring style guidelines, it's also not mentioned as an option. The advantage here is that it provides a way to document attributes alongside their definitions, while still creating a presentable class docstring, and avoiding having to write comments that reiterate the information from the docstring. I'm still kind of annoyed that I have to actually write the attributes twice; I'm considering using the string representations of the values in the docstring to at least avoid duplication of the default values.

Is this a heinous breach of the ad hoc community conventions? Is it okay? Is there a better way? For example, it's possible to create a dictionary containing values and docstrings for the attributes and then add the contents to the class __dict__ and docstring towards the end of the class declaration; this would alleviate the need to type the attribute names and values twice. edit: this last idea is, I think, not actually possible, at least not without dynamically building the entire class from data, which seems like a really bad idea unless there's some other reason to do that.

I'm pretty new to python and still working out the details of coding style, so unrelated critiques are also welcome.

解决方案

To avoid confusion: the term property has a specific meaning in python. What you're talking about is what we call class attributes. Since they are always acted upon through their class, I find that it makes sense to document them within the class' doc string. Something like this:

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"

I think that's a lot easier on the eyes than the approach in your example. If I really wanted a copy of the attribute values to appear in the doc string, I would put them beside or below the description of each attribute.

Edit:

Keep in mind that in Python, doc strings are actual members of the objects they document, not merely source code annotations. Since class attribute variables are not objects themselves but references to objects, they have no way of holding doc strings of their own. I guess you could make a case for doc strings on references, perhaps to describe "what should go here" instead of "what is actually here", but I find it easy enough to do that in the containing class doc string.

这篇关于如何在Python中记录类属性？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！