Question

我想在某些动态创建的对象上提供文档（在我的程序中），但仍然可以使用他们的类文档。设置__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__ )

Answer 1

__doc__被记录为 functions 的可写属性，但不是用户定义类的实例。例如，pydoc.help(a)只会考虑在类型上定义的__doc__。

其他协议（包括未来的用例）也可以合理地绕过实例dict中定义的特殊属性。请参阅datamodel文档的Special method lookup部分，具体来说：

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

因此，根据属性的使用者，您打算做什么可能不可靠。的避免。

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

Answer 2

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

以下是您的成语无法帮助的文档字符串的一些主要用途：

help(a) ：在交互式终端中输入help(a)，您将获得MyClass的文档字符串，而不是a的文档字符串。< / LI>
自动生成的文档：除非您编写自己的文档生成器，否则您无法理解您对a值所做的任何特殊操作。许多文档生成器做有一些方法来指定模块和类常量的帮助，但我不知道任何会识别你的习语。
IDE帮助：许多IDE不仅会自动完成表达式，还会在工具提示中显示相关的文档字符串。它们都是静态地执行此操作，并且没有围绕您的习惯设计的特殊情况代码（由于它是一种不寻常的习惯用语，它们不太可能具有这些代码），它们几乎肯定会为类而不是对象获取文档字符串

以下是一些可能有用的地方：

来源可读性：作为阅读您的来源的人，我可以在a.__doc__ = …附近的a右侧告诉您的意图。然后，我可以通过Sphinx对常量的评论轻松地说出同样的意图。
调试：pdb对于文档字符串并没有太大帮助，但是一些GUI调试器会在其中进行，并且大多数可能会显示a.__doc__。
自定义动态使用文档字符串：显然，您编写的任何与a.__doc__有关的代码都会在需要时获取实例文档字符串，因此可以执行任何操作想要它。 但是，请记住，如果要定义自己的“协议”，则应使用自己的名称，而不是为实现保留的名称。

请注意，对于使用docstring的描述符，大多数情况都是如此：

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

如果您输入c.__doc__，则会获得'C doc'，但help(c)会将其视为没有文档字符串的对象。

值得注意的是，让help工作一个的原因是一些动态代理库动态生成新类 - 即底层类型Spam的代理有一些新类型，例如_SpamProxy，而不是用于代理GenericProxy和Ham的相同Eggs类型。前者允许help(myspam)显示有关Spam的动态生成信息。但我不知道重要是什么原因;通常你已经需要动态类，例如，进行特殊的方法查找工作，此时添加动态文档字符串是免费的。

Answer 3

我认为首选通过您的文档字符串将其保留在类下，因为它还可以帮助任何处理代码的开发人员。但是，如果你正在做一些需要这种设置的动态，那么我就没有看到任何理由。只要明白它增加了一个间接层，使其他人不那么清楚。

记得K.I.S.S.适用时：）

关于实例的Python doc文档

3 个答案:

关于实例的Python __doc__文档

3 个答案:

关于实例的Python doc文档