如何将变量放入 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 有什么；这样当更新这个变量时，文档字符串将自动更新。

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

原文由 Jack Z 发布，翻译遵循 CC BY-SA 4.0 许可协议

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}

不过，我不确定这是否会正常工作；文档字符串有点神奇。这是 行不通 的；文档字符串在编译时被评估（作为函数中的第一条语句，假设它是一个字符串文字——一旦它得到 % 其中它不仅仅是一个字符串文字），字符串格式化发生在运行时，所以 __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 中的一种动物类型”，或类似的。

原文由 Chris Morgan 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 2

一种方法是使用装饰器。我不确定我对此有何看法；实际上，我搜索了有关此方法的评论并找到 了这个答案，该答案正确地指出它可能会掩盖设计问题。但是乍一看，您的用例对我来说 似乎很 合理。

无论如何，这是一种相当优雅的方式来实现您正在寻找的结果：

 >>> def docstring_parameter(*sub):
...     def dec(obj):
...         obj.__doc__ = obj.__doc__.format(*sub)
...         return obj
...     return dec
...
>>> @docstring_parameter('Ocean')
... def foo():
...     '''My Docstring Lies Over The {0}'''
...     pass
...
>>> @docstring_parameter('Sea')
... def bar():
...     '''My Docstring Lies Over The {0}'''
...     pass
...
>>> @docstring_parameter('Docstring', 'Me')
... def baz():
...     '''Oh Bring Back My {0} To {1}'''
...     pass
...
>>> foo.__doc__
'My Docstring Lies Over The Ocean'
>>> bar.__doc__
'My Docstring Lies Over The Sea'
>>> foo.__doc__
'My Docstring Lies Over The Ocean'
>>> baz.__doc__
'Oh Bring Back My Docstring To Me'

原文由 senderle 发布，翻译遵循 CC BY-SA 3.0 许可协议