Skip to content

Commit dcee0aa

Browse files
miss-islingtonJelleZijlstraAlexWaygood
authored
[3.12] gh-103921: Document PEP 695 (GH-104642) (#104989)
(cherry picked from commit 060277d) Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
1 parent bb1e57e commit dcee0aa

11 files changed

+1234
-302
lines changed

‎Doc/library/ast.rst

+100-2
Original file line numberDiff line numberDiff line change
@@ -917,6 +917,25 @@ Statements
917917
type_ignores=[])
918918

919919

920+
.. class:: TypeAlias(name, type_params, value)
921+
922+
A :ref:`type alias <type-aliases>` created through the :keyword:`type`
923+
statement. ``name`` is the name of the alias, ``type_params`` is a list of
924+
:ref:`type parameters <ast-type-params>`, and ``value`` is the value of the
925+
type alias.
926+
927+
.. doctest::
928+
929+
>>> print(ast.dump(ast.parse('type Alias = int'), indent=4))
930+
Module(
931+
body=[
932+
TypeAlias(
933+
name=Name(id='Alias', ctx=Store()),
934+
type_params=[],
935+
value=Name(id='int', ctx=Load()))],
936+
type_ignores=[])
937+
938+
920939
Other statements which are only applicable inside functions or loops are
921940
described in other sections.
922941

@@ -1644,15 +1663,93 @@ Pattern matching
16441663
value=Constant(value=Ellipsis))])])],
16451664
type_ignores=[])
16461665

1666+
.. _ast-type-params:
1667+
1668+
Type parameters
1669+
^^^^^^^^^^^^^^^
1670+
1671+
:ref:`Type parameters <type-params>` can exist on classes, functions, and type
1672+
aliases.
1673+
1674+
.. class:: TypeVar(name, bound)
1675+
1676+
A :class:`typing.TypeVar`. ``name`` is the name of the type variable.
1677+
``bound`` is the bound or constraints, if any. If ``bound`` is a :class:`Tuple`,
1678+
it represents constraints; otherwise it represents the bound.
1679+
1680+
.. doctest::
1681+
1682+
>>> print(ast.dump(ast.parse("type Alias[T: int] = list[T]"), indent=4))
1683+
Module(
1684+
body=[
1685+
TypeAlias(
1686+
name=Name(id='Alias', ctx=Store()),
1687+
type_params=[
1688+
TypeVar(
1689+
name='T',
1690+
bound=Name(id='int', ctx=Load()))],
1691+
value=Subscript(
1692+
value=Name(id='list', ctx=Load()),
1693+
slice=Name(id='T', ctx=Load()),
1694+
ctx=Load()))],
1695+
type_ignores=[])
1696+
1697+
.. class:: ParamSpec(name)
1698+
1699+
A :class:`typing.ParamSpec`. ``name`` is the name of the parameter specification.
1700+
1701+
.. doctest::
1702+
1703+
>>> print(ast.dump(ast.parse("type Alias[**P] = Callable[P, int]"), indent=4))
1704+
Module(
1705+
body=[
1706+
TypeAlias(
1707+
name=Name(id='Alias', ctx=Store()),
1708+
type_params=[
1709+
ParamSpec(name='P')],
1710+
value=Subscript(
1711+
value=Name(id='Callable', ctx=Load()),
1712+
slice=Tuple(
1713+
elts=[
1714+
Name(id='P', ctx=Load()),
1715+
Name(id='int', ctx=Load())],
1716+
ctx=Load()),
1717+
ctx=Load()))],
1718+
type_ignores=[])
1719+
1720+
.. class:: TypeVarTuple(name)
1721+
1722+
A :class:`typing.TypeVarTuple`. ``name`` is the name of the type variable tuple.
1723+
1724+
.. doctest::
1725+
1726+
>>> print(ast.dump(ast.parse("type Alias[*Ts] = tuple[*Ts]"), indent=4))
1727+
Module(
1728+
body=[
1729+
TypeAlias(
1730+
name=Name(id='Alias', ctx=Store()),
1731+
type_params=[
1732+
TypeVarTuple(name='Ts')],
1733+
value=Subscript(
1734+
value=Name(id='tuple', ctx=Load()),
1735+
slice=Tuple(
1736+
elts=[
1737+
Starred(
1738+
value=Name(id='Ts', ctx=Load()),
1739+
ctx=Load())],
1740+
ctx=Load()),
1741+
ctx=Load()))],
1742+
type_ignores=[])
16471743

16481744
Function and class definitions
16491745
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16501746

1651-
.. class:: FunctionDef(name, args, body, decorator_list, returns, type_comment)
1747+
.. class:: FunctionDef(name, type_params, args, body, decorator_list, returns, type_comment)
16521748

16531749
A function definition.
16541750

16551751
* ``name`` is a raw string of the function name.
1752+
* ``type_params`` is a list of :ref:`type parameters <ast-type-params>`.
16561753
* ``args`` is an :class:`arguments` node.
16571754
* ``body`` is the list of nodes inside the function.
16581755
* ``decorator_list`` is the list of decorators to be applied, stored outermost
@@ -1820,11 +1917,12 @@ Function and class definitions
18201917
type_ignores=[])
18211918

18221919

1823-
.. class:: ClassDef(name, bases, keywords, body, decorator_list)
1920+
.. class:: ClassDef(name, type_params, bases, keywords, body, decorator_list)
18241921

18251922
A class definition.
18261923

18271924
* ``name`` is a raw string for the class name
1925+
* ``type_params`` is a list of :ref:`type parameters <ast-type-params>`.
18281926
* ``bases`` is a list of nodes for explicitly specified base classes.
18291927
* ``keywords`` is a list of :class:`keyword` nodes, principally for 'metaclass'.
18301928
Other keywords will be passed to the metaclass, as per `PEP-3115

‎Doc/library/dis.rst

+91-20
Original file line numberDiff line numberDiff line change
@@ -188,9 +188,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
188188
For a module, it disassembles all functions. For a class, it disassembles
189189
all methods (including class and static methods). For a code object or
190190
sequence of raw bytecode, it prints one line per bytecode instruction.
191-
It also recursively disassembles nested code objects (the code of
192-
comprehensions, generator expressions and nested functions, and the code
193-
used for building nested classes).
191+
It also recursively disassembles nested code objects. These can include
192+
generator expressions, nested functions, the bodies of nested classes,
193+
and the code objects used for :ref:`annotation scopes <annotation-scopes>`.
194194
Strings are first compiled to code objects with the :func:`compile`
195195
built-in function before being disassembled. If no object is provided, this
196196
function disassembles the last traceback.
@@ -926,6 +926,27 @@ iterations of the loop.
926926
.. opcode:: LOAD_NAME (namei)
927927

928928
Pushes the value associated with ``co_names[namei]`` onto the stack.
929+
The name is looked up within the locals, then the globals, then the builtins.
930+
931+
932+
.. opcode:: LOAD_LOCALS
933+
934+
Pushes a reference to the locals dictionary onto the stack. This is used
935+
to prepare namespace dictionaries for :opcode:`LOAD_FROM_DICT_OR_DEREF`
936+
and :opcode:`LOAD_FROM_DICT_OR_GLOBALS`.
937+
938+
.. versionadded:: 3.12
939+
940+
941+
.. opcode:: LOAD_FROM_DICT_OR_GLOBALS (i)
942+
943+
Pops a mapping off the stack and looks up the value for ``co_names[namei]``.
944+
If the name is not found there, looks it up in the globals and then the builtins,
945+
similar to :opcode:`LOAD_GLOBAL`.
946+
This is used for loading global variables in
947+
:ref:`annotation scopes <annotation-scopes>` within class bodies.
948+
949+
.. versionadded:: 3.12
929950

930951

931952
.. opcode:: BUILD_TUPLE (count)
@@ -1243,16 +1264,17 @@ iterations of the loop.
12431264
``i`` is no longer offset by the length of ``co_varnames``.
12441265

12451266

1246-
.. opcode:: LOAD_CLASSDEREF (i)
1267+
.. opcode:: LOAD_FROM_DICT_OR_DEREF (i)
12471268

1248-
Much like :opcode:`LOAD_DEREF` but first checks the locals dictionary before
1249-
consulting the cell. This is used for loading free variables in class
1250-
bodies.
1251-
1252-
.. versionadded:: 3.4
1269+
Pops a mapping off the stack and looks up the name associated with
1270+
slot ``i`` of the "fast locals" storage in this mapping.
1271+
If the name is not found there, loads it from the cell contained in
1272+
slot ``i``, similar to :opcode:`LOAD_DEREF`. This is used for loading
1273+
free variables in class bodies (which previously used
1274+
:opcode:`!LOAD_CLASSDEREF`) and in
1275+
:ref:`annotation scopes <annotation-scopes>` within class bodies.
12531276

1254-
.. versionchanged:: 3.11
1255-
``i`` is no longer offset by the length of ``co_varnames``.
1277+
.. versionadded:: 3.12
12561278

12571279

12581280
.. opcode:: STORE_DEREF (i)
@@ -1504,13 +1526,45 @@ iterations of the loop.
15041526

15051527
The operand determines which intrinsic function is called:
15061528

1507-
* ``0`` Not valid
1508-
* ``1`` Prints the argument to standard out. Used in the REPL.
1509-
* ``2`` Performs ``import *`` for the named module.
1510-
* ``3`` Extracts the return value from a ``StopIteration`` exception.
1511-
* ``4`` Wraps an aync generator value
1512-
* ``5`` Performs the unary ``+`` operation
1513-
* ``6`` Converts a list to a tuple
1529+
+-----------------------------------+-----------------------------------+
1530+
| Operand | Description |
1531+
+===================================+===================================+
1532+
| ``INTRINSIC_1_INVALID`` | Not valid |
1533+
+-----------------------------------+-----------------------------------+
1534+
| ``INTRINSIC_PRINT`` | Prints the argument to standard |
1535+
| | out. Used in the REPL. |
1536+
+-----------------------------------+-----------------------------------+
1537+
| ``INTRINSIC_IMPORT_STAR`` | Performs ``import *`` for the |
1538+
| | named module. |
1539+
+-----------------------------------+-----------------------------------+
1540+
| ``INTRINSIC_STOPITERATION_ERROR`` | Extracts the return value from a |
1541+
| | ``StopIteration`` exception. |
1542+
+-----------------------------------+-----------------------------------+
1543+
| ``INTRINSIC_ASYNC_GEN_WRAP`` | Wraps an aync generator value |
1544+
+-----------------------------------+-----------------------------------+
1545+
| ``INTRINSIC_UNARY_POSITIVE`` | Performs the unary ``+`` |
1546+
| | operation |
1547+
+-----------------------------------+-----------------------------------+
1548+
| ``INTRINSIC_LIST_TO_TUPLE`` | Converts a list to a tuple |
1549+
+-----------------------------------+-----------------------------------+
1550+
| ``INTRINSIC_TYPEVAR`` | Creates a :class:`typing.TypeVar` |
1551+
+-----------------------------------+-----------------------------------+
1552+
| ``INTRINSIC_PARAMSPEC`` | Creates a |
1553+
| | :class:`typing.ParamSpec` |
1554+
+-----------------------------------+-----------------------------------+
1555+
| ``INTRINSIC_TYPEVARTUPLE`` | Creates a |
1556+
| | :class:`typing.TypeVarTuple` |
1557+
+-----------------------------------+-----------------------------------+
1558+
| ``INTRINSIC_SUBSCRIPT_GENERIC`` | Returns :class:`typing.Generic` |
1559+
| | subscripted with the argument |
1560+
+-----------------------------------+-----------------------------------+
1561+
| ``INTRINSIC_TYPEALIAS`` | Creates a |
1562+
| | :class:`typing.TypeAliasType`; |
1563+
| | used in the :keyword:`type` |
1564+
| | statement. The argument is a tuple|
1565+
| | of the type alias's name, |
1566+
| | type parameters, and value. |
1567+
+-----------------------------------+-----------------------------------+
15141568

15151569
.. versionadded:: 3.12
15161570

@@ -1522,8 +1576,25 @@ iterations of the loop.
15221576

15231577
The operand determines which intrinsic function is called:
15241578

1525-
* ``0`` Not valid
1526-
* ``1`` Calculates the :exc:`ExceptionGroup` to raise from a ``try-except*``.
1579+
+----------------------------------------+-----------------------------------+
1580+
| Operand | Description |
1581+
+========================================+===================================+
1582+
| ``INTRINSIC_2_INVALID`` | Not valid |
1583+
+----------------------------------------+-----------------------------------+
1584+
| ``INTRINSIC_PREP_RERAISE_STAR`` | Calculates the |
1585+
| | :exc:`ExceptionGroup` to raise |
1586+
| | from a ``try-except*``. |
1587+
+----------------------------------------+-----------------------------------+
1588+
| ``INTRINSIC_TYPEVAR_WITH_BOUND`` | Creates a :class:`typing.TypeVar` |
1589+
| | with a bound. |
1590+
+----------------------------------------+-----------------------------------+
1591+
| ``INTRINSIC_TYPEVAR_WITH_CONSTRAINTS`` | Creates a |
1592+
| | :class:`typing.TypeVar` with |
1593+
| | constraints. |
1594+
+----------------------------------------+-----------------------------------+
1595+
| ``INTRINSIC_SET_FUNCTION_TYPE_PARAMS`` | Sets the ``__type_params__`` |
1596+
| | attribute of a function. |
1597+
+----------------------------------------+-----------------------------------+
15271598

15281599
.. versionadded:: 3.12
15291600

‎Doc/library/stdtypes.rst

+8
Original file line numberDiff line numberDiff line change
@@ -5476,6 +5476,14 @@ types, where they are relevant. Some of these are not reported by the
54765476
.. versionadded:: 3.3
54775477

54785478

5479+
.. attribute:: definition.__type_params__
5480+
5481+
The :ref:`type parameters <type-params>` of generic classes, functions,
5482+
and :ref:`type aliases <type-aliases>`.
5483+
5484+
.. versionadded:: 3.12
5485+
5486+
54795487
.. attribute:: class.__mro__
54805488

54815489
This attribute is a tuple of classes that are considered when looking for

0 commit comments

Comments
 (0)