8000 [3.12] Enhance TypedDict docs around required/optional keys (GH-10954… · python/cpython@ee2f2bd · GitHub
[go: up one dir, main page]

Skip to content
< 8000 div class="Box-sc-g0xbh4-0 prc-PageHeader-PageHeader-sT1Hp">

Commit ee2f2bd

Browse files
[3.12] Enhance TypedDict docs around required/optional keys (GH-109547) (#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>
1 parent bbce8bd commit ee2f2bd

File tree

1 file changed

+15
-0
lines changed

1 file changed

+15
-0
lines changed

Doc/library/typing.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2392,6 +2392,13 @@ types.
23922392
>>> Point3D.__total__
23932393
True
23942394

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

23972404
.. versionadded:: 3.9
@@ -2427,6 +2434,14 @@ types.
24272434

24282435
.. versionadded:: 3.9
24292436

2437+
.. note::
2438+
2439+
If ``from __future__ import annotations`` is used or if annotations
2440+
are given as strings, annotations are not evaluated when the
2441+
``TypedDict`` is defined. Therefore, the runtime introspection that
2442+
``__required_keys__`` and ``__optional_keys__`` rely on may not work
2443+
properly, and the values of the attributes may be incorrect.
2444+
24302445
See :pep:`589` for more examples and detailed rules of using ``TypedDict``.
24312446

24322447
.. versionadded:: 3.8

0 commit comments

Comments
 (0)
0