Skip to content

Commit 060277d

Browse files
JelleZijlstraAlexWaygood
JelleZijlstra
and
AlexWaygood
authored
gh-103921: Document PEP 695 (#104642)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
1 parent 95f1b1f commit 060277d

File tree

11 files changed

+1234
-302
lines changed

11 files changed

+1234
-302
lines changed

‎Doc/library/ast.rst

Lines changed: 100 additions & 2 deletions
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

Lines changed: 91 additions & 20 deletions
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

Lines changed: 8 additions & 0 deletions
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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy