Question

考虑代码：

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

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

我想将doc-string添加到所有属性中。所以，我可以做一些像（对于文件属性）：

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方法是很繁琐的。实际上，这些方法（如上所示）执行默认作业。

是否有一种简单的方法可以只将doc-string添加到属性中？

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，则可以使用以下语法添加属性doc：

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文档，则可以使用variable docstrings。但如果您希望文档字符串可用于交互式/反思性使用，那么DzinX的答案可能就是这样。

Answer 5

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

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

使用像PyCharm这样的IDE可以帮助您创建属性。在PyCharm中，你只需要开始输入＆＃34; prop＆＃34;弹出窗口将帮助您为只读属性，读/写等创建完整模板

属性docstring

5 个答案: