Design goals

The primary goal is to make the common pattern of “callbacks that are intended to be called with specific keyword arguments” straightforward to express with Callable. Today, such callbacks must be written as a Protocol with a __call__ that uses **kwargs: Unpack[...] or includes each keyword parameter explicitly. This approach is verbose and inconsistent with how positional variadics are supported: per PEP 646, *args can be expressed as *tuple[int, ...] inside Callable.

Allowing Unpack[TypedDict] inside Callable achieves the following:

• Preserves the familiar Callable[[...], R] shape while enabling keyword-only parameter descriptions.
• Provides a concise shorthand equivalent to Protocol-based callbacks with __call__(self, **kwargs: Unpack[TD]) -> R.
• Provides the intuitive analogue to positional variadics.
• Reuses existing building blocks and keeps semantics predictable. It aligns with existing semantics from PEP 692 (Unpack for **kwargs) and PEP 728 (extra_items and closed).
• Keeps the feature additive, backwards compatible, and stays mostly a typing-specification change only.

Alternatives considered

1. Continue recommending Protocol-based callbacks only. This keeps the status quo and avoids changing Callable. However, it is syntactically heavier and duplicates concepts already present in Callable.
2. Introduce a new Callable syntax for keywords (e.g., dedicated keyword parameter markers inside Callable). This would require extending the callable parameter grammar with new constructs, creating fresh semantics for optionality, defaults, and extra keywords. The design space overlaps with TypedDict and PEP 692 and risks divergent behavior from existing **kwargs typing.
3. Adopt callback literal syntax (cf. PEP 677) to express rich signatures inline. Literal syntax can improve readability but introduces a larger, orthogonal change. This PEP seeks a focused, minimal extension that works within Callable and existing typing semantics.

Design trade-offs and decisions

• Positional parameters: Allowing positional parameters to precede Unpack[TD] retains existing Callable semantics and mirrors real Python functions where positional and keyword-only parameters coexist.
• Concatenate: Combining Unpack[TD] with Concatenate would enable interspersed keyword-only parameters among *args and **kwargs. This increases complexity and is not proposed here.

New allowed form

It becomes valid to write:

Callable[[Unpack[TD]], R]

where TD is a TypedDict. A shorter form is also allowed:

Callable[Unpack[TD], R]

Additionally, positional parameters may be combined with an unpacked TypedDict:

Callable[[int, str, Unpack[TD]], R]

Semantics

For type-checking purposes, Callable[[Unpack[TD]], R] behaves as if it were specified via a callback protocol whose __call__ method has **kwargs: Unpack[TD]. The semantics of Unpack itself are exactly those described in the typing specification’s Unpack for keyword arguments section and PEP 692, together with PEP 728 for extra_items and closed.

This PEP only adds the following Callable-specific rules:

• Unpack[TD] may appear inside the parameter list of Callable.
• Positional parameters may appear in Callable before Unpack[TD] and follow existing Callable semantics.
• Only a ParamSpec may be substituted by an unpacked TypedDict within a Callable.

Examples

The following examples illustrate how unpacking a TypedDict into a Callable enforces acceptance of specific keyword parameters. A function is compatible if it can be called with the required keywords (even if they are also accepted positionally); positional-only parameters for those keys are rejected:

from typing import TypedDict, Callable, Unpack, Any, NotRequired

class KeywordTD(TypedDict):
    a: int

type IntKwCallable = Callable[[Unpack[KeywordTD]], Any]

def normal(a: int): ...
def kw_only(*, a: int): ...
def pos_only(a: int, /): ...
def different(bar: int): ...

f1: IntKwCallable = normal     # Accepted
f2: IntKwCallable = kw_only    # Accepted
f3: IntKwCallable = pos_only   # Rejected
f4: IntKwCallable = different  # Rejected

Optional arguments

Keys marked NotRequired in the TypedDict correspond to optional keyword arguments. This means that the callable must accept them, but callers may omit them. Functions that accept the keyword argument must also provide a default value that is compatible; functions that omit the parameter entirely are rejected:

class OptionalKws(TypedDict):
    a: NotRequired[int]

type OptCallable = Callable[[Unpack[OptionalKws]], Any]

def defaulted(a: int = 1): ...
def kw_default(*, a: int = 1): ...
def no_params(): ...
def required(a: int): ...

g1: OptCallable = defaulted    # Accepted
g2: OptCallable = kw_default   # Accepted
g3: OptCallable = no_params    # Rejected
g4: OptCallable = required     # Rejected

Additional keyword arguments

# implies extra_items=object
class DefaultTD(TypedDict):
  a: int

type DefaultCallable = Callable[[Unpack[DefaultTD]], Any]

def v_any(**kwargs: object): ...
def v_ints(a: int, b: int=2): ...

d1: DefaultCallable = v_any   # Accepted (implicit object for extras)
d1(a=1, c="more")             # Accepted (extras allowed)
d2: DefaultCallable = v_ints  # Rejected (b: int is not a supertype of object)

class ClosedTD(TypedDict, closed=True):
  a: int

type ClosedCallable = Callable[[Unpack[ClosedTD]], Any]

def v_any(**kwargs: object): ...
def v_ints(a: int, b: int=2): ...

c1: ClosedCallable = v_any   # Accepted
c1(a=1, c="more")            # Rejected (extra c not allowed)
c2: ClosedCallable = v_ints  # Accepted
c2(a=1, b=2)                 # Rejected (extra b not allowed)

class ExtraTD(TypedDict, extra_items=str):
  a: int

type ExtraCallable = Callable[[Unpack[ExtraTD]], Any]

def accepts_str(**kwargs: str): ...
def accepts_object(**kwargs: object): ...
def accepts_int(**kwargs: int): ...

e1: ExtraCallable = accepts_str     # Accepted (matches extra_items type)
e2: ExtraCallable = accepts_object  # Accepted (object is a supertype of str)
e3: ExtraCallable = accepts_int     # Rejected (int is not a supertype of str)

e1(a=1, b="foo")   # Accepted
e1(a=1, b=2)       # Rejected (b must be str)

type CallableP[**P] = Callable[P, Any]

h: CallableP[Unpack[KeywordTD]] = normal   # Accepted
h2: CallableP[Unpack[KeywordTD]] = kw_only # Accepted
h3: CallableP[Unpack[KeywordTD]] = pos_only # Rejected

from typing import TypedDict, Callable, Unpack, Any

class KeywordTD(TypedDict):
    a: int

type IntKwPosCallable = Callable[[int, str, Unpack[KeywordTD]], Any]

def mixed_kwonly(x: int, y: str, *, a: int): ...
def mixed_poskw(x: int, y: str, a: int): ...
def mixed_posonly(x: int, y: str, a: int, /): ...

m1: IntKwPosCallable = mixed_kwonly  # Accepted
m2: IntKwPosCallable = mixed_poskw   # Accepted
m3: IntKwPosCallable = mixed_posonly # Rejected