3

考虑代码：

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

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

4

5 回答 5

2

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

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 属性。

于 2012-02-15T15:21:24.293 回答
1

This is a fixed version of DzinX's DocProperty class:

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)

Usage:

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

Note that using this will make your code less efficient though -- every attribute access becomes more expensive. But I guess that in some contexts the ability to add docs might be worth it (esp if efficiency isn't a concern in your context).

于 2012-02-15T15:52:34.933 回答
0

如果您使用epydoc 之类的工具（生成描述代码 API 的网页）生成 API 文档，则可以使用变量 docstrings。但是，如果您希望文档字符串可用于交互/反射使用，那么 DzinX 的答案可能是要走的路。

于 2012-02-15T15:25:01.393 回答
0

不确定您是否正在搜索它，但如果您将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
于 2012-02-15T15:23:17.927 回答
0

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

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

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

于 2017-05-05T03:59:51.387 回答