gh-103921: Document PEP 695

Doc/library/ast.rst

@@ -917,6 +917,25 @@ Statements
  type_ignores=[])
 
 
+.. class:: TypeAlias(name, type_params, value)
+
+ A :ref:`type alias <type-aliases>` created through the :keyword:`type`
+ statement. ``name`` is the name of the alias, ``type_params`` is a list of
+ :ref:`type parameters <ast-type-params>`, and ``value`` is the value of the
+ type alias.
+
+ .. doctest::
+
+ >>> print(ast.dump(ast.parse('type Alias = int'), indent=4))
+ Module(
+ body=[
+ TypeAlias(
+ name=Name(id='Alias', ctx=Store()),
+ type_params=[],
+ value=Name(id='int', ctx=Load()))],
+ type_ignores=[])
+
+
 Other statements which are only applicable inside functions or loops are
 described in other sections.
 
@@ -1644,15 +1663,93 @@ Pattern matching
  value=Constant(value=Ellipsis))])])],
  type_ignores=[])
 
+.. _ast-type-params:
+
+Type parameters
+^^^^^^^^^^^^^^^
+
+:ref:`Type parameters <type-params>` can exist on classes, functions, and type
+aliases.
+
+.. class:: TypeVar(name, 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.
+
+ .. doctest::
+
+ >>> print(ast.dump(ast.parse("type Alias[T: int] = list[T]"), indent=4))
+ Module(
+ body=[
+ TypeAlias(
+ name=Name(id='Alias', ctx=Store()),
+ type_params=[
+ TypeVar(
+ name='T',
+ bound=Name(id='int', ctx=Load()))],
+ value=Subscript(
+ value=Name(id='list', ctx=Load()),
+ slice=Name(id='T', ctx=Load()),
+ ctx=Load()))],
+ type_ignores=[])
+
+.. class:: ParamSpec(name)
+
+ A :class:`typing.ParamSpec`. ``name`` is the name of the parameter specification.
+
+ .. doctest::
+
+ >>> print(ast.dump(ast.parse("type Alias[**P] = Callable[P, int]"), indent=4))
+ Module(
+ body=[
+ TypeAlias(
+ name=Name(id='Alias', ctx=Store()),
+ type_params=[
+ ParamSpec(name='P')],
+ value=Subscript(
+ value=Name(id='Callable', ctx=Load()),
+ slice=Tuple(
+ elts=[
+ Name(id='P', ctx=Load()),
+ Name(id='int', ctx=Load())],
+ ctx=Load()),
+ ctx=Load()))],
+ type_ignores=[])
+
+.. class:: TypeVarTuple(name)
+
+ A :class:`typing.TypeVarTuple`. ``name`` is the name of the type variable tuple.
+
+ .. doctest::
+
+ >>> 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')],
+ value=Subscript(
+ value=Name(id='tuple', ctx=Load()),
+ slice=Tuple(
+ elts=[
+ Starred(
+ value=Name(id='Ts', ctx=Load()),
+ ctx=Load())],
+ ctx=Load()),
+ ctx=Load()))],
+ type_ignores=[])
 
 Function and class definitions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. class:: FunctionDef(name, args, body, decorator_list, returns, type_comment)
+.. class:: FunctionDef(name, type_params, args, body, decorator_list, returns, type_comment)
 
  A function definition.
 
  * ``name`` is a raw string of the function name.
+ * ``type_params`` is a list of :ref:`type parameters <ast-type-params>`.
  * ``args`` is an :class:`arguments` node.
  * ``body`` is the list of nodes inside the function.
  * ``decorator_list`` is the list of decorators to be applied, stored outermost
@@ -1820,11 +1917,12 @@ Function and class definitions
  type_ignores=[])
 
 
-.. class:: ClassDef(name, bases, keywords, body, decorator_list)
+.. class:: ClassDef(name, type_params, bases, keywords, body, decorator_list)
 
  A class definition.
 
  * ``name`` is a raw string for the class name
+ * ``type_params`` is a list of :ref:`type parameters <ast-type-params>`.
  * ``bases`` is a list of nodes for explicitly specified base classes.
  * ``keywords`` is a list of :class:`keyword` nodes, principally for 'metaclass'.
  Other keywords will be passed to the metaclass, as per `PEP-3115

Doc/library/dis.rst

@@ -188,9 +188,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
  For a module, it disassembles all functions. For a class, it disassembles
  all methods (including class and static methods). For a code object or
  sequence of raw bytecode, it prints one line per bytecode instruction.
- It also recursively disassembles nested code objects (the code of
-comprehensions, generator expressions and nested functions, and the code
- used for building nested classes).
+ It also recursively disassembles nested code objects. These can include
+ generator expressions, nested functions, the bodies of nested classes,
+and the code objects used for :ref:`annotation scopes <annotation-scopes>`.
  Strings are first compiled to code objects with the :func:`compile`
  built-in function before being disassembled. If no object is provided, this
  function disassembles the last traceback.
@@ -926,6 +926,27 @@ iterations of the loop.
 .. opcode:: LOAD_NAME (namei)
 
  Pushes the value associated with ``co_names[namei]`` onto the stack.
+ The name is looked up within the locals, then the globals, then the builtins.
+
+
+.. opcode:: LOAD_LOCALS
+
+ Pushes a reference to the locals dictionary onto the stack. This is used
+ to prepare namespace dictionaries for :opcode:`LOAD_FROM_DICT_OR_DEREF`
+ and :opcode:`LOAD_FROM_DICT_OR_GLOBALS`.
+
+ .. versionadded:: 3.12
+
+
+.. opcode:: LOAD_FROM_DICT_OR_GLOBALS (i)
+
+ Pops a mapping off the stack and looks up the value for ``co_names[namei]``.
+ If the name is not found there, looks it up in the globals and then the builtins,
+ similar to :opcode:`LOAD_GLOBAL`.
+ This is used for loading global variables in
+ :ref:`annotation scopes <annotation-scopes>` within class bodies.
+
+ .. versionadded:: 3.12
 
 
 .. opcode:: BUILD_TUPLE (count)
@@ -1243,16 +1264,17 @@ iterations of the loop.
  ``i`` is no longer offset by the length of ``co_varnames``.
 
 
-.. opcode:: LOAD_CLASSDEREF (i)
+.. opcode:: LOAD_FROM_DICT_OR_DEREF (i)
 
- Much like :opcode:`LOAD_DEREF` but first checks the locals dictionary before
- consulting the cell. This is used for loading free variables in class
- bodies.
-
- .. versionadded:: 3.4
+ Pops a mapping off the stack and looks up the name associated with
+ slot ``i`` of the "fast locals" storage in this mapping.
+ If the name is not found there, loads it from the cell contained in
+ slot ``i``, similar to :opcode:`LOAD_DEREF`. This is used for loading
+ free variables in class bodies (which previously used
+ :opcode:`!LOAD_CLASSDEREF`) and in
+ :ref:`annotation scopes <annotation-scopes>` within class bodies.
 
- .. versionchanged:: 3.11
- ``i`` is no longer offset by the length of ``co_varnames``.
+ .. versionadded:: 3.12
 
 
 .. opcode:: STORE_DEREF (i)
@@ -1504,13 +1526,45 @@ iterations of the loop.
 
  The operand determines which intrinsic function is called:
 
- * ``0`` Not valid
- * ``1`` Prints the argument to standard out. Used in the REPL.
- * ``2`` Performs ``import *`` for the named module.
- * ``3`` Extracts the return value from a ``StopIteration`` exception.
- * ``4`` Wraps an aync generator value
- * ``5`` Performs the unary ``+`` operation
- * ``6`` Converts a list to a tuple
+ +-----------------------------------+-----------------------------------+
+ | Operand | Description |
+ +===================================+===================================+
+ | ``INTRINSIC_1_INVALID`` | Not valid |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_PRINT`` | Prints the argument to standard |
+ | | out. Used in the REPL. |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_IMPORT_STAR`` | Performs ``import *`` for the |
+ | | named module. |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_STOPITERATION_ERROR`` | Extracts the return value from a |
+ | | ``StopIteration`` exception. |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_ASYNC_GEN_WRAP`` | Wraps an aync generator value |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_UNARY_POSITIVE`` | Performs the unary ``+`` |
+ | | operation |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_LIST_TO_TUPLE`` | Converts a list to a tuple |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_TYPEVAR`` | Creates a :class:`typing.TypeVar` |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_PARAMSPEC`` | Creates a |
+ | | :class:`typing.ParamSpec` |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_TYPEVARTUPLE`` | Creates a |
+ | | :class:`typing.TypeVarTuple` |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_SUBSCRIPT_GENERIC`` | Returns :class:`typing.Generic` |
+ | | subscripted with the argument |
+ +-----------------------------------+-----------------------------------+
+ | ``INTRINSIC_TYPEALIAS`` | Creates a |
+ | | :class:`typing.TypeAliasType`; |
+ | | used in the :keyword:`type` |
+ | | statement. The argument is a tuple|
+ | | of the type alias's name, |
+ | | type parameters, and value. |
+ +-----------------------------------+-----------------------------------+
 
  .. versionadded:: 3.12
 
@@ -1522,8 +1576,25 @@ iterations of the loop.
 
  The operand determines which intrinsic function is called:
 
- * ``0`` Not valid
- * ``1`` Calculates the :exc:`ExceptionGroup` to raise from a ``try-except*``.
+ +----------------------------------------+-----------------------------------+
+ | Operand | Description |
+ +========================================+===================================+
+ | ``INTRINSIC_2_INVALID`` | Not valid |
+ +----------------------------------------+-----------------------------------+
+ | ``INTRINSIC_PREP_RERAISE_STAR`` | Calculates the |
+ | | :exc:`ExceptionGroup` to raise |
+ | | from a ``try-except*``. |
+ +----------------------------------------+-----------------------------------+
+ | ``INTRINSIC_TYPEVAR_WITH_BOUND`` | Creates a :class:`typing.TypeVar` |
+ | | with a bound. |
+ +----------------------------------------+-----------------------------------+
+ | ``INTRINSIC_TYPEVAR_WITH_CONSTRAINTS`` | Creates a |
+ | | :class:`typing.TypeVar` with |
+ | | constraints. |
+ +----------------------------------------+-----------------------------------+
+ | ``INTRINSIC_SET_FUNCTION_TYPE_PARAMS`` | Sets the ``__type_params__`` |
+ | | attribute of a function. |
+ +----------------------------------------+-----------------------------------+
 
  .. versionadded:: 3.12
 

Doc/library/stdtypes.rst

@@ -5476,6 +5476,14 @@ types, where they are relevant. Some of these are not reported by the
  .. versionadded:: 3.3
 
 
+.. attribute:: definition.__type_params__
+
+ The :ref:`type parameters <type-params>` of generic classes, functions,
+ and :ref:`type aliases <type-aliases>`.
+
+ .. versionadded:: 3.12
+
+
 .. attribute:: class.__mro__
 
  This attribute is a tuple of classes that are considered when looking for