gh-116126: Implement PEP 696 (#116129) · python/cpython@ca269e5 · GitHub
Skip to content

Commit ca269e5

Browse files
JelleZijlstraAlexWaygoodpicnixzhauntsaninja
authored
gh-116126: Implement PEP 696 (#116129)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
1 parent 852263e commit ca269e5

28 files changed

Lines changed: 1924 additions & 623 deletions

‎Doc/library/ast.rst‎

Lines changed: 38 additions & 14 deletions

‎Doc/library/typing.rst‎

Lines changed: 79 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1614,7 +1614,7 @@ without the dedicated syntax, as documented below.
16141614

16151615
.. _typevar:
16161616

1617-
.. class:: TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False)
1617+
.. class:: TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)
16181618

16191619
Type variable.
16201620

@@ -1752,15 +1752,35 @@ without the dedicated syntax, as documented below.
17521752
the constraints are evaluated only when the attribute is accessed, not when
17531753
the type variable is created (see :ref:`lazy-evaluation`).
17541754

1755+
.. attribute:: __default__
1756+
1757+
The default value of the type variable, or :data:`typing.NoDefault` if it
1758+
has no default.
1759+
1760+
.. versionadded:: 3.13
1761+
1762+
.. method:: has_default()
1763+
1764+
Return whether or not the type variable has a default value. This is equivalent
1765+
to checking whether :attr:`__default__` is not the :data:`typing.NoDefault`
1766+
singleton, except that it does not force evaluation of the
1767+
:ref:`lazily evaluated <lazy-evaluation>` default value.
1768+
1769+
.. versionadded:: 3.13
1770+
17551771
.. versionchanged:: 3.12
17561772

17571773
Type variables can now be declared using the
17581774
:ref:`type parameter <type-params>` syntax introduced by :pep:`695`.
17591775
The ``infer_variance`` parameter was added.
17601776

1777+
.. versionchanged:: 3.13
1778+
1779+
Support for default values was added.
1780+
17611781
.. _typevartuple:
17621782

1763-
.. class:: TypeVarTuple(name)
1783+
.. class:: TypeVarTuple(name, default=typing.NoDefault)
17641784

17651785
Type variable tuple. A specialized form of :ref:`type variable <typevar>`
17661786
that enables *variadic* generics.
@@ -1870,14 +1890,34 @@ without the dedicated syntax, as documented below.
18701890

18711891
The name of the type variable tuple.
18721892

1893+
.. attribute:: __default__
1894+
1895+
The default value of the type variable tuple, or :data:`typing.NoDefault` if it
1896+
has no default.
1897+
1898+
.. versionadded:: 3.13
1899+
1900+
.. method:: has_default()
1901+
1902+
Return whether or not the type variable tuple has a default value. This is equivalent
1903+
to checking whether :attr:`__default__` is not the :data:`typing.NoDefault`
1904+
singleton, except that it does not force evaluation of the
1905+
:ref:`lazily evaluated <lazy-evaluation>` default value.
1906+
1907+
.. versionadded:: 3.13
1908+
18731909
.. versionadded:: 3.11
18741910

18751911
.. versionchanged:: 3.12
18761912

18771913
Type variable tuples can now be declared using the
18781914
:ref:`type parameter <type-params>` syntax introduced by :pep:`695`.
18791915

1880-
.. class:: ParamSpec(name, *, bound=None, covariant=False, contravariant=False)
1916+
.. versionchanged:: 3.13
1917+
1918+
Support for default values was added.
1919+
1920+
.. class:: ParamSpec(name, *, bound=None, covariant=False, contravariant=False, default=typing.NoDefault)
18811921

18821922
Parameter specification variable. A specialized version of
18831923
:ref:`type variables <typevar>`.
@@ -1946,6 +1986,22 @@ without the dedicated syntax, as documented below.
19461986

19471987
The name of the parameter specification.
19481988

1989+
.. attribute:: __default__
1990+
1991+
The default value of the parameter specification, or :data:`typing.NoDefault` if it
1992+
has no default.
1993+
1994+
.. versionadded:: 3.13
1995+
1996+
.. method:: has_default()
1997+
1998+
Return whether or not the parameter specification has a default value. This is equivalent
1999+
to checking whether :attr:`__default__` is not the :data:`typing.NoDefault`
2000+
singleton, except that it does not force evaluation of the
2001+
:ref:`lazily evaluated <lazy-evaluation>` default value.
2002+
2003+
.. versionadded:: 3.13
2004+
19492005
Parameter specification variables created with ``covariant=True`` or
19502006
``contravariant=True`` can be used to declare covariant or contravariant
19512007
generic types. The ``bound`` argument is also accepted, similar to
@@ -1959,6 +2015,10 @@ without the dedicated syntax, as documented below.
19592015
Parameter specifications can now be declared using the
19602016
:ref:`type parameter <type-params>` syntax introduced by :pep:`695`.
19612017

2018+
.. versionchanged:: 3.13
2019+
2020+
Support for default values was added.
2021+
19622022
.. note::
19632023
Only parameter specification variables defined in global scope can
19642024
be pickled.
@@ -3171,6 +3231,22 @@ Introspection helpers
31713231

31723232
.. versionadded:: 3.7.4
31733233

3234+
.. data:: NoDefault
3235+
3236+
A sentinel object used to indicate that a type parameter has no default
3237+
value. For example:
3238+
3239+
.. doctest::
3240+
3241+
>>> T = TypeVar("T")
3242+
>>> T.__default__ is typing.NoDefault
3243+
True
3244+
>>> S = TypeVar("S", default=None)
3245+
>>> S.__default__ is None
3246+
True
3247+
3248+
.. versionadded:: 3.13
3249+
31743250
Constant
31753251
--------
31763252

‎Doc/reference/compound_stmts.rst‎

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1620,15 +1620,18 @@ Type parameter lists
16201620

16211621
.. versionadded:: 3.12
16221622

1623+
.. versionchanged:: 3.13
1624+
Support for default values was added (see :pep:`696`).
1625+
16231626
.. index::
16241627
single: type parameters
16251628

16261629
.. productionlist:: python-grammar
16271630
type_params: "[" `type_param` ("," `type_param`)* "]"
16281631
type_param: `typevar` | `typevartuple` | `paramspec`
1629-
typevar: `identifier` (":" `expression`)?
1630-
typevartuple: "*" `identifier`
1631-
paramspec: "**" `identifier`
1632+
typevar: `identifier` (":" `expression`)? ("=" `expression`)?
1633+
typevartuple: "*" `identifier` ("=" `expression`)?
1634+
paramspec: "**" `identifier` ("=" `expression`)?
16321635

16331636
:ref:`Functions <def>` (including :ref:`coroutines <async def>`),
16341637
:ref:`classes <class>` and :ref:`type aliases <type>` may
@@ -1694,19 +1697,31 @@ evaluated in a separate :ref:`annotation scope <annotation-scopes>`.
16941697
:data:`typing.TypeVarTuple`\ s and :data:`typing.ParamSpec`\ s cannot have bounds
16951698
or constraints.
16961699

1700+
All three flavors of type parameters can also have a *default value*, which is used
1701+
when the type parameter is not explicitly provided. This is added by appending
1702+
a single equals sign (``=``) followed by an expression. Like the bounds and
1703+
constraints of type variables, the default value is not evaluated when the
1704+
object is created, but only when the type parameter's ``__default__`` attribute
1705+
is accessed. To this end, the default value is evaluated in a separate
1706+
:ref:`annotation scope <annotation-scopes>`. If no default value is specified
1707+
for a type parameter, the ``__default__`` attribute is set to the special
1708+
sentinel object :data:`typing.NoDefault`.
1709+
16971710
The following example indicates the full set of allowed type parameter declarations::
16981711

16991712
def overly_generic[
17001713
SimpleTypeVar,
1714+
TypeVarWithDefault = int,
17011715
TypeVarWithBound: int,
17021716
TypeVarWithConstraints: (str, bytes),
1703-
*SimpleTypeVarTuple,
1704-
**SimpleParamSpec,
1717+
*SimpleTypeVarTuple = (int, float),
1718+
**SimpleParamSpec = (str, bytearray),
17051719
](
17061720
a: SimpleTypeVar,
1707-
b: TypeVarWithBound,
1708-
c: Callable[SimpleParamSpec, TypeVarWithConstraints],
1709-
*d: SimpleTypeVarTuple,
1721+
b: TypeVarWithDefault,
1722+
c: TypeVarWithBound,
1723+
d: Callable[SimpleParamSpec, TypeVarWithConstraints],
1724+
*e: SimpleTypeVarTuple,
17101725
): ...
17111726

17121727
.. _generic-functions:

‎Doc/reference/executionmodel.rst‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ Annotation scopes are used in the following contexts:
205205
* Type parameter lists for :ref:`generic classes <generic-classes>`.
206206
A generic class's base classes and
207207
keyword arguments are executed within the annotation scope, but its decorators are not.
208-
* The bounds and constraints for type variables
208+
* The bounds, constraints, and default values for type parameters
209209
(:ref:`lazily evaluated <lazy-evaluation>`).
210210
* The value of type aliases (:ref:`lazily evaluated <lazy-evaluation>`).
211211

@@ -232,13 +232,17 @@ Annotation scopes differ from function scopes in the following ways:
232232
.. versionadded:: 3.12
233233
Annotation scopes were introduced in Python 3.12 as part of :pep:`695`.
234234

235+
.. versionchanged:: 3.13
236+
Annotation scopes are also used for type parameter defaults, as
237+
introduced by :pep:`696`.
238+
235239
.. _lazy-evaluation:
236240

237241
Lazy evaluation
238242
---------------
239243

240244
The values of type aliases created through the :keyword:`type` statement are
241-
*lazily evaluated*. The same applies to the bounds and constraints of type
245+
*lazily evaluated*. The same applies to the bounds, constraints, and default values of type
242246
variables created through the :ref:`type parameter syntax <type-params>`.
243247
This means that they are not evaluated when the type alias or type variable is
244248
created. Instead, they are only evaluated when doing so is necessary to resolve

‎Doc/whatsnew/3.13.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,8 @@ Interpreter improvements:
8989

9090
New typing features:
9191

92+
* :pep:`696`: Type parameters (:data:`typing.TypeVar`, :data:`typing.ParamSpec`,
93+
and :data:`typing.TypeVarTuple`) now support defaults.
9294
* :pep:`742`: :data:`typing.TypeIs` was added, providing more intuitive
9395
type narrowing behavior.
9496

@@ -850,6 +852,10 @@ typing
850852
an item of a :class:`typing.TypedDict` as read-only for type checkers.
851853
See :pep:`705` for more details.
852854

855+
* Add :data:`typing.NoDefault`, a sentinel object used to represent the defaults
856+
of some parameters in the :mod:`typing` module. (Contributed by Jelle Zijlstra in
857+
:gh:`116126`.)
858+
853859
unicodedata
854860
-----------
855861

‎Grammar/python.gram‎

Lines changed: 7 additions & 3 deletions

0 commit comments

Comments
 (0)