Decorators

What would you recommend in terms of typing hints for a decorator?

@Bastian Decorators are usually defined as functions, so regular type hinting rules apply:

import functools
import time
from typing import Any, Callable

def measure_time(function: Callable) -> Callable:
    @functools.wraps(function)
    def wrapper(*args, **kwargs) -> Any:
        t1 = time.perf_counter()
        result = function(*args, **kwargs)
        t2 = time.perf_counter()
        print(f"{function.__name__}() executed in {t2 - t1:.2f} seconds")
        return result
    return wrapper

@measure_time
def add(a, b):
    return a + b

On the other hand, if you decide not to use the @-syntax but rather decorate functions manually, then you could try using the Callable hint to declare a decorator:

def decorate(function: Callable, decorator: Callable) -> Callable:
    return decorator(function)

decorated_add = decorate(add, measure_time)

Is that what you were asking about?

Hi @Bastian,

as Bartosz says, decorators are functions so you will typically use Callable to type hint them. However, this is not completely satisfactory because there are several typical decorator patterns that are simply not possible to annotate so that they can be correctly type checked. Unless you have very specific decorators, it’s hard to preserve the type information of the original function that is decorated.

To continue on Bartosz’ example from above, if you annotate add() as follows:

@measure_time
def add(a: int, b: int) -> int:
    return a + b

Even though you have annotated both input types and return types, those hints are lost because the function has been replaced by wrapper() returned by the @measure_time decorator.

It’s possible to use a type variable to preserve the return value:

import functools
from typing import Any, TypeVar

R = TypeVar("R")

def measure_time(function: Callable[..., R]) -> Callable[..., R]:
    @functools.wraps(function)
    def wrapper(*args: Any, **kwargs: Any) -> R:
        # Same as above
    return wrapper

Here, the type R will be matched, so that for instance for add() as above, R will represent int and the decorated version of add() will also have int as its return type.

In Callable[..., R], the three dots are valid code and represent any specification of input parameter types. For a general decorator like this, that is really the best we can do. However, there is no validation that there is a match between the different instances of ... or the use of Any in the wrapper() signature.

Type variables don’t really work for this, because they would force you to specify the number of input parameters (one type variable per parameter), and there is currently not any other mechanism for preserving an undetermined number of types.

This has been recognized and in Python 3.10, which will be officially released in October, a new feature called Parameter Specification will be included, which will solve exactly this use case. You can read all the details, including examples of what is currently not possible and how that will be fixed, in the enhancement proposal: PEP 612

Great! Thanks to both of you for the detailed answers!

Small off-topic note: the code in the videao @03:26 reports seconds as milliseconds.

Thanks @mo. Good catch. Code’s been there for almost a year and you’re the first to catch that. I’ll get it patched. …ct