將docstring設置為def中的表達式

Question

我想在 def設置func_doc （作為表達式）。

def f():
    '''My function help''' #Set the docstring

def g():
    "My function " + "help" # An expression, so not read as a docstring
    # can I put something here to set the docstring as an expression?
g.func_doc # is None
g.func_doc = "My function " + "help" # This works

這可能嗎？

（我可以考慮這樣做的兩個原因：從模塊導入函數（並且您也想導入文檔字符串）和使用詞法分析器 。）

Answer 1

您不能這樣做，因為只有字符串文字被識別為文檔字符串。 但是您可以使用裝飾器來設置或修改函數的文檔字符串。 （您也可以在可執行代碼中顯式修改__doc__ ，但裝飾器更清晰，因為它在邏輯上是聲明的一部分）。

這可能很有用，例如，如果您有多個函數應包含與其文檔字符串（的一部分）相同的文本。 這是一個小裝飾器，它將其參數（文字或變量）附加到函數聲明的docstring。

def docstring(docstr, sep="\n"):
    """
    Decorator: Append to a function's docstring.
    """
    def _decorator(func):
        if func.__doc__ == None:
            func.__doc__ = docstr
        else:
            func.__doc__ = sep.join([func.__doc__, docstr])
        return func
    return _decorator

它可以像這樣使用：

@docstring("copyright by nobody")
def testme():
    "This function does nothing"
    pass

或者您可以直接執行它，修改現有函數（可能從另一個模塊導入）：

from re import sub
docstring("Copyright unknown")(sub)

Answer 2

你不能。 規則是：作為第一個語句的字符串文字被視為docstring。 如果它是表達式，則它不是字符串文字，因此被忽略。

如果確實需要，您也可以在之后顯式指定docstring屬性。 我不明白為什么你需要它。 你的理由對我來說似乎很可疑：

• 導入一個函數（或其他任何東西，真的）為您提供了相同的文檔字符串。 包裝功能是另一個故事，但我們有functools.wraps 。
• 將正則表達式的一部分分解為單獨的變量並不會使本身更具可讀性。 掌握令牌定義對於理解動作代碼至關重要。

Answer 3

不，您不能在函數體內設置函數的文檔字符串，而不是在函數外部或函數內部執行代碼（這需要先調用函數）。

python通常設置文檔字符串的方式是獲取函數套件的第一行（在def行下縮進的所有內容）， 如果這是一個字符串文字 ，它會從套件中刪除它並使其成為文檔字符串。 然后，Python將套件的其余部分編譯到函數代碼對象中，並通過傳入已編譯的代碼對象和docstring（以及其他對象function()創建新的function()對象。

如果你使用恰好產生字符串的表達式，那么'技巧'不起作用; python將忽略該表達式，將其作為要編譯的函數套件的一部分。 因為函數套件本身是編譯的而不是執行的 ，所以你不能“伸出”並在編譯期間設置要在函數對象上使用的docstring。

動態設置函數文檔字符串的唯一方法是直接引用函數對象並設置它的__doc__或func_doc變量（這兩個是別名）。 當然，這可以在函數套件中完成，但這是毫無意義的，文檔字符串將是錯誤的，直到你這樣做。

請注意，從模塊導入函數時，您已經獲得了文檔字符串：

>>> import itertools
>>> print itertools.groupby.__doc__
groupby(iterable[, keyfunc]) -> create an iterator which returns
(key, sub-iterator) grouped by each value of key(value).

無需單獨導入docstring。

Answer 4

您可以在運行時修改函數的__doc__屬性：

>>> def what():
...    """docstring"""
...    what.__doc__ += " x"
...    print what.__doc__
... 
>>> what()
docstring x
>>> what()
docstring x x
>>> what()
docstring x x x
>>> what()
docstring x x x x