¿Cuál es la forma correcta de poner una cadena de documentos en la propiedad de Python?

¿Debo hacer varias cadenas de documentación, o solo una (y dónde debería colocarla)?

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

Veo que la property() acepta un argumento doc.

Escriba la cadena de documentos en el captador, porque 1) eso es lo help(MyClass) muestra la help(MyClass) , y 2) también es cómo se hace en los documentos de Python; consulte el ejemplo de x.setter .

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

Y entonces:

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

Tenga en cuenta que la cadena de documentación del definidor “Set x” se ignora.

Por lo tanto, debe escribir la cadena de documentación para toda la propiedad (getter y setter) en la función getter para que sea visible. Un ejemplo de una buena cadena de documentos de propiedad podría ser:

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