Add Rationale section, explaining what a type expression is and why i…

…t's used
python · JelleZijlstra · Jun 16, 2024 · May 27, 2024 · May 27, 2024 · May 27, 2024
commit 11a1e88eb7c52cb200c95e23d189bcf0bfd33218
@@ -28,6 +28,8 @@ This PEP makes no Python grammar changes. Correct usage of
 type checkers and need not be enforced by Python itself at runtime.
 
 
+.. _motivation:
+
 Motivation
 ==========
 
@@ -190,20 +192,11 @@ annotation expressions as input using plain ``object``\ s which would
 .. _typing_inspect: https://github.com/ilevkivskyi/typing_inspect?tab=readme-ov-file#readme
 
 
-Specification
-=============
-
-A ``TypeExpr`` represents a :ref:`type expression <typing:type-expression>`
-such as ``str | None``, ``dict[str, int]``, or ``MyTypedDict``.
-A ``TypeExpr`` type is written as
-``TypeExpr[T]`` where ``T`` is a type or a type variable. It can also be
-written without brackets as just ``TypeExpr``, in which case a type
-checker should apply its usual type inference mechanisms to determine
-the type of its argument, possibly ``Any``.
+Rationale
+=========
 
-Type expressions include more values than 
-:ref:`annotation expressions <typing:annotation-expression>` but
-fewer values than *class objects* (``type[C]``):
+Before this PEP existed there were already a few definitions in use to describe
+different kinds of type annotations:
 
 ::
 
@@ -220,6 +213,44 @@ fewer values than *class objects* (``type[C]``):
       | Object                           | = object         
    +----------------------------------+ 
 
+-  :ref:`Class objects <typing:type-brackets>`,
+   spelled as ``type[C]``, support ``isinstance`` checks and are callable.
+
+   -  Examples: ``int``, ``str``, ``MyClass``
+
+-  :ref:`Type expressions <typing:type-expression>`
+   include any type annotation which describes a type.
+
+   -  Examples: ``list[int]``, ``MyTypedDict``, ``int | str``,
+      ``Literal['square']``, any class object
+
+-  :ref:`Annotation expressions <typing:annotation-expression>`
+   include any type annotation, including those only valid in specific contexts.
+
+   -  Examples: ``Final[int]``, ``Required[str]``, ``ClassVar[str]``,
+      any type expression
+
+``TypeExpr`` aligns with an existing definition from the above list -
+*type expression* - to avoid introducing yet another subset of type annotations
+that users of Python typing need to think about.
+
+``TypeExpr`` aligns with *type expression* specifically
+because a type expression is already used to parameterize type variables,
+which are used in combination with ``TypeIs`` and ``TypeGuard`` to enable
+the compelling examples mentioned in :ref:`Motivation <motivation>`.
+
+
+Specification
+=============
+
+A ``TypeExpr`` represents a :ref:`type expression <typing:type-expression>`
+such as ``str | None``, ``dict[str, int]``, or ``MyTypedDict``.
+A ``TypeExpr`` type is written as
+``TypeExpr[T]`` where ``T`` is a type or a type variable. It can also be
+written without brackets as just ``TypeExpr``, in which case a type
+checker should apply its usual type inference mechanisms to determine
+the type of its argument, possibly ``Any``.
+
 
 Using TypeExprs
 ---------------