Prepare PR

Author: Daraan

peps/pep-0821.rst

@@ -1,14 +1,14 @@
 PEP: 821
 Title: Support for unpacking TypedDicts in Callable type hints
 Author: Daniel Sperber <github.blurry@9ox.net>
+Sponsor: Pending
 Discussions-To: Pending
 Status: Draft
 Type: Standards Track
 Topic: Typing
 Created: 30-Dec-2025
 Python-Version: 3.15
-Post-History: `28-Jun-2025 <https://discuss.python.org/t/pep-idea-extend-spec-of-callable-to-accept-unpacked-typedicts-to-specify-keyword-only-parameters/96975>`__,
-
+Post-History: `28-Jun-2025 <https://discuss.python.org/t/pep-idea-extend-spec-of-callable-to-accept-unpacked-typedicts-to-specify-keyword-only-parameters/96975>`__
 
 Abstract
 ========
@@ -53,6 +53,16 @@ more succinctly::
   type KwCallable = Callable[[Unpack[Signature]], Any]
 
 
+Rationale
+=========
+
+This proposal extends the existing Callable semantics by reusing a ``TypedDict``'s
+keyed structure for keyword arguments. It avoids verbose Protocol-based
+callable definitions while remaining compatible with current typing concepts
+(:pep:`692` Unpack for ``kwargs``, and :pep:`728` ``extra_items``). It preserves backward
+compatibility by being purely a typing feature.
+
+
 Specification
 =============
 
@@ -80,6 +90,7 @@ Semantics
 * Required keys must be accepted, but may correspond to parameters with a
   default value.
 * ``NotRequired`` keys must still be accepted, but may be omitted at call sites.
+  This respectively applies to ``TypedDict`` with ``total=False``.
 * Functions with ``**kwargs`` are compatible if the annotation of ``**kwargs``
   matches or is a supertype of the ``TypedDict`` values.
 * ``extra_items`` from PEP 728 is respected: functions accepting additional
@@ -125,11 +136,11 @@ rejected.
 Optional arguments
 ------------------
 
- Keys marked ``NotRequired`` in the ``TypedDict`` correspond to optional
- keyword arguments.
- Meaning 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.
+Keys marked ``NotRequired`` in the ``TypedDict`` correspond to optional
+keyword arguments.
+Meaning 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.
 
 .. code-block:: python
 
@@ -196,7 +207,7 @@ arguments beyond those declared are expected.
 Interaction with ``extra_items`` (PEP 728)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If a ``TypedDict`` specifies the ``extra_items`` parameter, the corresponding ``Callable``
+If a ``TypedDict`` specifies the ``extra_items`` parameter (with the exemption of ``extra_items=Never``), the corresponding ``Callable``
 must accept additional keyword arguments of the specified type.
 
 For example:
@@ -220,11 +231,13 @@ For example:
   e1(a=1, b=2)       # Rejected (b must be str)
 
 
-Interaction with ParamSpec:
+Interaction with ``ParamSpec`` and ``Concatenate``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``ParamSpec`` can be combined with ``Unpack[TypedDict]`` to define a
+A ``ParamSpec`` can be substituted by ``Unpack[TypedDict]`` to define a
 parameterized callable alias. Substituting ``Unpack[Signature]`` produces the
 same effect as writing the callable with an unpacked ``TypedDict`` directly.
+Using a ``TypedDict`` within ``Concatenate`` is not allowed.
 
 .. code-block:: python
 
@@ -278,26 +291,6 @@ Backwards Compatibility
 This feature is additive. Existing code is unaffected. Runtime behavior does
 not change; this is a typing-only feature.
 
-
-Reference Implementation
-========================
-
-A prototype exists in mypy:
-https://github.com/python/mypy/pull/16083
-
-Open Questions
-==============
-
-* Should combining ``Unpack[TD]`` with ``Concatenate`` and ``ParamSpec`` be
-  supported in the future? With such support, one could write
-  ``Callable[Concatenate[int, Unpack[TD], P], R]`` which in turn would allow a keyword-only parameter between ``*args`` and ``**kwargs``, i.e.
-  ``def func(*args: Any, a: int, **kwargs: Any) -> R: ...`` which is currently not allowed per PEP 612.
-  To keep the initial implementation simple, this PEP does not propose such
-  support.
-* Should multiple ``TypedDict`` unpacks be allowed to form a union, and if so, how to handle
-  overlapping keys?
-
-
 How to Teach This
 =================
 
@@ -317,24 +310,45 @@ taught that with
   using ``closed=True`` for definitions will create the more intuitive equivalence
   of ``__call__(self, a: int, b: str = ...) -> R``
 
-Alternatives
-============
 
-This (`discussion thread <https://discuss.python.org/t/pep-677-with-an-easier-to-parse-and-more-expressive-syntax/98408/33>`__)
-revisits the idea of the rejected :pep:`677`
-to introduce alternative and more expressive syntax for callable type hints.
+Reference Implementation
+========================
+
+A prototype exists in mypy:
+https://github.com/python/mypy/pull/16083
+
+
+Rejected Ideas
+==============
+
+- Combining ``Unpack[TD]`` with ``Concatenate``. With such support, one could write
+  ``Callable[Concatenate[int, Unpack[TD], P], R]`` which in turn would allow a keyword-only parameter between ``*args`` and ``**kwargs``, i.e.
+  ``def func(*args: Any, a: int, **kwargs: Any) -> R: ...`` which is currently not allowed per :pep:`612`.
+  To keep the initial implementation simple, this PEP does not propose such
+  support.
+
+Open Questions
+==============
+
+* Should multiple ``TypedDict`` unpacks be allowed to form a union, and if so, how to handle
+  overlapping keys of non-identical types? Which restrictions should apply in such a case? Should the order matter?
+* Is there a necessity to differentiate between normal and ``ReadOnly`` keys?
+* Is it necessary to specify generic behavior for ``TypedDict`` and the resulting ``Callable`` when the ``TypedDict`` itself is generic?
+
+
+Acknowledgements
+================
+TODO
+
 
 
 References
 ==========
 
-* PEP 484 - Type Hints
-* PEP 612 - ParamSpec
-* PEP 646 - Variadic Generics
-* PEP 692 - Using ``Unpack`` with ``**kwargs``
-* PEP 728 - ``extra_items`` in TypedDict
-* PEP 764 - Inline TypedDict
-* mypy PR #16083 - Prototype support
+* :pep:`692` - Using ``Unpack`` with ``**kwargs``
+* :pep:`728` - ``extra_items`` in TypedDict
+* :pep:`764` - Inline TypedDict
+* `mypy PR #16083 - Prototype support <https://github.com/python/mypy/pull/16083>`__
 * Revisiting PEP 677 (`discussion thread <https://discuss.python.org/t/pep-677-with-an-easier-to-parse-and-more-expressive-syntax/98408/33>`__)