JelleZijlstra · May 26, 2023 · May 13, 2023 · May 15, 2023 · May 19, 2023 · May 19, 2023
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
@@ -57,20 +57,20 @@ the extracted data in a :class:`argparse.Namespace` object::
 Quick Links for add_argument()
 ------------------------------
 
-====================== =========================================================== ==========================================================================================================================
-Name                   Description                                                 Values
-====================== =========================================================== ==========================================================================================================================
-action_                Specify how an argument should be handled                   ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``'append_const'``, ``'count'``, ``'help'``, ``'version'``
-choices_               Limit values to a specific set of choices                   ``['foo', 'bar']``, ``range(1, 10)``, or :class:`~collections.abc.Container` instance
-const_                 Store a constant value
-default_               Default value used when an argument is not provided         Defaults to ``None``
-dest_                  Specify the attribute name used in the result namespace
-help_                  Help message for an argument
-metavar_               Alternate display name for the argument as shown in help
-nargs_                 Number of times the argument can be used                    :class:`int`, ``'?'``, ``'*'``, or ``'+'``
-required_              Indicate whether an argument is required or optional        ``True`` or ``False``
-type_                  Automatically convert an argument to the given type         :class:`int`, :class:`float`, ``argparse.FileType('w')``, or callable function
-====================== =========================================================== ==========================================================================================================================
+============================ =========================================================== ==========================================================================================================================
+Name                         Description                                                 Values
+============================ =========================================================== ==========================================================================================================================
+action_                      Specify how an argument should be handled                   ``'store'``, ``'store_const'``, ``'store_true'``, ``'append'``, ``'append_const'``, ``'count'``, ``'help'``, ``'version'``
+choices_                     Limit values to a specific set of choices                   ``['foo', 'bar']``, ``range(1, 10)``, or :class:`~collections.abc.Container` instance
+const_                       Store a constant value
+default_                     Default value used when an argument is not provided         Defaults to ``None``
+dest_                        Specify the attribute name used in the result namespace
+help_                        Help message for an argument
+metavar_                     Alternate display name for the argument as shown in help
+nargs_                       Number of times the argument can be used                    :class:`int`, ``'?'``, ``'*'``, or ``'+'``
+required_                    Indicate whether an argument is required or optional        ``True`` or ``False``
+:ref:`type <argparse-type>`  Automatically convert an argument to the given type         :class:`int`, :class:`float`, ``argparse.FileType('w')``, or callable function
+============================ =========================================================== ==========================================================================================================================
 
 
 Example
@@ -1132,7 +1132,7 @@ command-line argument was not present::
    Namespace(foo='1')
 
 
-.. _type:
+.. _argparse-type:
 
 type
 ^^^^

diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
@@ -917,6 +917,25 @@ Statements
             type_ignores=[])
 
 
+.. class:: TypeAlias(name, typeparams, value)
+
+   A type alias created through the :keyword:`type` statement. ``name``
+   is the name of the alias, ``typeparams`` 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()),
+                    typeparams=[],
+                    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, and
+   ``bound`` is the bound or constraints, if any. If the value 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()),
+                    typeparams=[
+                        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()),
+                    typeparams=[
+                        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()),
+                    typeparams=[
+                        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, typeparams, args, body, decorator_list, returns, type_comment)
 
    A function definition.
 
    * ``name`` is a raw string of the function name.
+   * ``typeparams`` 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, starargs, kwargs, body, decorator_list)
+.. class:: ClassDef(name, typeparams, bases, keywords, starargs, kwargs, body, decorator_list)
 
    A class definition.
 
    * ``name`` is a raw string for the class name
+   * ``typeparams`` 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

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
@@ -189,8 +189,8 @@ operation is being performed, so the intermediate analysis object isn't useful:
    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).
+   generator expressions and nested functions, and the code
+   used for building nested classes and :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, look 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, load it from the cell contained in
+   slot ``i``, similar to :opcode:`LOAD_DEREF`. This is used for loading
+   free variables in class bodies 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
+      Replaces the previous instruction ``LOAD_CLASSDEREF``.
 
 
 .. opcode:: STORE_DEREF (i)
@@ -1504,13 +1526,23 @@ 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
+   * ``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 value on top of the stack.
+   * ``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 +1554,15 @@ 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*``.
+   * ``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
 

@@ -101,6 +101,8 @@ annotations. These include:
 * :pep:`692`: Using ``TypedDict`` for more precise ``**kwargs`` typing
     *Introducing* a new way of typing ``**kwargs`` with :data:`Unpack` and
     :data:`TypedDict`
+* :pep:`695`: Type Parameter Syntax
+    *Introducing* syntax for creating generic functions, classes, and type aliases.
 * :pep:`698`: Adding an override decorator to typing
     *Introducing* the :func:`@override<override>` decorator
 
@@ -109,10 +111,10 @@ annotations. These include:
 Type aliases
 ============
 
-A type alias is defined by assigning the type to the alias. In this example,
+A type alias is defined using the :keyword:`type` statement. In this example,
 ``Vector`` and ``list[float]`` will be treated as interchangeable synonyms::
 
-   Vector = list[float]
+   type Vector = list[float]
 
    def scale(scalar: float, vector: Vector) -> Vector:
        return [scalar * num for num in vector]
@@ -124,9 +126,9 @@ Type aliases are useful for simplifying complex type signatures. For example::
 
    from collections.abc import Sequence
 
-   ConnectionOptions = dict[str, str]
-   Address = tuple[str, int]
-   Server = tuple[Address, ConnectionOptions]
+   type ConnectionOptions = dict[str, str]
+   type Address = tuple[str, int]
+   type Server = tuple[Address, ConnectionOptions]
 
    def broadcast_message(message: str, servers: Sequence[Server]) -> None:
        ...
@@ -141,6 +143,17 @@ Type aliases are useful for simplifying complex type signatures. For example::
 Note that ``None`` as a type hint is a special case and is replaced by
 ``type(None)``.
 
+The :keyword:`type` statement is new in Python 3.12. For backwards
+compatibility, type aliases can also created through simple assignment::
+
+   Vector = list[float]
+
+Or marked with :data:`TypeAlias`::
+
+   from typing import TypeAlias
+
+   Vector: TypeAlias = list[float]
+
 .. _distinct:
 
 NewType
@@ -752,6 +765,9 @@ These can be used as types in annotations and do not support ``[]``.
 
    .. versionadded:: 3.10
 
+   .. deprecated:: 3.12
+      :data:`TypeAlias` is deprecated in favor of the :keyword:`type` statement.
+
 Special forms
 """""""""""""
 
@@ -2994,3 +3010,5 @@ convenience. This is subject to change, and not all deprecations are listed.
 |  ``typing.Hashable`` and         | 3.12          | Undecided         | :gh:`94309`    |
 |  ``typing.Sized``                |               |                   |                |
 +----------------------------------+---------------+-------------------+----------------+
+|  ``typing.TypeAlias``            | 3.12          | Undecided         | :pep:`695`     |
++----------------------------------+---------------+-------------------+----------------+