在 python 2 中为类设置 __doc__答案

【问题标题】：Set __doc__ for class in python 2在 python 2 中为类设置 __doc__
【发布时间】：2015-01-08 21:33:56
【问题描述】：

我正在以编程方式制作大量（接近 100 个）类，我希望能够设置类的文档字符串。每个类文档字符串都有相同的基本结构，需要填写特定的部分。我想定义一个模板字符串，然后在创建类时用类特定的参数填充它。

作为我所追求的人为示例，请考虑以下内容

class_docstr = """
This is the docstring for the {name} class.
"""


class A(object):

    def __init__(self):
        pass


class B(object):

    def __init__(self):
        pass


class C(object):

    def __init__(self):
        pass

我想做的是以某种方式设置A.__doc__ = class_docstr.format(name="A")，这样当我调用help(A) 时，我会看到这样的内容：

class A(__builtin__.object)
 |  This is the docstring for the A class.

我相信我可能需要使用元类来执行此操作，但我不确定如何。

【问题讨论】：

您可以在元类的__new__ 方法中更新类字典的__doc__ 键，注意这必须在实际创建类之前完成。
这有点违背了文档字符串的目的，因为浏览类定义不会给您提供查看文档的明显方式。是否有理由需要以这种方式生成您的文档字符串？
我希望文档字符串更多地用于在 python 或 ipython repl 上进行交互式探索，并通过 sphinx 自动生成 html 文档，而不是记录源代码。
@AshwiniChaudhary -- 你为什么说它需要在创建类之前发生？ doc 属性应该是可写的...
@mgilson 对于类型的类是不可能的。但是嗯……元类使之成为可能。 ideone.com/UPKHq8

标签： python metaclass docstring

【解决方案1】：

您可以通过分配给类定义中的__doc__ 类变量来设置文档字符串：

class A(object):
    __doc__ = class_docstr.format(name="A")

    # whatever else

即使在创建类之后分配给A.__doc__ 之后也不起作用，这仍然有效。

【讨论】：

很好/简单的答案。非常适合我的应用程序

【解决方案2】：

如果你真的想在这里使用元类，应该不难......

>>> class Meta(type):
...   def __init__(cls, *args):
...     super(Meta, cls).__init__(*args)
...     cls.__doc__ = class_docstr.format(name=cls.__name__)
... 
>>> class A(object):
...   __metaclass__ = Meta
... 
>>> A.__doc__
'\nThis is the docstring for the A class.\n'

话虽如此，这几乎可以肯定是矫枉过正......

【讨论】：

我真的不想使用元类，但不知道更清洁的解决方案。你能提供一个替代方案吗？也许是 Blckknght 的建议？
当然可以。然后你必须两次指定类的名称，但这不是世界末日。或者，您可以创建一个类装饰器来完成这项工作......基本上 - 您有很多选择，这实际上取决于您想要变得多冗长......
这在 Python 2 中不起作用，在创建类后您无法修改 __doc__ 变量。您可以在元类__new__ 方法中将__doc__ 值添加到类字典中，但这比您在此处的内容要详细一些。
@Blckknght 如果类的类型不是type，则有可能。所以，一个简单的基于装饰器的方法是不可能的。
啊，很有趣... :-)