Skip to content

Commit

Permalink
[3.12] Enhance TypedDict docs around required/optional keys (GH-109547)…
Browse files Browse the repository at this point in the history
… (#109982)

Enhance TypedDict docs around required/optional keys (GH-109547)

As discussed in comments to GH-109544, the semantics of this attribute
are somewhat confusing. Add a note explaining its limitations and
steering users towards __required_keys__ and __optional_keys__ instead.
(cherry picked from commit f49958c)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
  • Loading branch information
miss-islington and JelleZijlstra committed Oct 4, 2023
1 parent bbce8bd commit ee2f2bd
Showing 1 changed file with 15 additions and 0 deletions.
15 changes: 15 additions & 0 deletions Doc/library/typing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2392,6 +2392,13 @@ types.
>>> Point3D.__total__
True

This attribute reflects *only* the value of the ``total`` argument
to the current ``TypedDict`` class, not whether the class is semantically
total. For example, a ``TypedDict`` with ``__total__`` set to True may
have keys marked with :data:`NotRequired`, or it may inherit from another
``TypedDict`` with ``total=False``. Therefore, it is generally better to use
:attr:`__required_keys__` and :attr:`__optional_keys__` for introspection.

.. attribute:: __required_keys__

.. versionadded:: 3.9
Expand Down Expand Up @@ -2427,6 +2434,14 @@ types.

.. versionadded:: 3.9

.. note::

If ``from __future__ import annotations`` is used or if annotations
are given as strings, annotations are not evaluated when the
``TypedDict`` is defined. Therefore, the runtime introspection that
``__required_keys__`` and ``__optional_keys__`` rely on may not work
properly, and the values of the attributes may be incorrect.

See :pep:`589` for more examples and detailed rules of using ``TypedDict``.

.. versionadded:: 3.8
Expand Down

0 comments on commit ee2f2bd

Please sign in to comment.