Jaki jest właściwy sposób umieszczenia docstringu w usłudze Python?

Question

Czy powinienem wykonać kilka docstruktów, czy tylko jeden (i gdzie powinienem go umieścić)?

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

Widzę, że property() przyjmuje argument doc.

Answer 1

Napisz docstring na geterze, ponieważ 1) to pokazuje help(MyClass), a 2) to także, jak to się robi w Python docs -- see the x.setter example.

Odnośnie 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 

A potem:

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

>>> 

Zauważ, że docstring ustawiająca za "zbiór X" jest ignorowany.

Powinieneś napisać docstring do całej właściwości (getter i setter) na funkcji gettera, aby była widoczna. Przykładem dobrej docstring nieruchomości może być:

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

Często właściwości nie wymagają docstrowania, ich zachowanie powinno być zrozumiałe.

Ale jeśli naprawdę potrzebujesz umieścić docstring, umieść go na geterze. Jeśli umieścisz jedną na obu, ta z setera zostanie zignorowana przez pydoc.

Jeśli na przykład przeprowadzisz pewne kontrole w ustawionej operacji i może rzucisz wyjątek, to byłoby to dobrym pomysłem na umieszczenie dokumentu docs w celu udokumentowania tego zachowania. Ale posiadanie czegoś w stylu "ustaw/otrzymuje wartość spam" jako docstring jest całkowicie bezużyteczne.