https://github.com/python/cpython/commit/d7256ae4d781932b3b43b162e8425abdb134afa6
commit: d7256ae4d781932b3b43b162e8425abdb134afa6
branch: main
author: larryhastings <[email protected]>
committer: larryhastings <[email protected]>
date: 2025-05-27T23:08:52-07:00
summary:
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.
files:
M Doc/library/typing.rst
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index dd8ea3c364f49a..69df09c779592a 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
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
