属性文档字符串

Question

考虑代码：

class MyClass(object):
  '''
  Keep track of file and its path on disk
  '''

  def __init__(self):
    self.file = None
    self.path = None

我想将文档字符串添加到所有属性。所以，我可以做类似的事情（对于文件属性）：

class MyClass(object):
  ...

  @property
  def file(self):
    '''
    this is a doc-string for file property
    '''

    return self._file

  @file.setter
  def file(self, value):
    self._file = value

  @file.deleter
  def file(self):
    del self._file

但是，为每个属性编写 getter、setter 和 deleter 方法是很乏味的。事实上，这些方法（如上所示）执行默认工作。

有没有一种简单的方法可以仅将文档字符串添加到属性中？

Answer 1

好吧，您始终可以创建自己的描述符，该描述符允许记录并以标准方式实现其他操作：

class DocProperty(object):

    def __init__(self, doc=None):
        self._values = {}
        self.__doc__ = doc

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return self._values[obj]

    def __set__(self, obj, value):
        self._values[obj] = value

    def __delete__(self, obj):
        del self._values[obj]

然后您可以像这样使用它：

class SomeClass(object):

    p1 = DocProperty('some docs')

print SomeClass.p1.__doc__
# some docs
c = SomeClass()
c.p1 = 2
print c.p1
# 2
del c.p1

不过，就我个人而言，我认为这是矫枉过正。如果代码需要它，请在构造函数中使用注释。所有自动文档生成器还支持以某种方式注释简单的 Python 属性。

Answer 2

这是 DzinX 的 DocProperty 类的固定版本：

class DocProperty(object):

    def __init__(self, name, doc):
        self._name = '_'+name
        self.__doc__ = doc

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return getattr(obj, self._name)

    def __set__(self, obj, value):
        setattr(obj, self._name, value)

    def __delete__(self, obj):
        delattr(obj, self._name)

用法：

class SomeClass(object):
    p1 = DocProperty('p1', 'some docs')

请注意，使用它会使您的代码效率降低 - 每个属性访问都会变得更加昂贵。但我想在某些情况下，添加文档的能力可能是值得的（特别是如果您的情况下不关心效率的话）。

Answer 3

不确定您是否正在搜索该内容，但如果您正在使用 Sphinx 作为您的文档系统，您可以使用以下语法放置属性文档：

class MyClass(object):
  '''
  Keep track of file and its path on disk
  '''

  def __init__(self):
    #: this is doc for file
    self.file = None

    #: this is the documentation for path
    #: on multiple line too.
    self.path = None

Answer 4

如果您使用 epydoc 等工具生成 API 文档（它会生成一个描述代码 API 的网页） ，那么您可以使用变量文档字符串。但如果您希望文档字符串可用于交互/反射使用，那么 DzinX 的答案可能是正确的选择。

Answer 5

您是指属性（在问题开头的 init 中定义）还是属性，如所述？

对于属性，只需将文档字符串放入 getter 中即可。您可以像 my_class_instance.__class__.file.__doc__ 一样访问它。

使用 PyCharm 等 IDE 可以帮助您创建属性。在 PyCharm 中，您只需开始输入“prop”，弹出窗口将帮助您创建只读属性、读/写等的完整模板。