Use updated argspecs of functions wrapped by signature-changing decorators

[Terrance]

Actual behavior

When applying decorators that change the argument spec, internally applying functools.wraps to the replacement causes the corresponding docs to show the arguments of the inner wrapped function, rather than the wrapper.

With explicit type hinting, the types of the inner function arguments and return value are similarly used in place of the wrapper's new types.

Full example

Consider a decorator like the following, an alternate form of map():

def mapped(fn):
    """Map pairs of input numbers to an output number."""
    def inner(pairs):
        for x, y in pairs:
            yield fn(x, y)
    return inner

@mapped
def add(x, y):
    """Sum two numbers."""
    return x + y

if __name__ == "__main__":
    inputs = [(1, 2), (3, 4)]
    for output in add(inputs): ...

This produces documentation with the correct arguments, but the documentation for add comes from inner instead, which has no docstring:

Functions

add(pairs)

mapped(fn) Map pairs of input numbers to an output number.

Now, if we decorate inner with functools.wraps:

from functools import wraps

def mapped(fn):
    @wraps(fn)
    def inner(pairs):
        for x, y in pairs:
            yield fn(x, y)
    return inner

...then we get the inner function's docstring as desired, but also its argument spec:

Functions

add(x, y) Sum two numbers.

Expected behavior

When applying decorators that change the argument spec, using functools.wraps on the replacement should produce docs that show the arguments of the wrapper function, as that's effectively the public API.

The downside is that the inner docstring and the rewritten argspec could be inconsistent, though in general I'd expect the docstring to describe the public, outer version of the function if it's being decorated directly (i.e. @ syntax). Making this configurable at the project level might be desirable in any case.

Additional info

• pdoc version: 0.9.2