@@ -3,12 +3,13 @@ Title: TypedDict with Typed Extra Items
33Author: Zixuan James Li <p359101898@gmail.com>
44Sponsor: Jelle Zijlstra <jelle.zijlstra@gmail.com>
55Discussions-To: https://discuss.python.org/t/pep-728-typeddict-with-typed-extra-items/45443
6- Status: Draft
6+ Status: Accepted
77Type: Standards Track
88Topic: Typing
99Created: 12-Sep-2023
1010Python-Version: 3.15
1111Post-History: `09-Feb-2024 <https://discuss.python.org/t/pep-728-typeddict-with-typed-extra-items/45443 >`__,
12+ Resolution: `15-Aug-2025 <https://discuss.python.org/t/pep-728-typeddict-with-typed-extra-items/45443/159 >`__
1213
1314
1415Abstract
@@ -123,6 +124,24 @@ Given the usage of pre-:pep:`692` type annotation for ``**kwargs`` in existing
123124codebases, it will be valuable to accept and type extra items on TypedDict so
124125that the old typing behavior can be supported in combination with ``Unpack ``.
125126
127+ Previous Discussions
128+ --------------------
129+
130+ The new features introduced in this PEP would address several long-standing feature
131+ requests in the type system. Previous discussions include:
132+
133+ - `Mypy issue <https://github.com/python/mypy/issues/7981 >`__ asking for a "final TypedDict"
134+ (2019). While the discussion focuses on the ``@final `` decorator, the underlying feature request
135+ would be addressed by this PEP.
136+ - `Mailing list thread <https://mail.python.org/archives/list/typing-sig@python.org/thread/66RITIHDQHVTUMJHH2ORSNWZ6DOPM367/ >`__
137+ asking for a way to say that a ``TypedDict `` can contain arbitrary extra keys (2020).
138+ - `Discussion <https://discuss.python.org/t/pep-692-using-typeddict-for-more-precise-kwargs-typing/17314/87 >`__
139+ about an extension of the ``Unpack `` mechanism introduced by :pep: `692 ` (2023).
140+ - `PEP 705 <https://discuss.python.org/t/pep-705-typeddict-read-only-and-other-keys/36457 >`__ in an earlier
141+ draft proposed a similar feature (2023); it was removed to keep that PEP simpler.
142+ - `Discussion <https://discuss.python.org/t/do-we-want-an-exact-typeddict-if-so-how-final-extras-never/44418 >`__
143+ about an "exact" ``TypedDict `` (2024).
144+
126145Rationale
127146=========
128147
@@ -747,12 +766,22 @@ valid definition that indicates all extra items must be ``None``.)
747766How to Teach This
748767=================
749768
750- The choice of the spelling ``"extra_items" `` is intended to make this
751- feature more understandable to new users compared to shorter alternatives like
752- ``"extra" ``.
753-
754- Details of this should be documented in both the typing spec and the
755- :mod: `typing ` documentation.
769+ The new features introduced in this PEP can be taught together with the concept
770+ of inheritance as it applies to ``TypedDict ``. A possible outline could be:
771+
772+ - Basics of ``TypedDict ``: a ``dict `` with a fixed set of keys and value types.
773+ - ``NotRequired ``, ``Required ``, and ``total=False ``: keys that may be missing.
774+ - ``ReadOnly ``: keys that cannot be modified.
775+ - Inheritance: subclasses can add new keys. As a corollary, a value of a ``TypedDict ``
776+ type may contain additional keys at runtime that are not specified in the type.
777+ - ``closed=True ``: disallowing additional keys and restricting inheritance.
778+ - ``extra_items=VT ``: allowing additional keys with a specified value type.
779+
780+ The concept of a closed ``TypedDict `` should also be cross-referenced in documentation
781+ for related concepts. For example, type narrowing with the ``in `` operator works
782+ differently, perhaps more intuitively, with closed ``TypedDict `` types. In addition, when ``Unpack ``
783+ is used for keyword arguments, a closed ``TypedDict `` can be useful to restrict the
784+ allowed keyword arguments.
756785
757786Backwards Compatibility
758787=======================
0 commit comments