代码之家 › 专栏 › 技术社区 › c z

关于实例的python文档

python-3.x python

c z · 技术社区 · 8 年前

我想(在我的程序中)提供一些动态创建的对象的文档,但仍然要使用它们的类文档。设置 __doc__ 似乎是一个合适的方法。但是,在这方面,我在python帮助中找不到很多细节,在提供关于实例 ?例如:

class MyClass:
    """
    A description of the class goes here.
    """

a = MyClass()
a.__doc__ = "A description of the object"

print( MyClass.__doc__ )
print( a.__doc__ )

3 回复 | 直到 8 年前

wim 8 年前

__doc__ 记录为的可写属性功能 ,但不适用于用户定义类的实例。 pydoc.help(a) 例如,只考虑 _文件__ 在类型上定义。

其他协议(包括未来的用例)也可以合理地绕过实例dict中定义的特殊属性。见 Special method lookup 数据模型文档的部分,特别是:

对于自定义类,只有在对象类型(而不是在对象实例字典中)上定义特殊方法的隐式调用时,才能保证其正确工作。

因此,根据属性的使用者,您打算做的事情可能不可靠。 避免。

一个安全而简单的替代方法就是为自己的用例使用自己选择的不同属性名,最好不要使用 __dunder__ 语法约定,通常指示为实现和/或stdlib的某些特定用途保留的特殊名称。

abarnert 8 年前

有一些非常明显的技术问题;问题是它们对您的用例是否重要。

下面是一些您的成语对docstring没有帮助的主要用途:

help(a) 类型 帮助(a) 在一个交互式终端中,您将获得 MyClass ,而不是用于 a 。
自动生成的文档 :除非您自己编写文档生成器,否则将无法理解您对 一 值。许多文档生成器做有一些方法可以为模块和类常量指定帮助,但我不知道有什么方法可以识别您的习惯用法。
IDE帮助 :许多IDE不仅会自动完成表达式,还会在工具提示中显示相关的docstring。它们都是静态的,如果没有围绕您的习惯用法设计的一些特殊的case代码(考虑到这是一个不寻常的习惯用法,它们不太可能有),它们几乎肯定会为类而不是对象获取docstring。

以下是一些可能有帮助的地方:

源可读性 作为一个阅读你信息来源的人,我可以从 a.__doc__ = â¦ 就在建筑附近 一 . 同样,我可以很容易地从斯芬克斯对常数的评论中看出同样的意图。
调试 : pdb 对docstring并没有太大的作用,但是一些围绕它的GUI调试程序确实起作用,而且大多数调试程序可能会显示 a.__doc__ .
自定义动态使用docstring :显然,您编写的任何代码 A.“医生__ 如果需要,将获取实例docstring,因此可以用它做任何它想做的事情。 但是,请记住,如果您想要定义自己的“协议”,您应该使用自己的名称,而不是为实现保留的名称。

注意,对于使用docstring的描述符,大多数情况都是这样的:

>>> class C:
...     @property
...     def __doc__(self):
...         return('C doc')
>>> c = C()

如果你打字 c.__doc__ 你会得到 'C doc' 但是 help(c) 将其视为没有docstring的对象。

值得注意的是 help 工作是一一些动态代理库在flysy上生成新类的原因之一是,底层类型的代理 Spam 有一些新的类型 _SpamProxy ,而不是相同的 GenericProxy 用于代理的类型 Ham S和 Eggs ESES。前者允许 help(myspam) 显示动态生成的有关 垃圾邮件 . 但我不知道怎么做 重要的 这是一个原因;通常您已经需要动态类,例如,使特殊的方法查找工作,此时添加动态docstring是免费的。

rsiemens 8 年前

我认为最好通过Doc字符串将其保存在类中,因为它还可以帮助任何开发人员处理代码。但是,如果您正在执行需要此设置的动态操作,那么我看不到任何原因。只是要明白,它增加了一个间接的层次,使事情对其他人不那么清楚。

请记住K.I.S.S.,如适用:)