如何把一個變量引入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`