gh-116126: Implement PEP 696

Doc/library/ast.rst

@@ -1798,23 +1798,25 @@ Type parameters
 :ref:`Type parameters <type-params>` can exist on classes, functions, and type
 aliases.
 
-.. class:: TypeVar(name, bound)
+.. class:: TypeVar(name, bound, default_value)
 
-   A :class:`typing.TypeVar`. ``name`` is the name of the type variable.
-   ``bound`` is the bound or constraints, if any. If ``bound`` is a :class:`Tuple`,
-   it represents constraints; otherwise it represents the bound.
+   A :class:`typing.TypeVar`. *name* is the name of the type variable.
+   *bound* is the bound or constraints, if any. If *bound* is a :class:`Tuple`,
+   it represents constraints; otherwise it represents the bound. *default_value*
+   is the default value, if any.
 
    .. doctest::
 
-        >>> print(ast.dump(ast.parse("type Alias[T: int] = list[T]"), indent=4))
+        >>> print(ast.dump(ast.parse("type Alias[T: int = bool] = list[T]"), indent=4))
         Module(
             body=[
                 TypeAlias(
                     name=Name(id='Alias', ctx=Store()),
                     type_params=[
                         TypeVar(
                             name='T',
-                            bound=Name(id='int', ctx=Load()))],
+                            bound=Name(id='int', ctx=Load()),
+                            default_value=Name(id='bool', ctx=Load()))],
                     value=Subscript(
                         value=Name(id='list', ctx=Load()),
                         slice=Name(id='T', ctx=Load()),
@@ -1823,19 +1825,29 @@ aliases.
 
    .. versionadded:: 3.12
 
-.. class:: ParamSpec(name)
+   .. versionchanged:: 3.13
+      Added ``default_value``.
+
+.. class:: ParamSpec(name, default_value)
 
-   A :class:`typing.ParamSpec`. ``name`` is the name of the parameter specification.
+   A :class:`typing.ParamSpec`. *name* is the name of the parameter specification.
+   *default_value* is the default value, if any.
 
    .. doctest::
 
-        >>> print(ast.dump(ast.parse("type Alias[**P] = Callable[P, int]"), indent=4))
+        >>> print(ast.dump(ast.parse("type Alias[**P = (int, str)] = Callable[P, int]"), indent=4))
         Module(
             body=[
                 TypeAlias(
                     name=Name(id='Alias', ctx=Store()),
                     type_params=[
-                        ParamSpec(name='P')],
+                        ParamSpec(
+                            name='P',
+                            default_value=Tuple(
+                                elts=[
+                                    Name(id='int', ctx=Load()),
+                                    Name(id='str', ctx=Load())],
+                                ctx=Load()))],
                     value=Subscript(
                         value=Name(id='Callable', ctx=Load()),
                         slice=Tuple(
@@ -1848,19 +1860,25 @@ aliases.
 
    .. versionadded:: 3.12
 
-.. class:: TypeVarTuple(name)
+   .. versionchanged:: 3.13
+      Added ``default_value``.
+
+.. class:: TypeVarTuple(name, default_value)
 
-   A :class:`typing.TypeVarTuple`. ``name`` is the name of the type variable tuple.
+   A :class:`typing.TypeVarTuple`. *name* is the name of the type variable tuple.
+   *default_value* is the default value, if any.
 
    .. doctest::
 
-        >>> print(ast.dump(ast.parse("type Alias[*Ts] = tuple[*Ts]"), indent=4))
+        >>> print(ast.dump(ast.parse("type Alias[*Ts = ()] = tuple[*Ts]"), indent=4))
         Module(
             body=[
                 TypeAlias(
                     name=Name(id='Alias', ctx=Store()),
                     type_params=[
-                        TypeVarTuple(name='Ts')],
+                        TypeVarTuple(
+                            name='Ts',
+                            default_value=Tuple(elts=[], ctx=Load()))],
                     value=Subscript(
                         value=Name(id='tuple', ctx=Load()),
                         slice=Tuple(
@@ -1874,6 +1892,9 @@ aliases.
 
    .. versionadded:: 3.12
 
+   .. versionchanged:: 3.13
+      Added ``default_value``.
+
 Function and class definitions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Doc/library/typing.rst

@@ -1616,7 +1616,7 @@ without the dedicated syntax, as documented below.
 
 .. _typevar:
 
-.. class:: TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False)
+.. class:: TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False, default=<unrepresentable>)
 
    Type variable.
 
@@ -1754,15 +1754,27 @@ without the dedicated syntax, as documented below.
          the constraints are evaluated only when the attribute is accessed, not when
          the type variable is created (see :ref:`lazy-evaluation`).
 
+   .. attribute:: __default__
+
+      The default value of the type variable, if any. This attribute is ``None``
+      if the type variable has no default, and :class:`types.NoneType`
+      if the default is set to ``None``.
+
+      .. versionadded:: 3.13
+
    .. versionchanged:: 3.12
 
       Type variables can now be declared using the
       :ref:`type parameter <type-params>` syntax introduced by :pep:`695`.
       The ``infer_variance`` parameter was added.
 
+   .. versionchanged:: 3.13
+
+      Support for default values was added.
+
 .. _typevartuple:
 
-.. class:: TypeVarTuple(name)
+.. class:: TypeVarTuple(name, default=<unrepresentable>)
 
    Type variable tuple. A specialized form of :ref:`type variable <typevar>`
    that enables *variadic* generics.
@@ -1872,14 +1884,26 @@ without the dedicated syntax, as documented below.
 
       The name of the type variable tuple.
 
+   .. attribute:: __default__
+
+      The default value of the type variable tuple, if any. This attribute is ``None``
+      if the type variable tuple has no default, and :class:`types.NoneType`
+      if the default is set to ``None``.
+
+      .. versionadded:: 3.13
+
    .. versionadded:: 3.11
 
    .. versionchanged:: 3.12
 
       Type variable tuples can now be declared using the
       :ref:`type parameter <type-params>` syntax introduced by :pep:`695`.
 
-.. class:: ParamSpec(name, *, bound=None, covariant=False, contravariant=False)
+   .. versionchanged:: 3.13
+
+      Support for default values was added.
+
+.. class:: ParamSpec(name, *, bound=None, covariant=False, contravariant=False, default=<unrepresentable>)
 
    Parameter specification variable.  A specialized version of
    :ref:`type variables <typevar>`.
@@ -1948,6 +1972,14 @@ without the dedicated syntax, as documented below.
 
       The name of the parameter specification.
 
+   .. attribute:: __default__
+
+      The default value of the parameter specification, if any. This attribute is ``None``
+      if the parameter specification has no default, and :class:`types.NoneType`
+      if the default is set to ``None``.
+
+      .. versionadded:: 3.13
+
    Parameter specification variables created with ``covariant=True`` or
    ``contravariant=True`` can be used to declare covariant or contravariant
    generic types.  The ``bound`` argument is also accepted, similar to
@@ -1961,6 +1993,10 @@ without the dedicated syntax, as documented below.
       Parameter specifications can now be declared using the
       :ref:`type parameter <type-params>` syntax introduced by :pep:`695`.
 
+   .. versionchanged:: 3.13
+
+      Support for default values was added.
+
    .. note::
       Only parameter specification variables defined in global scope can
       be pickled.

Doc/reference/compound_stmts.rst

@@ -1620,15 +1620,18 @@ Type parameter lists
 
 .. versionadded:: 3.12
 
+.. versionchanged:: 3.13
+   Support for default values was added (see :pep:`696`).
+
 .. index::
    single: type parameters
 
 .. productionlist:: python-grammar
    type_params: "[" `type_param` ("," `type_param`)* "]"
    type_param: `typevar` | `typevartuple` | `paramspec`
-   typevar: `identifier` (":" `expression`)?
-   typevartuple: "*" `identifier`
-   paramspec: "**" `identifier`
+   typevar: `identifier` (":" `expression`)? ("=" `expression`)?
+   typevartuple: "*" `identifier` ("=" `expression`)?
+   paramspec: "**" `identifier` ("=" `expression`)?
 
 :ref:`Functions <def>` (including :ref:`coroutines <async def>`),
 :ref:`classes <class>` and :ref:`type aliases <type>` may
@@ -1694,19 +1697,29 @@ evaluated in a separate :ref:`annotation scope <annotation-scopes>`.
 :data:`typing.TypeVarTuple`\ s and :data:`typing.ParamSpec`\ s cannot have bounds
 or constraints.
 
+All three flavors of type parameters can also have a *default value*, which is used
+when the type parameter is not explicitly provided. This is added by appending
+a single equals sign (``=``) followed by an expression. Like the bounds and
+constraints of type variables, the default value is not evaluated when the
+object is created, but only when the type parameter's ``__default__`` attribute
+is accessed. To this end, the default value is evaluated in a separate
+:ref:`annotation scope <annotation-scopes>`.
+
 The following example indicates the full set of allowed type parameter declarations::
 
    def overly_generic[
       SimpleTypeVar,
+      TypeVarWithDefault = int,
       TypeVarWithBound: int,
       TypeVarWithConstraints: (str, bytes),
-      *SimpleTypeVarTuple,
-      **SimpleParamSpec,
+      *SimpleTypeVarTuple = (int, float),
+      **SimpleParamSpec = (str, bytearray),
    ](
       a: SimpleTypeVar,
-      b: TypeVarWithBound,
-      c: Callable[SimpleParamSpec, TypeVarWithConstraints],
-      *d: SimpleTypeVarTuple,
+      b: TypeVarWithDefault,
+      c: TypeVarWithBound,
+      d: Callable[SimpleParamSpec, TypeVarWithConstraints],
+      *e: SimpleTypeVarTuple,
    ): ...
 
 .. _generic-functions:

Doc/reference/executionmodel.rst

@@ -205,7 +205,7 @@ Annotation scopes are used in the following contexts:
 * Type parameter lists for :ref:`generic classes <generic-classes>`.
   A generic class's base classes and
   keyword arguments are executed within the annotation scope, but its decorators are not.
-* The bounds and constraints for type variables
+* The bounds, constraints, and default values for type parameters
   (:ref:`lazily evaluated <lazy-evaluation>`).
 * The value of type aliases (:ref:`lazily evaluated <lazy-evaluation>`).
 
@@ -232,13 +232,17 @@ Annotation scopes differ from function scopes in the following ways:
 .. versionadded:: 3.12
    Annotation scopes were introduced in Python 3.12 as part of :pep:`695`.
 
+.. versionchanged:: 3.13
+   Annotation scopes are now also used for type parameter defaults, as
+   introduced by :pep:`696`.
+
 .. _lazy-evaluation:
 
 Lazy evaluation
 ---------------
 
 The values of type aliases created through the :keyword:`type` statement are
-*lazily evaluated*. The same applies to the bounds and constraints of type
+*lazily evaluated*. The same applies to the bounds, constraints, and default values of type
 variables created through the :ref:`type parameter syntax <type-params>`.
 This means that they are not evaluated when the type alias or type variable is
 created. Instead, they are only evaluated when doing so is necessary to resolve

Doc/whatsnew/3.13.rst

@@ -89,6 +89,8 @@ Interpreter improvements:
 
 New typing features:
 
+* :pep:`696`: Type parameters (:data:`typing.TypeVar`, :data:`typing.ParamSpec`,
+  and :data:`typing.TypeVarTuple`) now support defaults.
 * :pep:`742`: :data:`typing.TypeIs` was added, providing more intuitive
   type narrowing behavior.
 

Grammar/python.gram

@@ -644,21 +644,25 @@ type_params[asdl_type_param_seq*]: '[' t=type_param_seq  ']' {
 type_param_seq[asdl_type_param_seq*]: a[asdl_type_param_seq*]=','.type_param+ [','] { a }
 
 type_param[type_param_ty] (memo):
-    | a=NAME b=[type_param_bound] { _PyAST_TypeVar(a->v.Name.id, b, EXTRA) }
+    | a=NAME b=[type_param_bound] c=[type_param_default] { _PyAST_TypeVar(a->v.Name.id, b, c, EXTRA) }
     | '*' a=NAME colon=':' e=expression {
             RAISE_SYNTAX_ERROR_STARTING_FROM(colon, e->kind == Tuple_kind
                 ? "cannot use constraints with TypeVarTuple"
                 : "cannot use bound with TypeVarTuple")
         }
-    | '*' a=NAME { _PyAST_TypeVarTuple(a->v.Name.id, EXTRA) }
+    | '*' a=NAME b=[type_param_starred_default] { _PyAST_TypeVarTuple(a->v.Name.id, b, EXTRA) }
     | '**' a=NAME colon=':' e=expression {
             RAISE_SYNTAX_ERROR_STARTING_FROM(colon, e->kind == Tuple_kind
                 ? "cannot use constraints with ParamSpec"
                 : "cannot use bound with ParamSpec")
         }
-    | '**' a=NAME { _PyAST_ParamSpec(a->v.Name.id, EXTRA) }
+    | '**' a=NAME b=[type_param_default] { _PyAST_ParamSpec(a->v.Name.id, b, EXTRA) }
 
 type_param_bound[expr_ty]: ':' e=expression { e }
+type_param_default[expr_ty]: '=' e=expression {
+    CHECK_VERSION(expr_ty, 13, "Type parameter defaults are", e) }
+type_param_starred_default[expr_ty]: '=' e=star_expression {
+    CHECK_VERSION(expr_ty, 13, "Type parameter defaults are", e) }
 
 # EXPRESSIONS
 # -----------

Include/internal/pycore_intrinsics.h

@@ -28,8 +28,9 @@
 #define INTRINSIC_TYPEVAR_WITH_BOUND             2
 #define INTRINSIC_TYPEVAR_WITH_CONSTRAINTS       3
 #define INTRINSIC_SET_FUNCTION_TYPE_PARAMS       4
+#define INTRINSIC_SET_TYPEPARAM_DEFAULT          5
 
-#define MAX_INTRINSIC_2                          4
+#define MAX_INTRINSIC_2                          5
 
 typedef PyObject *(*intrinsic_func1)(PyThreadState* tstate, PyObject *value);
 typedef PyObject *(*intrinsic_func2)(PyThreadState* tstate, PyObject *value1, PyObject *value2);

Include/internal/pycore_typevarobject.h

@@ -13,6 +13,7 @@ extern PyObject *_Py_make_paramspec(PyThreadState *, PyObject *);
 extern PyObject *_Py_make_typevartuple(PyThreadState *, PyObject *);
 extern PyObject *_Py_make_typealias(PyThreadState *, PyObject *);
 extern PyObject *_Py_subscript_generic(PyThreadState *, PyObject *);
+extern PyObject *_Py_set_typeparam_default(PyThreadState *, PyObject *, PyObject *);
 extern int _Py_initialize_generic(PyInterpreterState *);
 extern void _Py_clear_generic_types(PyInterpreterState *);