Каков правильный способ поставить docstring на свойство Python?

Question

Должен ли я сделать несколько docstrings, или только один (и где его положить)?

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

Я вижу, что property() принимает док-аргумент.

Answer 1

Напишите docstring на геттере, потому что 1) вот что такое help(MyClass) показывает, и 2) это также как это делается в Python docs -- see the x.setter example.

Что касается 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 

И потом:

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

>>> 

Обратите внимание, что строка документации сеттер в "Set х" игнорируется.

Значит, вы должны написать docstring для всего свойства (getter и setter) в функции getter, чтобы оно было видимым. Примером хорошего имущества может строку документации быть:

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

Часто свойствам не требуется docstring, их поведение должно быть само собой разумеющимся.

Но если вам действительно нужно поставить docstring, поместите его на геттер. Если вы поместите один на оба, один из сеттера будет проигнорирован pydoc в любом случае.

Если вы, например, делаете некоторые проверки в своей заданной операции и, возможно, выбрасываете исключение, то это будет хороший резонанс, чтобы поставить документацию для документирования этого поведения. Но просто что-то вроде «set/получает значение spam», поскольку docstring абсолютно бесполезен.