更改签名的修饰符：正确记录附加参数

vikingr 发表于 Dev

维京格

假设我有一个自定义装饰器，并且我希望它能够正确处理装饰函数的文档字符串。问题是：我的装饰器添加了一个参数。

from functools import wraps

def custom_decorator(f):
    @wraps(f)
    def wrapper(arg, need_to_do_more):
        '''
        :param need_to_do_more: if True: do more
        '''
        args = do_something(arg)

        if need_to_do_more:
            args = do_more(args)

        return f(args)

    return wrapper

您可以看到该参数实际上并没有传递给装饰函数，而是由包装器使用的-在这里可能相关，也可能不相关。

如何正确记录附加参数？包装器接受其他参数是一个好习惯，还是应该避免呢？

还是我应该使用其他解决方案，例如：

使包装器成为简单的高阶函数，并将其调用的函数作为第三个参数传递
重构包装成两个独立的功能？

雅各布·齐默曼

如果期望装饰的结果总是向该参数提供相同的内容，则建议将其设置为参数化装饰器。我猜您已经想到了这一点，但是需要说一下。

除此之外，我肯定会建议将其分成两部分，就像您的第二个建议一样。然后，装饰器的用户可以提供使用两个不同装饰器的“重载”版本（因为它们将需要不同的名称，因此不是真正的重载）。

另一个可能的选项是为参数提供默认值。

最后，如果只是必须保持原样，则需要在包装器定义__doc__ 之后的末尾附加新的参数文档。

因此，您的示例（简化）如下所示：

def custom_decorator(f):
    @wraps(f)
    def wrapper(arg, need_to_do_more):
        ...

    wrapper.__doc__ += "/n:param need_to_do_more: if True: do more"
    return wrapper

这是因为@wraps(f)装饰器将wrapper的文档替换为f。之后添加它实际上将两者结合在一起。

这些选项的另一种选择是进行文档记录，custom_decorator以便说包装方法需要在其文档中添加参数。这以及装饰器的拆分给用户带来了负担，但它们使意图更加明确（“ ...显式优于隐式...”-Python Zen）

本文收集自互联网，转载请注明来源。

如有侵权，请联系[email protected] 删除。