python属性docstring常用吗?

On the one hand, we are encouraged to just create fields, and not encrust our python classes with extra accessor functions modelled on other languages.

一方面，我们被鼓励只创建字段，而不是用模仿其他语言的额外访问器函数来封装python类。

On the other hand, the PEP for 'attribute docstrings' was rejected.

另一方面，“属性docstring”的PEP被拒绝。

On the third hand, epydoc and sphinx support them. At the risk of a nonconstructive question, is there a single, clear, common practice for documenting variables in classes?

第三，epydoc和sphinx支持他们。冒着非建设性问题的风险，是否有一个单一的、清晰的、通用的方法来记录类中的变量?

1 个解决方案

#1

I rephrase my comment as an answer since I was asked to do so.

我重新措辞我的评论作为一个回答，因为我被要求这么做。

Generally instance (public) attributes are self-explanatory and their usage by the user does not require documentation. The name of the attribute and the context is enough to make clear what the attribute is and you can add a bit of documentation about how to handle it in the class's documentation.

通常，实例(公共)属性是自解释的，用户使用它们不需要文档。属性的名称和上下文足以说明属性是什么，您可以添加一些关于如何在类文档中处理它的文档。

You may end up in some circumstances in which you would like to provide the user the access of an attribute but the attribute is not self-explanatory enough and/or its handling requires attention(because if not handled correctly it could "blow things up").

在某些情况下，您可能希望向用户提供一个属性的访问权限，但是这个属性并没有足够的自解释性，并且/或它的处理需要注意(因为如果处理不当，它可能会“把事情搞砸”)。

For example you may want to let the user know that an attribute should have a specific "interface" in order to allow it to be used. Or you have to explain a condition that must be met by the attribute.

例如，您可能希望让用户知道属性应该具有特定的“接口”，以便允许使用它。或者您必须解释一个必须由属性满足的条件。

In this cases putting the documentation together with the class's doc is not a good idea, because the class's documentation gets longer and longer and it explain a lot of really specific knowledge.

在这种情况下，将文档与类的doc放在一起并不是一个好主意，因为类的文档会越来越长，它解释了很多非常具体的知识。

The simple and, I think, more elegant solution is to use properties. Properties let you add a docstring to the attribute and give you a way to actually control the access over it, thus allowing to make the class more robust.

简单而优雅的解决方案是使用属性。属性允许向属性添加docstring，并提供一种方法来实际控制对其的访问，从而使类更健壮。

If you have to deal with a lot of attributes then it may be troublesome to write tens of properties, but you can still add them dynamically, for example using a decorator. This works well especially if you just want to add a docstring, using always the same kind of getter/setter.

如果您必须处理大量的属性，那么编写几十个属性可能会很麻烦，但是您仍然可以动态地添加它们，例如使用decorator。如果您只想添加一个docstring，并使用相同类型的getter/setter，那么这种方法将非常有效。

For example you could write:

例如，你可以这样写:

def set_properties(names_to_docs):
    def decorator(cls):
        for name, doc in names_to_docs.items():
            prop = property((lambda self: getattr(self, '_{}'.format(name))),
                            (lambda self, val: setattr(self, '_{}'.format(name), val),
                            doc=doc)
            setattr(cls, name, prop)
        return cls
    return decorator

And use it like this:

像这样使用它:

>>> @set_properties({'a': 'This is a', 'b': 'This is b'})
>>> class Test:
...     def __init__(self):
...         self._a = 1
...         self._b = 2
... 
>>> print(Test.a.__doc__)
This is a
>>> Test().a
1

In a comment Lukas Graf pointed out that you may use Zope.interface to create a class which simply describes the concrete class, which gives you a chance to add docstrings to attributes. This would probably be an other option. I'm not experienced in using Zope.interface so I can't tell exactly what can you do and how, and how it interacts, eventually, with auto-documentation programs.

Lukas Graf在评论中指出，您可以使用zop .interface创建一个类，这个类只描述具体的类，这样您就有机会向属性添加docstring。这可能是另一个选择。我没有使用zop .interface的经验，因此我不能确切地说出你能做什么，如何做，以及最终如何与自动文档程序交互。

#1