71

所以我试图创建一个“动态”的文档字符串，它是这样的：

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内容；这样当这个变量被更新时，文档字符串就会自动更新。

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

4

4 回答 4

64

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

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

>>> 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'
于 2012-04-25T01:54:23.307 回答
22

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

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

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

不过，我不确定这是否会正常工作；文档字符串有点神奇。 这行不通；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 中的一种动物类型”，或类似的。

于 2012-04-25T00:13:20.773 回答
9

您还可以使用定义文档字符串.__doc__

例如：

>>> def f():
      pass
>>> x = 1
>>> y = "docstring"

>>> f.__doc__ = "%s string %s" % (x, y)
>>> print(f.__doc__)
1 string docstring
于 2012-04-25T00:20:57.163 回答
2

您可以简单地在您的文档字符串中使用交叉引用来引用该变量。

所以：

:param animalType: It takes one of these :data:`animal types<ANIMAL_TYPES>`

在第二个：

:param choice: can be one of :attr:`MY_CONST`
于 2012-12-14T13:32:57.480 回答