Docstrings for Python descriptors

It makes sense to me that the docstring of a descriptor class and a descriptor instance should be different:

• The docstring of the class should tell you what the class does and how to use it,

• The docstring of the instance should tell you what the attribute is in the class.

Here is an example:

class Number:
    """A number descriptor.
    Args:
        default: The default value of the attribute
        doc (str): The docstring of the attribute
    """
    def init(self, default, doc:str = ''):
        self.default = default
        if doc:
            self.doc = doc
        else:
            self.doc = f'A number with {default} as a default value'
    def setname(self, cls, name):
        self.name = name
        self.privatename = '' + name
    def get(self, instance, instancetype=None):
        if instance is None:
            return self
        return getattr(instance, self.privatename, self.default)
    def set(self, instance, value):
        setattr(instance, self.privatename, value)
class Test:
    """Docstring of Test
    """
    a = Number(0, 'Docstring of a')
    b = Number(1.0, 'Docstring of b')
    c = Number(5, '')

Then,

>>> help(Test) # same as help(Test())

This prints the docstring of the Test class, as well as the docstring of each descriptor instances a, b and c. It is worth noting that c's docstring has been defined programatically, and it displays its default value, which is practical and usefull.

>>> help(Test.a) # resp. Test.b or Test.c

This shows the attribute (descriptor instance) docstring, as expected

>>> help(Number)

This displays the docstring of Number, which is useful to actually use that descriptor

I do not have an explanation for that whitespace interaction you found, however. I suspect help might be explicitely testing to verify that it isn't displaying the class docstring for an instance. That might be due to the fact that by default, the docstring of the instance of a class is the same as that of the class itself.

It makes sense in a way, but if you actually need these two to be the same, you might need to use that whitespace hack you found.

EDIT:

I've found another weird interaction between docstrings and the property decorator, and I thought I'd share:

from operator import attrgetter
class Test:
    a = property(attrgetter('_a'))

Here, calling help(Test) will display the docstring of attrgetter as the docstring of a. I've found this after playing around with the property decorator after @Dunes' comment on this post.