PEP 781: Adding __type_checking__ constant

Author: methane

peps/pep-0781.rst

@@ -0,0 +1,163 @@
+PEP: 781
+Title: Adding __type_checking__ constant
+Author: Inada Naoki <songofacandy@gmail.com>
+Discussions-To: https://discuss.python.org/t/85728
+Status: Draft
+Type: Standards Track
+Topic: Typing
+Created: [24-Mar-2025]
+Python-Version: 3.14
+
+
+Abstract
+========
+
+This PEP proposes adding a new keyword ``__type_checking__`` that serves the
+same purpose as ``typing.TYPE_CHECKING``.
+This constant is ``True`` when the code is being analyzed by a static type
+checker, and ``False`` during normal runtime execution.
+
+
+Motivation
+==========
+
+For libraries that may be used in scripts where startup time is critical,
+the time taken to import the ``typing`` module cannot be ignored.
+
+To avoid importing ``typing``, developers currently define a module-level
+variable ``TYPE_CHECKING = False`` or use code like
+``if False:  # TYPE_CHECKING``.
+Providing a standard method will allow many tools to implement the same
+behavior consistently.
+
+Furthermore, this allows compilers to eliminate type-checking-only code at
+compile time. This reduces bytecode size and memory usage,
+and would help with writing type-hinted code for memory-constrained
+environments like WASM or micropython.
+
+
+Specification
+=============
+
+``__type_checking__`` is a keyword and its value is ``False``.
+It can be used in the same way as ``False``, except it can not be used as
+a matching pattern.
+
+
+Rational
+========
+
+Difference from ``__debug__``
+-----------------------------
+
+``__debug__`` is not a keyword, but a built-in constant.
+Not adding a new keyword is attractive, but it requires special handling in
+both the compiler and the runtime to change the value of the constant
+depending on the startup option.
+
+By implementing ``__type_checking__`` the same way as ``False``,
+we avoid the need for special handling in both the compiler and runtime.
+Therefore, making it a keyword is the simpler approach.
+
+
+How to teach this
+=================
+
+Add this note to the ``typing.TYPE_CHECKING`` document:
+
+> If you don't want to import ``typing``, you can use ``__type_checking__``.
+> Workarounds like ``TYPE_CHECKING = False`` or
+> ``if False:  # TYPE_CHECKING`` are not recommended since Python 3.14.
+
+
+Resources
+=========
+
+.. [1] Previous discussion: https://discuss.python.org/t/76766
+.. [2] Reference Implementation: https://github.com/python/cpython/pull/131641
+
+
+PEP: 781
+Title: Adding __type_checking__ constant
+Author: Inada Naoki <songofacandy@gmail.com>
+Discussions-To:
+Status: Draft
+Type: Standards Track
+Topic: Typing
+Created: [24-Mar-2025]
+Python-Version: 3.14
+
+
+Abstract
+========
+
+This PEP proposes adding a new keyword ``__type_checking__`` that serves the
+same purpose as ``typing.TYPE_CHECKING``.
+This constant is ``True`` when the code is being analyzed by a static type
+checker, and ``False`` during normal runtime execution.
+
+
+Motivation
+==========
+
+For libraries that may be used in scripts where startup time is critical,
+the time taken to import the ``typing`` module cannot be ignored.
+
+To avoid importing ``typing``, developers currently define a module-level
+variable ``TYPE_CHECKING = False`` or use code like
+``if False:  # TYPE_CHECKING``.
+Providing a standard method will allow many tools to implement the same
+behavior consistently.
+
+Furthermore, this allows compilers to eliminate type-checking-only code at
+compile time. This reduces bytecode size and memory usage,
+and would help with writing type-hinted code for memory-constrained
+environments like WASM or micropython.
+
+
+Specification
+=============
+
+``__type_checking__`` is a keyword and its value is ``False``.
+It can be used in the same way as ``False``, except it can not be used as
+a matching pattern.
+
+
+Rational
+========
+
+Difference from ``__debug__``
+-----------------------------
+
+``__debug__`` is not a keyword, but a built-in constant.
+Not adding a new keyword is attractive, but it requires special handling in
+both the compiler and the runtime to change the value of the constant
+depending on the startup option.
+
+By implementing ``__type_checking__`` the same way as ``False``,
+we avoid the need for special handling in both the compiler and runtime.
+Therefore, making it a keyword is the simpler approach.
+
+
+How to teach this
+=================
+
+Add this note to the ``typing.TYPE_CHECKING`` document:
+
+> If you don't want to import ``typing``, you can use ``__type_checking__``.
+> Workaround like ``TYPE_CHECKING = False`` or
+> ``if False:  # TYPE_CHECKING`` are not recommended since Python 3.14.
+
+
+Resources
+=========
+
+* Previous discussion: https://discuss.python.org/t/76766
+* Reference Implementation: https://github.com/python/cpython/pull/131641
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.