What is the right way to put a docstring on Python property?

python properties decorator
Paul Draper picture Paul Draper · Apr 16, 2013 · Viewed 14.3k times · Source

Should I make several docstrings, or just one (and where should I put it)?

@property
def x(self):
     return 0
@x.setter
def x(self, values):
     pass

I see that property() accepts a doc argument.

Answer

Ben Hoyt picture Ben Hoyt · Apr 16, 2013

Write the docstring on the getter, because 1) that's what help(MyClass) shows, and 2) it's also how it's done in the Python docs -- see the x.setter example.

Regarding 1):

class C(object):
    @property
    def x(self):
        """Get x"""
        return getattr(self, '_x', 42)

    @x.setter
    def x(self, value):
        """Set x"""
        self._x = value

And then:

>>> c = C()
>>> help(c)
Help on C in module __main__ object:

class C(__builtin__.object)
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables (if defined)
 |
 |  __weakref__
 |      list of weak references to the object (if defined)
 |
 |  x
 |      Get x

>>>

Note that the setter's docstring "Set x" is ignored.

So you should write the docstring for the entire property (getter and setter) on the getter function for it to be visible. An example of a good property docstring might be:

class Serial(object):
    @property
    def baudrate(self):
        """Get or set the current baudrate. Setting the baudrate to a new value
        will reconfigure the serial port automatically.
        """
        return self._baudrate

    @baudrate.setter
    def baudrate(self, value):
        if self._baudrate != value:
            self._baudrate = value
            self._reconfigure_port()

Related questions

How does the @property decorator work in Python?

I would like to understand how the built-in function property works. What confuses me is that property can also be used as a decorator, but it only takes arguments when used as a built-in function and not when used as …

Read More
How to create abstract properties in python abstract classes

In the following code, I create a base abstract class Base. I want all the classes that inherit from Base to provide the name property, so I made this property an @abstractmethod. Then I created a subclass of Base, called …

Read More
Preferred way of defining properties in Python: property decorator or lambda?

Which is the preferred way of defining class properties in Python and why? Is it Ok to use both in one class? @property def total(self): return self.field_1 + self.field_2 or total = property(lambda self: self.field_1 + self.field_2)

Read More