Qual è il modo giusto per mettere una docstring sulla proprietà Python?

Question

Devo fare alcune docstring, o solo una (e dove dovrei metterla)?

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

vedo che property() accetta un argomento doc.

Answer 1

Scrivere la docstring sul getter, perché 1) è quello che mostra help(MyClass) e 2) è anche come è fatto nello Python docs -- see the x.setter example.

Per quanto riguarda 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 

E poi:

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

>>> 

noti che docstring del setter "Set x" viene ignorata.

Quindi è necessario scrivere la docstring per l'intera proprietà (getter e setter) sulla funzione getter affinché sia ​​visibile. Un esempio di buona docstring proprietà potrebbe essere:

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

Answer 2

Spesso le proprietà non hanno bisogno di una docstring, il loro comportamento dovrebbe essere auto-esplicativo.

Ma se hai davvero bisogno di mettere un docstring lì, mettilo sul getter. Se ne metti uno su entrambi, quello del setter verrà comunque ignorato da pydoc.

Se ad esempio si eseguono alcuni controlli nell'operazione impostata e si genera un'eccezione, allora sarebbe un buon reson inserire una docstring lì per documentare tale comportamento. Ma avere qualcosa come "set/ottiene il valore di spam" come docstring è completamente inutile.