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()`:
```python
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`:
```python
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.
Actual behavior
When applying decorators that change the argument spec, internally applying
functools.wrapsto 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()`: ```python 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`: ```python 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.wrapson 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