Are python attribute docstrings commonly used?

Question

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.

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

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?

Answer 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.

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.

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.

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.