From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Wed, 27 Sep 2023 17:35:46 +0000 (-0700)
Subject: Enhance TypedDict docs around required/optional keys (#109547)
X-Git-Tag: v3.13.0a1~264
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f49958c886a2f2608f1008186d588efc2a98b445;p=thirdparty%2FPython%2Fcpython.git

Enhance TypedDict docs around required/optional keys (#109547)

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.
---

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index e63b83993182..8f6919322012 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
@@ -2439,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