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[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

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

```diff @@ 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 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[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.