There is a small bug in the `@deprecated` decorator (#2359), which unfortunately doesn't resolve this issue.

`functools.wraps` (which is the stdlib's simpler implementation of what `decorator.py` does) doesn't adapt the function signature of the wrapper.  I don't know if this is worth adding yet another dependency.