From: larryhastings <larry@hastings.org>
Date: Wed, 28 May 2025 06:08:52 +0000 (-0400)
Subject: Fix typing.TYPE_CHECKING docs to reflect PEP 649. (#134813)
X-Git-Tag: v3.15.0a1~1480
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d7256ae4d781932b3b43b162e8425abdb134afa6;p=thirdparty%2FPython%2Fcpython.git

Fix typing.TYPE_CHECKING docs to reflect PEP 649. (#134813)

typing.TYPE_CHECKING should no longer steer users towards
manual or automatic stringization (and PEP 563); PEP 649
makes all that unnecessary.
---

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index dd8ea3c364f4..69df09c77959 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -3530,28 +3530,32 @@ Constant
 .. data:: TYPE_CHECKING
 
    A special constant that is assumed to be ``True`` by 3rd party static
-   type checkers. It is ``False`` at runtime.
+   type checkers. It's ``False`` at runtime.
+
+   A module which is expensive to import, and which only contain types
+   used for typing annotations, can be safely imported inside an
+   ``if TYPE_CHECKING:`` block.  This prevents the module from actually
+   being imported at runtime; annotations aren't eagerly evaluated
+   (see :pep:`649`) so using undefined symbols in annotations is
+   harmless--as long as you don't later examine them.
+   Your static type analysis tool will set ``TYPE_CHECKING`` to
+   ``True`` during static type analysis, which means the module will
+   be imported and the types will be checked properly during such analysis.
 
    Usage::
 
       if TYPE_CHECKING:
           import expensive_mod
 
-      def fun(arg: 'expensive_mod.SomeType') -> None:
+      def fun(arg: expensive_mod.SomeType) -> None:
           local_var: expensive_mod.AnotherType = other_fun()
 
-   The first type annotation must be enclosed in quotes, making it a
-   "forward reference", to hide the ``expensive_mod`` reference from the
-   interpreter runtime.  Type annotations for local variables are not
-   evaluated, so the second annotation does not need to be enclosed in quotes.
-
-   .. note::
-
-      If ``from __future__ import annotations`` is used,
-      annotations are not evaluated at function definition time.
-      Instead, they are stored as strings in ``__annotations__``.
-      This makes it unnecessary to use quotes around the annotation
-      (see :pep:`563`).
+   If you occasionally need to examine type annotations at runtime
+   which may contain undefined symbols, use
+   :meth:`annotationlib.get_annotations` with a ``format`` parameter
+   of :attr:`annotationlib.Format.STRING` or
+   :attr:`annotationlib.Format.FORWARDREF` to safely retrieve the
+   annotations without raising :exc:`NameError`.
 
    .. versionadded:: 3.5.2