将docstring设置为def中的表达式

时间:2012-08-31 15:39:04

标签: python docstring

我想在 func_doc中设置def(作为表达式)

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

这可能吗?

(我可以考虑这样做的两个原因:从模块导入函数(并且您也要导入文档字符串)并使用lexer。)

4 个答案:

答案 0 :(得分:5)

您不能这样做,因为只有字符串文字被识别为文档字符串。但是您可以使用装饰器来设置或修改函数的文档字符串。 (您也可以在可执行代码中明确地修改__doc__,但装饰器更清晰,因为它在逻辑上是声明的一部分。)

这可能很有用,例如,如果您有多个函数应该包含与其文档字符串(部分)相同的文本。这是一个小装饰器,它将其参数(文字或变量)附加到函数声明的文档字符串。

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)

答案 1 :(得分:1)

你做不到。规则是:将string literal作为第一个语句作为docstring。如果它是一个表达式,它不是字符串文字,因此被忽略。

如果你真的需要这个,你也可以在之后明确地分配给docstring属性。我没有看到为什么你需要它。你的理由对我来说似乎很可疑:

  • 导入一个函数(或其他任何东西,真的)为您提供了相同的文档字符串。 包装一个功能是另一个故事,但我们拥有functools.wraps
  • 将一部分正则表达式分解为一个单独的变量并不会使本身更具可读性。掌握令牌定义对于理解动作代码至关重要。

答案 2 :(得分:1)

不,你不能在函数体内设置函数的docstring,不能在函数外部或函数内部执行代码(需要先调用函数)。

python通常设置文档字符串的方式是获取函数套件的第一行(在def行下缩进的所有内容)和,如果这是字符串文字,它将从套件并使其成为文档串。 Python然后将套件的其余部分编译到函数代码对象中,并通过传入已编译的代码对象和docstring(以及其他对象)来创建新的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。

答案 3 :(得分:0)

您可以在运行时修改函数的__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