如何将变量放入Python文档字符串

Question

因此，我试图创建一个“动态”文档字符串，如下所示：

ANIMAL_TYPES = ["mammals", "reptiles", "other"]

def func(animalType):
""" This is a sample function.

    @param animalType: "It takes one of these animal types %s" % ANIMAL_TYPES
"""

基本上让文档字符串@param animalType显示所有ANIMAL_TYPES内容；因此，当更新此变量时，文档字符串将自动更新。

不幸的是，它似乎不起作用。有谁知道有没有办法实现这一目标？

Answer 1

三引号字符串是一个大字符串。它们内部没有任何评估。该%部分是字符串的所有部分。您需要使它在实际的字符串上运行。 ~~~~

def func(animalType):
    """
    This is a sample function.

    @param animalType: "It takes one of these animal types %(ANIMAL_TYPES)s"
    """ % {'ANIMAL_TYPES': ANIMAL_TYPES}

我不确定这是否可以正常工作；docstrings有点神奇。这将 不 工作;
docstring在编译时进行评估（作为函数中的第一条语句，假定它是字符串文字，一旦包含%了它，而不仅仅是字符串文字），字符串格式在运行时发生，因此__doc__为空：

>>> def a(): 'docstring works'
... 
>>> a.__doc__
'docstring works'
>>> def b(): "formatted docstring doesn't work %s" % ':-('
... 
>>> b.__doc__
>>>

如果要以这种方式工作，则需要func.__doc__ %= {'ANIMAL_TYPES': ANIMAL_TYPES}在定义函数之后执行。请注意，python -OO如果您不检查__doc__已定义的内容（如-OO剥离文档字符串），这将中断。

>>> def c(): "formatted docstring works %s"
... 
>>> c.__doc__
"formatted docstring works %s"
>>> c.__doc__ %= 'after'
>>> c.__doc__
"formatted docstring works after"

无论如何，这不是标准技术。标准技术是引用适当的常量：“采用ANIMAL_TYPES中的一种动物类型”或类似的常量。