如何把一个变量引入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}函数定义之后。请注意，如果您没有检查__doc__被定义，则会在python -OO上突破，因为-OO会剥离文档字符串。

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

反正这不是标准技术;标准技术是引用适当的常量：“采用ANIMAL_TYPES中的一种动物类型”或类似的。

Answer 2

您还可以定义使用.__doc__

例如文档字符串：

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

>>> f.__doc__ = "%s string %s" % (x, y) 
>>> print(f.__doc__) 
1 string docstring 

Answer 3

一种方式做，这将是使用装饰。我不确定我对此的看法;我真的搜索了这个方法的评论，发现this answer，正确地指出它可以掩盖设计问题。但你的使用案例似乎乍一看对我来说。

在任何情况下，这里是一个相当优雅的方式来实现你要找的结果：

>>> 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' 

Answer 4

你可以简单地使用[交叉参考] [1]在您的文档串指变量。

所以：

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

而在第二个：

:param choice: can be one of :attr:`MY_CONST`