fix(typing): improve decorator type hinting

[JP-Ellis]

The type hinting for the most commonly used decorators were incomplete, resulting in decorated functions being obscured.

This makes use of a TypeVar which allows the return type of the decorator to be the same as its input.

I have also taken the opportunity to fix other instances of Callable type hints missing their arguments.

---

PS:

The benefit of moving import statement behind the if TYPE_CHECKING block is to avoid unnecessary parsing of libraries at runtime (when no type checking takes place). There were a few cases of:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from typing import Callable

which provides no benefit as the typing library has to be parsed in the first place anyway.

I hope it's alright that I fixed a couple of these :)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (5707669) 95.45% compared to head (9c60589) 95.58%.
Report is 14 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #646      +/-   ##
==========================================
+ Coverage   95.45%   95.58%   +0.12%     
==========================================
  Files          49       49              
  Lines        1783     1788       +5     
  Branches      195      193       -2     
==========================================
+ Hits         1702     1709       +7     
+ Misses         53       52       -1     
+ Partials       28       27       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[youtux]

ditto

[JP-Ellis]

I'm not sure whether Callable[P, T] is what is needed in this case. What would that imply for:

@given(
    "Some step",
    converts={
        "id": int,
        "valid": bool,
        "list": lambda s: s.split(", "),
    },
)

Having a single Callable[P, T] would imply that they all have the same return type which is clearly incorrect.

Having said that, it might be correct to say that this should be refined to Callable[[str], Any], unless you are aware of cases where something else than a string is passed to the convert?

[youtux]

ah right, indeed it should be Callable[[str], Any]

[JP-Ellis]

While I agree completely that ParamSpec is the preferred option as it gives further introspection to the parameter types, I opted not to use that as ParamSpec was introduced in Python 3.10, and therefore won't work for Python 3.8 and 3.9 which pytest-bdd supports.

Given you are using typing_extensions already, I'll modify the PR to import ParamSpec from typing_extensions instead of the standard library.