Let's say I have a custom decorator, and I want it to properly handle docstring of decorated function. Problem is: my decorator adds an argument. from functools import wrapsdef 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 wrapperYou can see the argument is not actually passed to decorated function, but used by the wrapper - which may or maynot be relevant here.How can I properly handle documenting the additional argument?Is it a good practice for a wrapper to take an additional argument, or should I avoid it? Or should I rather use a different solution, like:making wrapper a simple higher order function, with the function it calls passed as the third argumentrefactoring the wrapper into two separate functions?
Signature-changing decorator: properly documenting additional argument
python;programming practices
Changing method signature using decorator is something that in most cases violates Principle Of Least Astonishment:The Principle of Least Astonishment states that the result of performing some operation should be obvious, consistent, and predictable, based upon the name of the operation and other clues.The exceptions I could come up are:decorator in its name clearly states that method signature is changed. Example of such decorator is @property. decorated method is not intended to be invoked directly by client codedecorator is used for some kind of adaptation (like Adapter pattern)Nevertheless, usually decorators are usually implemented for decorating functions (like in Decorator pattern, although authors of the decorator feature opposed this similarities), which implies that method signature (including list of parameters) is not changed.As an alternative to implicitly adding new parameter I propose to make this explicit - any decorated function must declare such parameter on the list of parameters. You can check function parameter names using method described in this SO answer and throw exception if decorated function does not have such parameter.Implicit parameter or requiring parameter should be described in decorator docstring (custom_decorator in your example). If you use @wraps decorator on returned function (wrapper in your example), __doc__ attribute is copied from function f and overwrites whatever docstring you specify for wrapper.