mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-07 19:35:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

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

Browse source 
typing.TYPE_CHECKING should no longer steer users towards
manual or automatic stringization (and PEP 563); PEP 649
makes all that unnecessary.
This commit is contained in:
larryhastings 2025-05-28 02:08:52 -04:00 • committed by GitHub
parent fbbbc10055
commit d7256ae4d7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 18 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

32
Doc/library/typing.rst
View file

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