Skip to content

PEP 728: Expand previous discussions and "How to teach this" #4539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

PEP 728: Expand previous discussions and "How to teach this" #4539

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 34 additions & 6 deletions peps/pep-0728.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,24 @@ Given the usage of pre-:pep:`692` type annotation for ``**kwargs`` in existing
codebases, it will be valuable to accept and type extra items on TypedDict so
that the old typing behavior can be supported in combination with ``Unpack``.

Previous Discussions
--------------------

The new features introduced in this PEP would address several long-standing feature
requests in the type system. Previous discussions include:

- `Mypy issue <https://github.com/python/mypy/issues/7981>`__ asking for a "final TypedDict"
(2019). While the discussion focuses on the ``@final`` decorator, the underlying feature request
would be addressed by this PEP.
- `Mailing list thread <https://mail.python.org/archives/list/[email protected]/thread/66RITIHDQHVTUMJHH2ORSNWZ6DOPM367/>`__
asking for a way to say that a ``TypedDict`` can contain arbitrary extra keys (2020).
- `Discussion <https://discuss.python.org/t/pep-692-using-typeddict-for-more-precise-kwargs-typing/17314/87>`__
about an extension of the ``Unpack`` mechanism introduced by :pep:`692` (2023).
- `PEP 705 <https://discuss.python.org/t/pep-705-typeddict-read-only-and-other-keys/36457>`__ in an earlier
draft proposed a similar feature (2023); it was removed to keep that PEP simpler.
- `Discussion <https://discuss.python.org/t/do-we-want-an-exact-typeddict-if-so-how-final-extras-never/44418>`__
about an "exact" ``TypedDict`` (2024).

Rationale
=========

Expand Down Expand Up @@ -747,12 +765,22 @@ valid definition that indicates all extra items must be ``None``.)
How to Teach This
=================

The choice of the spelling ``"extra_items"`` is intended to make this
feature more understandable to new users compared to shorter alternatives like
``"extra"``.

Details of this should be documented in both the typing spec and the
:mod:`typing` documentation.
The new features introduced in this PEP can be taught together with the concept
of inheritance as it applies to ``TypedDict``. A possible outline could be:

- Basics of ``TypedDict``: a ``dict`` with a fixed set of keys and value types.
- ``NotRequired``, ``Required``, and ``total=False``: keys that may be missing.
- ``ReadOnly``: keys that cannot be modified.
- Inheritance: subclasses can add new keys. As a corollary, a value of a ``TypedDict``
type may contain additional keys at runtime that are not specified in the type.
- ``closed=True``: disallowing additional keys and restricting inheritance.
- ``extra_items=VT``: allowing additional keys with a specified value type.

The concept of a closed ``TypedDict`` should also be cross-referenced in documentation
for related concepts. For example, type narrowing with the ``in`` operator works
differently, perhaps more intuitively, with closed ``TypedDict`` types. In addition, when ``Unpack``
is used for keyword arguments, a closed ``TypedDict`` can be useful to restrict the
allowed keyword arguments.

Backwards Compatibility
=======================
Expand Down