web-dev-qa-db-fra.com

Quelle est la bonne façon de mettre une docstring sur Python?

Dois-je faire plusieurs docstrings, ou un seul (et où dois-je le mettre)?

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

Je vois que property() accepte un argument doc.

pythonpropertiesdecorator
44
Paul Draper

Écrivez la docstring sur le getter, car 1) c'est ce que help(MyClass) montre, et 2) c'est aussi comme ça que ça se passe dans les documents Python - voir l'exemple x.setter .

Concernant 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

Puis:

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

>>>

Notez que la docstring du setter "Set x" est ignorée.

Vous devez donc écrire la docstring pour la propriété entière (getter et setter) sur la fonction getter pour qu'elle soit visible. Un exemple d'une bonne docstring de propriété pourrait être:

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()
44
Ben Hoyt