Design goals

The primary goal is to make the common pattern of “callbacks that are intendedto be called with specific keyword arguments” straightforward to express withCallable. Today, such callbacks must be written as aProtocol with a__call__ that uses**kwargs:Unpack[...] or includes each keywordparameter explicitly. This approach is verbose and inconsistentwith how positional variadics are supported: perPEP 646,*args can beexpressed as*tuple[int,...] insideCallable.

AllowingUnpack[TypedDict] insideCallable achieves the following:

• Preserves the familiarCallable[[...],R] shape while enablingkeyword-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 alignswith existing semantics fromPEP 692 (Unpack for**kwargs) andPEP 728 (extra_items andclosed).
• Keeps the feature additive, backwards compatible, and stays mostly atyping-specification change only.

Alternatives considered

1. Continue recommendingProtocol-based callbacks only.This keeps the status quo and avoids changingCallable. However, it issyntactically heavier and duplicates concepts already present inCallable.
2. Introduce a newCallable syntax for keywords (e.g., dedicated keywordparameter markers insideCallable).This would require extending the callable parameter grammar with newconstructs, creating fresh semantics for optionality, defaults, and extrakeywords. The design space overlaps withTypedDict andPEP 692 andrisks divergent behavior from existing**kwargs typing.
3. Adopt callback literal syntax (cf.PEP 677) to express rich signaturesinline. Literal syntax can improve readability but introduces a larger,orthogonal change. This PEP seeks a focused, minimal extension that workswithinCallable and existing typing semantics.

Design trade-offs and decisions

• Positional parameters: Allowing positional parameters to precedeUnpack[TD] retains existingCallable semantics and mirrors realPython functions where positional and keyword-only parameters coexist.
• Concatenate: CombiningUnpack[TD] withConcatenate would enableinterspersed keyword-only parameters among*args and**kwargs. Thisincreases complexity and is not proposed here.

New allowed form

It becomes valid to write:

Callable[[Unpack[TD]],R]

whereTD is aTypedDict. A shorter form is also allowed:

Callable[Unpack[TD],R]

Additionally, positional parameters may be combined with an unpackedTypedDict:

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

Semantics

For type-checking purposes,Callable[[Unpack[TD]],R] behaves as if it werespecified via a callback protocol whose__call__ method has**kwargs:Unpack[TD].The semantics ofUnpack itself are exactly those described in the typingspecification’sUnpack for keyword argumentssection andPEP 692, together withPEP 728 forextra_items andclosed.

This PEP only adds the following Callable-specific rules:

• Unpack[TD] may appear inside the parameter list ofCallable.
• Positional parameters may appear inCallable beforeUnpack[TD] andfollow existingCallable semantics.
• Only aParamSpec may be substituted by an unpackedTypedDict within aCallable.

Examples

The following examples illustrate how unpacking aTypedDict into aCallable enforces acceptance of specific keyword parameters. A function iscompatible if it can be called with the required keywords (even if they arealso accepted positionally); positional-only parameters for those keys arerejected:

fromtypingimportTypedDict,Callable,Unpack,Any,NotRequiredclassKeywordTD(TypedDict):a:inttypeIntKwCallable=Callable[[Unpack[KeywordTD]],Any]defnormal(a:int):...defkw_only(*,a:int):...defpos_only(a:int,/):...defdifferent(bar:int):...f1:IntKwCallable=normal# Acceptedf2:IntKwCallable=kw_only# Acceptedf3:IntKwCallable=pos_only# Rejectedf4:IntKwCallable=different# Rejected

Optional arguments

Keys markedNotRequired in theTypedDict correspond to optionalkeyword 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 valuethat is compatible; functions that omit the parameter entirely are rejected:

classOptionalKws(TypedDict):a:NotRequired[int]typeOptCallable=Callable[[Unpack[OptionalKws]],Any]defdefaulted(a:int=1):...defkw_default(*,a:int=1):...defno_params():...defrequired(a:int):...g1:OptCallable=defaulted# Acceptedg2:OptCallable=kw_default# Acceptedg3:OptCallable=no_params# Rejectedg4:OptCallable=required# Rejected

Additional keyword arguments

# implies extra_items=objectclassDefaultTD(TypedDict):a:inttypeDefaultCallable=Callable[[Unpack[DefaultTD]],Any]defv_any(**kwargs:object):...defv_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)

classClosedTD(TypedDict,closed=True):a:inttypeClosedCallable=Callable[[Unpack[ClosedTD]],Any]defv_any(**kwargs:object):...defv_ints(a:int,b:int=2):...c1:ClosedCallable=v_any# Acceptedc1(a=1,c="more")# Rejected (extra c not allowed)c2:ClosedCallable=v_ints# Acceptedc2(a=1,b=2)# Rejected (extra b not allowed)

classExtraTD(TypedDict,extra_items=str):a:inttypeExtraCallable=Callable[[Unpack[ExtraTD]],Any]defaccepts_str(**kwargs:str):...defaccepts_object(**kwargs:object):...defaccepts_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")# Acceptede1(a=1,b=2)# Rejected (b must be str)

typeCallableP[**P]=Callable[P,Any]h:CallableP[Unpack[KeywordTD]]=normal# Acceptedh2:CallableP[Unpack[KeywordTD]]=kw_only# Acceptedh3:CallableP[Unpack[KeywordTD]]=pos_only# Rejected

fromtypingimportTypedDict,Callable,Unpack,AnyclassKeywordTD(TypedDict):a:inttypeIntKwPosCallable=Callable[[int,str,Unpack[KeywordTD]],Any]defmixed_kwonly(x:int,y:str,*,a:int):...defmixed_poskw(x:int,y:str,a:int):...defmixed_posonly(x:int,y:str,a:int,/):...m1:IntKwPosCallable=mixed_kwonly# Acceptedm2:IntKwPosCallable=mixed_poskw# Acceptedm3:IntKwPosCallable=mixed_posonly# Rejected