Add TYPE_CHECKING, not __type_checking__.

Author: methane

peps/pep-0781.rst

@@ -1,5 +1,5 @@
 PEP: 781
-Title: Adding __type_checking__ constant
+Title: Making ``TYPE_CHECKING`` builtin
 Author: Inada Naoki <songofacandy@gmail.com>
 Discussions-To: https://discuss.python.org/t/85728
 Status: Draft
@@ -14,12 +14,11 @@ Post-History: `11-Jan-2025 <https://discuss.python.org/t/76766>`__,
 Abstract
 ========
 
-This PEP proposes adding a new keyword, :data:`!__type_checking__`, to improve
+This PEP proposes adding a new builtin, :data:`!TYPE_CHECKING`, to improve
 the experience of writing Python code with type annotations. It is evaluated
 as ``True`` when the code is being analyzed by a static type checker, and as
 ``False`` during normal runtime execution. Unlike :data:`typing.TYPE_CHECKING`,
-which this keyword replaces, it does not require an import statement, and
-creates the opportunity for compiler optimizations, such as smaller bytecode.
+which this keyword replaces, it does not require an import statement.
 
 
 Motivation
@@ -30,7 +29,7 @@ widespread adoption. A challenge with fully-annotated code is that many
 more imports are required in order to bring the relevant name into scope,
 potentially causing import cycles without careful design. This has been
 recognized by :pep:`563` and later :pep:`649`, which introduce two different
-mechanisms for deferred evaluation of type annotations. As PEP 563 notes,
+mechanisms for deferred evaluation of type annotations. As :pep:`563` notes,
 "type hints are ... not computationally free". The :data:`typing.TYPE_CHECKING`
 constant was thus introduced__, initially to aid in breaking cyclic imports.
 
@@ -51,62 +50,67 @@ third-party tools in the ecosystem to standardize on a single behavior
 with guaranteed semantics, as for example some static type checkers currently
 do not permit local constants, only recognizing ``typing.TYPE_CHECKING``.
 
-Furthermore, this allows compilers to eliminate type-checking-only code at
-compile time, as the constant is guaranteed to be ``False`` and cannot be
-reassigned. This reduces bytecode size and memory usage, and would help with
-writing type-annotated code for memory-constrained environments such as WASM
-or MicroPython.
 
+Specification
+=============
 
-Rationale
-=========
+``TYPE_CHECKING`` is a built-in constant and its value is ``False``.
+Unlike ``True``, ``False``, ``None``, and ``__debug__``, ``TYPE_CHECKING`` is
+not a real constant; assigning to it will not raise a ``SyntaxError``.
 
-Using Keyword
--------------
+Static type checkers must treat ``TYPE_CHECKING`` as ``True``, similar to
+:data:`typing.TYPE_CHECKING`.
 
-Avoiding the addition of a new :ref:`keyword <python:keywords>`
-(like :data:`__debug__`) would be attractive because more keywords means
-a more complex language.
+If this PEP is accepted, the new ``TYPE_CHECKING`` constant will be
+the preferred approach, instead of the existing ``typing.TYPE_CHECKING``.
+However, ``typing.TYPE_CHECKING`` will not be deprecated in the foreseeable
+future.
 
-However, adding a constant without a keyword (like :data:`__debug__`) requires
-special handling in both the compiler and runtime.
 
-By implementing ``__type_checking__`` the same way as ``False``, we avoid the
-need for the special handling.
-Therefore, making it a keyword is the simpler approach.
+Backwards Compatibility
+=======================
 
+Since ``TYPE_CHECKING`` doesn't prohibit assignment, existing code using
+``TYPE_CHECKING`` will continue to work.
 
-Specification
-=============
+.. code-block:: python
 
-``__type_checking__`` is a :ref:`keyword <python:keywords>` and its value is
-``False``.
-It can be used in the same way as ``False``, except it cannot be used as
-a matching pattern.
+   # These code will work as before
+   TYPE_CHECKING = False
+   from typing import TYPE_CHECKING
 
-Static type checkers must treat ``__type_checking__`` as ``True``,
-similar to :data:`typing.TYPE_CHECKING`.
 
-If this PEP is accepted, ``__type_checking__`` will be the preferred approach,
-instead of ``typing.TYPE_CHECKING``. However, ``typing.TYPE_CHECKING`` will not
-be deprecated.
-Instead, it will be implemented as ``TYPE_CHECKING = __type_checking__``,
-allowing future type checkers to focus on only handling ``__type_checking__``.
+User can remove the assingment to ``TYPE_CHECKING`` after they stop using
+Python before 3.14.
 
 
 How to Teach This
 =================
 
-* Use ``__type_checking__`` for skipping type-checking code at runtime.
-* Use :data:`typing.TYPE_CHECKING` to support Python versions before 3.14.
+* Use ``if TYPE_CHECKING:`` for skipping type-checking code at runtime.
+* Use ``from typing import TYPE_CHECKING`` to support Python versions before 3.14.
 * Workarounds like ``TYPE_CHECKING = False`` or ``if False:  # TYPE_CHECKING``
-  are not recommended since Python 3.14.
+  are continued to work, but not recommended.
 
 
 Reference Implementation
 ========================
 
-* `python/cpython#131641 <https://github.com/python/cpython/pull/131641>`__
+* `python/cpython#131793 <https://github.com/python/cpython/pull/131793>`__
+
+
+Rejected Ideas
+==============
+
+Eliminate type-checking-only Code
+---------------------------------
+
+It is considered to add real constant named ``__type_checking__``
+to eliminate type-checking-only code at compile time.
+
+However, adding real constant to language increase complexity of the language.
+Benefit from eliminating type-checking-only code is estimated to be not enough
+to justify the complexity.
 
 
 Copyright