模板化的 Python 文档字符串

Question

为什么动态格式化文档字符串不起作用？ 在函数定义时是否有可接受的解决方法？

>>> DEFAULT_BAR = "moe's tavern"
>>> def foo(bar=DEFAULT_BAR):
...     """
...     hello this is the docstring
...     
...     Args:
...       bar (str)    the bar argument (default: {})
...     """.format(DEFAULT_BAR)
... 
>>> foo.__doc__
>>> foo.__doc__ is None
True

我尝试使用老式的 %s 格式，但也没有用。

Answer 1

您的字符串需要调用函数，但创建函数时不会执行函数体。

适当的文档字符串不会执行，它只是从解析的源代码中获取并附加到函数对象，不会为此执行任何代码。 Python 将文档字符串存储为代码对象中的第一个常量值:

>>> def f():
...     """docstring"""
...     pass
...
>>> f.__code__.co_consts
('docstring', None)

构造新函数时代码对象传递给函数类型的位置(参见 PyFunction_New() function)。

参见 Function definitions reference documentation :

The function definition does not execute the function body; this gets executed only when the function is called. [3]

[...]

[3] A string literal appearing as the first statement in the function body is transformed into the function’s __doc__ attribute and therefore the function’s docstring.

您的定义在其他方面是有效的；函数体顶部没有独立的字符串文字。您的字符串文字是函数本身的一部分，并且仅在调用该函数时执行(并且由于您不存储该结果而将其丢弃)。

请注意，函数对象的 __doc__ 属性是可写的；您始终可以在创建函数后应用变量:

>>> DEFAULT_BAR = "moe's tavern"
>>> def foo(bar=DEFAULT_BAR):
...     """
...     hello this is the docstring
...
...     Args:
...       bar (str)    the bar argument (default: {})
...     """
...
>>> foo.__doc__ = foo.__doc__.format(DEFAULT_BAR)
>>> print(foo.__doc__)

    hello this is the docstring

    Args:
      bar (str)    the bar argument (default: moe's tavern)

也许您可以借助 functionobject.__globals__ 和 inspect.getargspec() 在装饰器中做到这一点，但随后在模板中使用命名插槽，这样您可以将所有内容作为字典应用，并让文档字符串选择要插入的内容:

from inspect import getargspec

def docstringtemplate(f):
    """Treat the docstring as a template, with access to globals and defaults"""
    spec = getargspec(f)
    defaults = {} if not spec.defaults else dict(zip(spec.args[-len(spec.defaults):], spec.defaults))
    f.__doc__ = f.__doc__ and f.__doc__.format(**dict(f.__globals__, **defaults))
    return f

演示:

>>> @docstringtemplate
... def foo(bar=DEFAULT_BAR):
...     """
...     hello this is the docstring
...
...     Args:
...       bar (str)    the bar argument (default: {bar!r}, or {DEFAULT_BAR!r})
...
...     """
...
>>> print(foo.__doc__)

    hello this is the docstring

    Args:
      bar (str)    the bar argument (default: "moe's tavern", or "moe's tavern")

函数关键字参数覆盖全局变量，就像它们在函数中一样。