From afd8037f764ddd833574628fe12d43e0f577b2ae Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Mon, 18 Sep 2023 08:53:49 -0700 Subject: [PATCH 1/2] Add note to TypedDict.__total__docs As discussed in comments to #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. --- Doc/library/typing.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 18e15f304f9f80..2358452ce85e60 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2404,6 +2404,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 From 39c49f78fe8264e4f3a7280c7e363d56a6b93b22 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Mon, 18 Sep 2023 08:59:04 -0700 Subject: [PATCH 2/2] Add another limitation --- Doc/library/typing.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 2358452ce85e60..0380aa161e3b3e 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2446,6 +2446,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