Use typing.TypeVar on methods used as annotations

[marcoffee]

Is your feature request related to a problem? Please describe.
When I annotate a method with, for example, @capture_span, the method loses its type hints and becomes just a Callable.
For example, Pylance gives the following information tooltips (as commented to the right of the reveal_type calls):

import elasticapm as apm
from typing_extensions import reveal_type


def test (a: int, b: str, c: float) -> bytes:
    return b"abc"

@apm.capture_span()
def test_with_apm (a: int, b: str, c: float) -> bytes:
    return b"abc"

reveal_type(test)  # Type of "test" is "(a: int, b: str, c: float) -> bytes"
reveal_type(test_with_apm)  # Type of "test_with_apm" is "(...) -> Any"

Describe the solution you'd like
Just use TypeVar on the __call__ method signature of annotation methods, example:

from typing import TypeVar

_AnnotatedFunctionT = TypeVar("_AnnotatedFunctionT")

class capture_span(object):
    ...
    def __call__(self, func: _AnnotatedFunctionT) -> _AnnotatedFunctionT:
        self.name = self.name or get_name_from_func(func)

        @functools.wraps(func)
        def decorated(*args, **kwds):
            with self:
                return func(*args, **kwds)

        return decorated
    ...

After this small change, the reveal_type reports the expected type:

import elasticapm as apm
from typing_extensions import reveal_type

@apm.capture_span()
def test_with_apm (a: int, b: str, c: float) -> bytes:
    return b"abc"

reveal_type(test_with_apm)  # Type of "test_with_apm" is "(a: int, b: str, c: float) -> bytes"

Describe alternatives you've considered
I've considered creating a pull request myself to solve this, but the CONTRIBUTING.md file indicates that an issue should be opened first.

Additional context
Screenshot of VSCode's pylance type hints without the change:

Screenshot of VSCode's pylance type hints with the change:

[beniwohli]

Hey @marcoffee

That's a great improvement! Thanks for proposing this, a PR would be great! Do you think it would also make sense to annotate the actual decorator (the decorated function) with ParamSpec? That is, if we can find a way to do it in a backwards-compatible way, as ParamSpec is only available in Python 3.10...

[marcoffee]

@beniwohli

Thanks for the positive feedback! I think there is an implementation of the ParamSpec on the typing-extensions package, but it is for python >= 3.7, so compatibility would still be broken for 3.5 and 3.6. Also, there is the issue of adding another requirement.
Anyways, I think there is no need to annotate the internal method, since functools.wrap already solve the issue for runtime, and the TypeVar ensures the typing of the return.
I will start working on the PR as soon as possible.