Python: What is the typing.ParamSpec?

1from typing import ParamSpec, TypeVar, Callable
2
3P = ParamSpec("P")
4R = TypeVar("R")
5
6# Type-safe decorator
7def log_calls(func: Callable[P, R]) -> Callable[P, R]:
8    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
9        print(f"Calling {func.__name__}")
10        return func(*args, **kwargs)
11    return wrapper
12
13@log_calls
14def add(a: int, b: int) -> int:
15    return a + b
16
17add(1, 2)  # Type checker knows: (int, int) -> int
18
19# With keyword arguments
20@log_calls
21def greet(name: str, greeting: str = "Hello") -> str:
22    return f"{greeting}, {name}!"
23
24greet("Alice")               # OK
25greet("Alice", greeting="Hi") # OK
26
27# ParamSpec with Concatenate
28from typing import Concatenate
29
30def with_context(
31    func: Callable[Concatenate[Context, P], R]
32) -> Callable[P, R]:
33    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
34        ctx = get_context()
35        return func(ctx, *args, **kwargs)
36    return wrapper
37
38@with_context
39def process(ctx: Context, data: str) -> str:
40    return ctx.transform(data)
41
42process("hello")  # Context is injected, type-safe!