> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Python ParamSpec
`typing.ParamSpec` is a specialized type variable used to capture, parameterize, and forward the complete parameter signature (both positional and keyword arguments) of a `Callable`. Introduced in Python 3.10 (PEP 612), it resolves the structural limitation of a standard `TypeVar`, which can only bind to a single type. `ParamSpec` allows static type checkers to validate the exact argument structure passed between higher-order functions.
## Declaration and Syntax
A `ParamSpec` is instantiated similarly to a `TypeVar`, typically using a single uppercase letter.
```python theme={"dark"}
from typing import ParamSpec, TypeVar, Callable
P = ParamSpec('P')
R = TypeVar('R')
```
When applied to a `Callable`, `ParamSpec` replaces the list of argument types. For example, `Callable[P, R]` indicates a function that accepts the parameter specification `P` and returns a value of type `R`.
## Internal Attributes: `args` and `kwargs`
To forward the captured signature to a function's actual parameters, `ParamSpec` exposes two special attributes:
* **`P.args`**: Represents the tuple of positional arguments. It must be used to type hint `*args`.
* **`P.kwargs`**: Represents the dictionary of keyword arguments. It must be used to type hint `**kwargs`.
These attributes ensure that the type checker enforces strict parity between the captured signature and the arguments provided at runtime.
```python theme={"dark"}
from typing import Callable, ParamSpec, TypeVar
P = ParamSpec('P')
R = TypeVar('R')
def abstract_forwarder(
func: Callable[P, R],
*args: P.args,
**kwargs: P.kwargs
) -> R:
# The type checker guarantees that *args and **kwargs
# strictly conform to the signature of `func`.
return func(*args, **kwargs)
```
## Signature Modification with `Concatenate`
`ParamSpec` is frequently used in conjunction with `typing.Concatenate` to represent signatures where parameters are mechanically added or removed from the captured specification.
`Concatenate` prepends one or more explicit types to a `ParamSpec`. This is structurally necessary when a higher-order function injects or consumes arguments before forwarding the rest of the signature.
```python theme={"dark"}
from typing import Callable, ParamSpec, TypeVar, Concatenate
P = ParamSpec('P')
R = TypeVar('R')
def signature_consumer(
func: Callable[Concatenate[str, P], R]
) -> Callable[P, R]:
def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
# The string argument is consumed internally;
# the returned callable only requires the remaining signature (P).
return func("injected_string", *args, **kwargs)
return wrapper
```
## Type Checking Mechanics
When a static type checker (like `mypy` or `pyright`) evaluates a `ParamSpec`, it performs the following operations:
1. **Inference**: It infers the exact positional and keyword types from the passed `Callable`.
2. **Binding**: It binds those types to `P`.
3. **Validation**: It validates that any subsequent use of `P.args` and `P.kwargs` exactly matches the bound signature, raising a type error if arity, argument names, or argument types deviate.
Tired of Poor Python Skills? Fix That With Deep Grasping!
Learn More
