Python 3.12.0b2v3.12.0b2

1 files changed, 674 insertions, 107 deletions

diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py
index cb74299..d70bf9e 100644
--- a/Lib/pydoc_data/topics.py
+++ b/Lib/pydoc_data/topics.py
@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Autogenerated by Sphinx on Mon May 22 14:02:15 2023
+# Autogenerated by Sphinx on Tue Jun  6 16:12:51 2023
 topics = {'assert': 'The "assert" statement\n'
            '**********************\n'
            '\n'
@@ -538,77 +538,7 @@ topics = {'assert': 'The "assert" statement\n'
           '  **PEP 492** - Coroutines with async and await syntax\n'
           '     The proposal that made coroutines a proper standalone concept '
           'in\n'
-          '     Python, and added supporting syntax.\n'
-          '\n'
-          '-[ Footnotes ]-\n'
-          '\n'
-          '[1] The exception is propagated to the invocation stack unless '
-          'there\n'
-          '    is a "finally" clause which happens to raise another '
-          'exception.\n'
-          '    That new exception causes the old one to be lost.\n'
-          '\n'
-          '[2] In pattern matching, a sequence is defined as one of the\n'
-          '    following:\n'
-          '\n'
-          '       * a class that inherits from "collections.abc.Sequence"\n'
-          '\n'
-          '       * a Python class that has been registered as\n'
-          '         "collections.abc.Sequence"\n'
-          '\n'
-          '       * a builtin class that has its (CPython) '
-          '"Py_TPFLAGS_SEQUENCE"\n'
-          '         bit set\n'
-          '\n'
-          '       * a class that inherits from any of the above\n'
-          '\n'
-          '    The following standard library classes are sequences:\n'
-          '\n'
-          '       * "array.array"\n'
-          '\n'
-          '       * "collections.deque"\n'
-          '\n'
-          '       * "list"\n'
-          '\n'
-          '       * "memoryview"\n'
-          '\n'
-          '       * "range"\n'
-          '\n'
-          '       * "tuple"\n'
-          '\n'
-          '    Note:\n'
-          '\n'
-          '      Subject values of type "str", "bytes", and "bytearray" do '
-          'not\n'
-          '      match sequence patterns.\n'
-          '\n'
-          '[3] In pattern matching, a mapping is defined as one of the '
-          'following:\n'
-          '\n'
-          '       * a class that inherits from "collections.abc.Mapping"\n'
-          '\n'
-          '       * a Python class that has been registered as\n'
-          '         "collections.abc.Mapping"\n'
-          '\n'
-          '       * a builtin class that has its (CPython) '
-          '"Py_TPFLAGS_MAPPING"\n'
-          '         bit set\n'
-          '\n'
-          '       * a class that inherits from any of the above\n'
-          '\n'
-          '    The standard library classes "dict" and '
-          '"types.MappingProxyType"\n'
-          '    are mappings.\n'
-          '\n'
-          '[4] A string literal appearing as the first statement in the '
-          'function\n'
-          '    body is transformed into the function’s "__doc__" attribute '
-          'and\n'
-          '    therefore the function’s *docstring*.\n'
-          '\n'
-          '[5] A string literal appearing as the first statement in the class\n'
-          '    body is transformed into the namespace’s "__doc__" item and\n'
-          '    therefore the class’s *docstring*.\n',
+          '     Python, and added supporting syntax.\n',
  'atom-identifiers': 'Identifiers (Names)\n'
                      '*******************\n'
                      '\n'
@@ -1748,8 +1678,8 @@ topics = {'assert': 'The "assert" statement\n'
           'standard\n'
           'type hierarchy):\n'
           '\n'
-          '   classdef    ::= [decorators] "class" classname [inheritance] ":" '
-          'suite\n'
+          '   classdef    ::= [decorators] "class" classname [type_params] '
+          '[inheritance] ":" suite\n'
           '   inheritance ::= "(" [argument_list] ")"\n'
           '   classname   ::= identifier\n'
           '\n'
@@ -1813,6 +1743,19 @@ topics = {'assert': 'The "assert" statement\n'
           '"assignment_expression". Previously, the grammar was much more\n'
           'restrictive; see **PEP 614** for details.\n'
           '\n'
+          'A list of type parameters may be given in square brackets '
+          'immediately\n'
+          'after the class’s name. This indicates to static type checkers '
+          'that\n'
+          'the class is generic. At runtime, the type parameters can be '
+          'retrieved\n'
+          'from the class’s "__type_params__" attribute. See Generic classes '
+          'for\n'
+          'more.\n'
+          '\n'
+          'Changed in version 3.12: Type parameter lists are new in Python '
+          '3.12.\n'
+          '\n'
           '**Programmer’s note:** Variables defined in the class definition '
           'are\n'
           'class attributes; they are shared by instances.  Instance '
@@ -3554,8 +3497,8 @@ topics = {'assert': 'The "assert" statement\n'
              '(see\n'
              'section The standard type hierarchy):\n'
              '\n'
-             '   funcdef                   ::= [decorators] "def" funcname "(" '
-             '[parameter_list] ")"\n'
+             '   funcdef                   ::= [decorators] "def" funcname '
+             '[type_params] "(" [parameter_list] ")"\n'
              '               ["->" expression] ":" suite\n'
              '   decorators                ::= decorator+\n'
              '   decorator                 ::= "@" assignment_expression '
@@ -3617,6 +3560,19 @@ topics = {'assert': 'The "assert" statement\n'
              '"assignment_expression". Previously, the grammar was much more\n'
              'restrictive; see **PEP 614** for details.\n'
              '\n'
+             'A list of type parameters may be given in square brackets '
+             'between the\n'
+             'function’s name and the opening parenthesis for its parameter '
+             'list.\n'
+             'This indicates to static type checkers that the function is '
+             'generic.\n'
+             'At runtime, the type parameters can be retrieved from the '
+             'function’s\n'
+             '"__type_params__" attribute. See Generic functions for more.\n'
+             '\n'
+             'Changed in version 3.12: Type parameter lists are new in Python '
+             '3.12.\n'
+             '\n'
              'When one or more *parameters* have the form *parameter* "="\n'
              '*expression*, the function is said to have “default parameter '
              'values.”\n'
@@ -3759,8 +3715,8 @@ topics = {'assert': 'The "assert" statement\n'
              'standard\n'
              'type hierarchy):\n'
              '\n'
-             '   classdef    ::= [decorators] "class" classname [inheritance] '
-             '":" suite\n'
+             '   classdef    ::= [decorators] "class" classname [type_params] '
+             '[inheritance] ":" suite\n'
              '   inheritance ::= "(" [argument_list] ")"\n'
              '   classname   ::= identifier\n'
              '\n'
@@ -3828,6 +3784,19 @@ topics = {'assert': 'The "assert" statement\n'
              '"assignment_expression". Previously, the grammar was much more\n'
              'restrictive; see **PEP 614** for details.\n'
              '\n'
+             'A list of type parameters may be given in square brackets '
+             'immediately\n'
+             'after the class’s name. This indicates to static type checkers '
+             'that\n'
+             'the class is generic. At runtime, the type parameters can be '
+             'retrieved\n'
+             'from the class’s "__type_params__" attribute. See Generic '
+             'classes for\n'
+             'more.\n'
+             '\n'
+             'Changed in version 3.12: Type parameter lists are new in Python '
+             '3.12.\n'
+             '\n'
              '**Programmer’s note:** Variables defined in the class definition '
              'are\n'
              'class attributes; they are shared by instances.  Instance '
@@ -3985,6 +3954,272 @@ topics = {'assert': 'The "assert" statement\n'
              'concept in\n'
              '     Python, and added supporting syntax.\n'
              '\n'
+             '\n'
+             'Type parameter lists\n'
+             '====================\n'
+             '\n'
+             'New in version 3.12.\n'
+             '\n'
+             '   type_params  ::= "[" type_param ("," type_param)* "]"\n'
+             '   type_param   ::= typevar | typevartuple | paramspec\n'
+             '   typevar      ::= identifier (":" expression)?\n'
+             '   typevartuple ::= "*" identifier\n'
+             '   paramspec    ::= "**" identifier\n'
+             '\n'
+             'Functions (including coroutines), classes and type aliases may '
+             'contain\n'
+             'a type parameter list:\n'
+             '\n'
+             '   def max[T](args: list[T]) -> T:\n'
+             '       ...\n'
+             '\n'
+             '   async def amax[T](args: list[T]) -> T:\n'
+             '       ...\n'
+             '\n'
+             '   class Bag[T]:\n'
+             '       def __iter__(self) -> Iterator[T]:\n'
+             '           ...\n'
+             '\n'
+             '       def add(self, arg: T) -> None:\n'
+             '           ...\n'
+             '\n'
+             '   type ListOrSet[T] = list[T] | set[T]\n'
+             '\n'
+             'Semantically, this indicates that the function, class, or type '
+             'alias\n'
+             'is generic over a type variable. This information is primarily '
+             'used by\n'
+             'static type checkers, and at runtime, generic objects behave '
+             'much like\n'
+             'their non-generic counterparts.\n'
+             '\n'
+             'Type parameters are declared in square brackets ("[]") '
+             'immediately\n'
+             'after the name of the function, class, or type alias. The type\n'
+             'parameters are accessible within the scope of the generic '
+             'object, but\n'
+             'not elsewhere. Thus, after a declaration "def func[T](): pass", '
+             'the\n'
+             'name "T" is not available in the module scope. Below, the '
+             'semantics of\n'
+             'generic objects are described with more precision. The scope of '
+             'type\n'
+             'parameters is modeled with a special function (technically, an\n'
+             'annotation scope) that wraps the creation of the generic '
+             'object.\n'
+             '\n'
+             'Generic functions, classes, and type aliases have a '
+             '"__type_params__"\n'
+             'attribute listing their type parameters.\n'
+             '\n'
+             'Type parameters come in three kinds:\n'
+             '\n'
+             '* "typing.TypeVar", introduced by a plain name (e.g., "T").\n'
+             '  Semantically, this represents a single type to a type '
+             'checker.\n'
+             '\n'
+             '* "typing.TypeVarTuple", introduced by a name prefixed with a '
+             'single\n'
+             '  asterisk (e.g., "*Ts"). Semantically, this stands for a tuple '
+             'of any\n'
+             '  number of types.\n'
+             '\n'
+             '* "typing.ParamSpec", introduced by a name prefixed with two '
+             'asterisks\n'
+             '  (e.g., "**P"). Semantically, this stands for the parameters of '
+             'a\n'
+             '  callable.\n'
+             '\n'
+             '"typing.TypeVar" declarations can define *bounds* and '
+             '*constraints*\n'
+             'with a colon (":") followed by an expression. A single '
+             'expression\n'
+             'after the colon indicates a bound (e.g. "T: int"). Semantically, '
+             'this\n'
+             'means that the "typing.TypeVar" can only represent types that '
+             'are a\n'
+             'subtype of this bound. A parenthesized tuple of expressions '
+             'after the\n'
+             'colon indicates a set of constraints (e.g. "T: (str, bytes)"). '
+             'Each\n'
+             'member of the tuple should be a type (again, this is not '
+             'enforced at\n'
+             'runtime). Constrained type variables can only take on one of the '
+             'types\n'
+             'in the list of constraints.\n'
+             '\n'
+             'For "typing.TypeVar"s declared using the type parameter list '
+             'syntax,\n'
+             'the bound and constraints are not evaluated when the generic '
+             'object is\n'
+             'created, but only when the value is explicitly accessed through '
+             'the\n'
+             'attributes "__bound__" and "__constraints__". To accomplish '
+             'this, the\n'
+             'bounds or constraints are evaluated in a separate annotation '
+             'scope.\n'
+             '\n'
+             '"typing.TypeVarTuple"s and "typing.ParamSpec"s cannot have '
+             'bounds or\n'
+             'constraints.\n'
+             '\n'
+             'The following example indicates the full set of allowed type '
+             'parameter\n'
+             'declarations:\n'
+             '\n'
+             '   def overly_generic[\n'
+             '      SimpleTypeVar,\n'
+             '      TypeVarWithBound: int,\n'
+             '      TypeVarWithConstraints: (str, bytes),\n'
+             '      *SimpleTypeVarTuple,\n'
+             '      **SimpleParamSpec,\n'
+             '   ](\n'
+             '      a: SimpleTypeVar,\n'
+             '      b: TypeVarWithBound,\n'
+             '      c: Callable[SimpleParamSpec, TypeVarWithConstraints],\n'
+             '      *d: SimpleTypeVarTuple,\n'
+             '   ): ...\n'
+             '\n'
+             '\n'
+             'Generic functions\n'
+             '-----------------\n'
+             '\n'
+             'Generic functions are declared as follows:\n'
+             '\n'
+             '   def func[T](arg: T): ...\n'
+             '\n'
+             'This syntax is equivalent to:\n'
+             '\n'
+             '   annotation-def TYPE_PARAMS_OF_func():\n'
+             '       T = typing.TypeVar("T")\n'
+             '       def func(arg: T): ...\n'
+             '       func.__type_params__ = (T,)\n'
+             '       return func\n'
+             '   func = TYPE_PARAMS_OF_func()\n'
+             '\n'
+             'Here "annotation-def" indicates an annotation scope, which is '
+             'not\n'
+             'actually bound to any name at runtime. (One other liberty is '
+             'taken in\n'
+             'the translation: the syntax does not go through attribute access '
+             'on\n'
+             'the "typing" module, but creates an instance of '
+             '"typing.TypeVar"\n'
+             'directly.)\n'
+             '\n'
+             'The annotations of generic functions are evaluated within the\n'
+             'annotation scope used for declaring the type parameters, but '
+             'the\n'
+             'function’s defaults and decorators are not.\n'
+             '\n'
+             'The following example illustrates the scoping rules for these '
+             'cases,\n'
+             'as well as for additional flavors of type parameters:\n'
+             '\n'
+             '   @decorator\n'
+             '   def func[T: int, *Ts, **P](*args: *Ts, arg: Callable[P, T] = '
+             'some_default):\n'
+             '       ...\n'
+             '\n'
+             'Except for the lazy evaluation of the "TypeVar" bound, this is\n'
+             'equivalent to:\n'
+             '\n'
+             '   DEFAULT_OF_arg = some_default\n'
+             '\n'
+             '   annotation-def TYPE_PARAMS_OF_func():\n'
+             '\n'
+             '       annotation-def BOUND_OF_T():\n'
+             '           return int\n'
+             '       # In reality, BOUND_OF_T() is evaluated only on demand.\n'
+             '       T = typing.TypeVar("T", bound=BOUND_OF_T())\n'
+             '\n'
+             '       Ts = typing.TypeVarTuple("Ts")\n'
+             '       P = typing.ParamSpec("P")\n'
+             '\n'
+             '       def func(*args: *Ts, arg: Callable[P, T] = '
+             'DEFAULT_OF_arg):\n'
+             '           ...\n'
+             '\n'
+             '       func.__type_params__ = (T, Ts, P)\n'
+             '       return func\n'
+             '   func = decorator(TYPE_PARAMS_OF_func())\n'
+             '\n'
+             'The capitalized names like "DEFAULT_OF_arg" are not actually '
+             'bound at\n'
+             'runtime.\n'
+             '\n'
+             '\n'
+             'Generic classes\n'
+             '---------------\n'
+             '\n'
+             'Generic classes are declared as follows:\n'
+             '\n'
+             '   class Bag[T]: ...\n'
+             '\n'
+             'This syntax is equivalent to:\n'
+             '\n'
+             '   annotation-def TYPE_PARAMS_OF_Bag():\n'
+             '       T = typing.TypeVar("T")\n'
+             '       class Bag(typing.Generic[T]):\n'
+             '           __type_params__ = (T,)\n'
+             '           ...\n'
+             '       return Bag\n'
+             '   Bag = TYPE_PARAMS_OF_Bag()\n'
+             '\n'
+             'Here again "annotation-def" (not a real keyword) indicates an\n'
+             'annotation scope, and the name "TYPE_PARAMS_OF_Bag" is not '
+             'actually\n'
+             'bound at runtime.\n'
+             '\n'
+             'Generic classes implicitly inherit from "typing.Generic". The '
+             'base\n'
+             'classes and keyword arguments of generic classes are evaluated '
+             'within\n'
+             'the type scope for the type parameters, and decorators are '
+             'evaluated\n'
+             'outside that scope. This is illustrated by this example:\n'
+             '\n'
+             '   @decorator\n'
+             '   class Bag(Base[T], arg=T): ...\n'
+             '\n'
+             'This is equivalent to:\n'
+             '\n'
+             '   annotation-def TYPE_PARAMS_OF_Bag():\n'
+             '       T = typing.TypeVar("T")\n'
+             '       class Bag(Base[T], typing.Generic[T], arg=T):\n'
+             '           __type_params__ = (T,)\n'
+             '           ...\n'
+             '       return Bag\n'
+             '   Bag = decorator(TYPE_PARAMS_OF_Bag())\n'
+             '\n'
+             '\n'
+             'Generic type aliases\n'
+             '--------------------\n'
+             '\n'
+             'The "type" statement can also be used to create a generic type '
+             'alias:\n'
+             '\n'
+             '   type ListOrSet[T] = list[T] | set[T]\n'
+             '\n'
+             'Except for the lazy evaluation of the value, this is equivalent '
+             'to:\n'
+             '\n'
+             '   annotation-def TYPE_PARAMS_OF_ListOrSet():\n'
+             '       T = typing.TypeVar("T")\n'
+             '\n'
+             '       annotation-def VALUE_OF_ListOrSet():\n'
+             '           return list[T] | set[T]\n'
+             '       # In reality, the value is lazily evaluated\n'
+             '       return typing.TypeAliasType("ListOrSet", '
+             'VALUE_OF_ListOrSet(), type_params=(T,))\n'
+             '   ListOrSet = TYPE_PARAMS_OF_ListOrSet()\n'
+             '\n'
+             'Here, "annotation-def" (not a real keyword) indicates an '
+             'annotation\n'
+             'scope. The capitalized names like "TYPE_PARAMS_OF_ListOrSet" are '
+             'not\n'
+             'actually bound at runtime.\n'
+             '\n'
              '-[ Footnotes ]-\n'
              '\n'
              '[1] The exception is propagated to the invocation stack unless '
@@ -5692,6 +5927,10 @@ topics = {'assert': 'The "assert" statement\n'
               '\n'
               '* "import" statements.\n'
               '\n'
+              '* "type" statements.\n'
+              '\n'
+              '* type parameter lists.\n'
+              '\n'
               'The "import" statement of the form "from ... import *" binds '
               'all names\n'
               'defined in the imported module, except those beginning with an\n'
@@ -5798,7 +6037,9 @@ topics = {'assert': 'The "assert" statement\n'
               'scope.\n'
               '"SyntaxError" is raised at compile time if the given name does '
               'not\n'
-              'exist in any enclosing function scope.\n'
+              'exist in any enclosing function scope. Type parameters cannot '
+              'be\n'
+              'rebound with the "nonlocal" statement.\n'
               '\n'
               'The namespace for a module is automatically created the first '
               'time a\n'
@@ -5821,17 +6062,162 @@ topics = {'assert': 'The "assert" statement\n'
               'the class. The scope of names defined in a class block is '
               'limited to\n'
               'the class block; it does not extend to the code blocks of '
-              'methods –\n'
-              'this includes comprehensions and generator expressions since '
-              'they are\n'
-              'implemented using a function scope.  This means that the '
-              'following\n'
-              'will fail:\n'
+              'methods.\n'
+              'This includes comprehensions and generator expressions, but it '
+              'does\n'
+              'not include annotation scopes, which have access to their '
+              'enclosing\n'
+              'class scopes. This means that the following will fail:\n'
               '\n'
               '   class A:\n'
               '       a = 42\n'
               '       b = list(a + i for i in range(10))\n'
               '\n'
+              'However, the following will succeed:\n'
+              '\n'
+              '   class A:\n'
+              '       type Alias = Nested\n'
+              '       class Nested: pass\n'
+              '\n'
+              "   print(A.Alias.__value__)  # <type 'A.Nested'>\n"
+              '\n'
+              '\n'
+              'Annotation scopes\n'
+              '-----------------\n'
+              '\n'
+              'Type parameter lists and "type" statements introduce '
+              '*annotation\n'
+              'scopes*, which behave mostly like function scopes, but with '
+              'some\n'
+              'exceptions discussed below. *Annotations* currently do not use\n'
+              'annotation scopes, but they are expected to use annotation '
+              'scopes in\n'
+              'Python 3.13 when **PEP 649** is implemented.\n'
+              '\n'
+              'Annotation scopes are used in the following contexts:\n'
+              '\n'
+              '* Type parameter lists for generic type aliases.\n'
+              '\n'
+              '* Type parameter lists for generic functions. A generic '
+              'function’s\n'
+              '  annotations are executed within the annotation scope, but '
+              'its\n'
+              '  defaults and decorators are not.\n'
+              '\n'
+              '* Type parameter lists for generic classes. A generic class’s '
+              'base\n'
+              '  classes and keyword arguments are executed within the '
+              'annotation\n'
+              '  scope, but its decorators are not.\n'
+              '\n'
+              '* The bounds and constraints for type variables (lazily '
+              'evaluated).\n'
+              '\n'
+              '* The value of type aliases (lazily evaluated).\n'
+              '\n'
+              'Annotation scopes differ from function scopes in the following '
+              'ways:\n'
+              '\n'
+              '* Annotation scopes have access to their enclosing class '
+              'namespace. If\n'
+              '  an annotation scope is immediately within a class scope, or '
+              'within\n'
+              '  another annotation scope that is immediately within a class '
+              'scope,\n'
+              '  the code in the annotation scope can use names defined in the '
+              'class\n'
+              '  scope as if it were executed directly within the class body. '
+              'This\n'
+              '  contrasts with regular functions defined within classes, '
+              'which\n'
+              '  cannot access names defined in the class scope.\n'
+              '\n'
+              '* Expressions in annotation scopes cannot contain "yield", '
+              '"yield\n'
+              '  from", "await", or ":=" expressions. (These expressions are '
+              'allowed\n'
+              '  in other scopes contained within the annotation scope.)\n'
+              '\n'
+              '* Names defined in annotation scopes cannot be rebound with '
+              '"nonlocal"\n'
+              '  statements in inner scopes. This includes only type '
+              'parameters, as\n'
+              '  no other syntactic elements that can appear within annotation '
+              'scopes\n'
+              '  can introduce new names.\n'
+              '\n'
+              '* While annotation scopes have an internal name, that name is '
+              'not\n'
+              '  reflected in the *__qualname__* of objects defined within the '
+              'scope.\n'
+              '  Instead, the "__qualname__" of such objects is as if the '
+              'object were\n'
+              '  defined in the enclosing scope.\n'
+              '\n'
+              'New in version 3.12: Annotation scopes were introduced in '
+              'Python 3.12\n'
+              'as part of **PEP 695**.\n'
+              '\n'
+              '\n'
+              'Lazy evaluation\n'
+              '---------------\n'
+              '\n'
+              'The values of type aliases created through the "type" statement '
+              'are\n'
+              '*lazily evaluated*. The same applies to the bounds and '
+              'constraints of\n'
+              'type variables created through the type parameter syntax. This '
+              'means\n'
+              'that they are not evaluated when the type alias or type '
+              'variable is\n'
+              'created. Instead, they are only evaluated when doing so is '
+              'necessary\n'
+              'to resolve an attribute access.\n'
+              '\n'
+              'Example:\n'
+              '\n'
+              '   >>> type Alias = 1/0\n'
+              '   >>> Alias.__value__\n'
+              '   Traceback (most recent call last):\n'
+              '     ...\n'
+              '   ZeroDivisionError: division by zero\n'
+              '   >>> def func[T: 1/0](): pass\n'
+              '   >>> T = func.__type_params__[0]\n'
+              '   >>> T.__bound__\n'
+              '   Traceback (most recent call last):\n'
+              '     ...\n'
+              '   ZeroDivisionError: division by zero\n'
+              '\n'
+              'Here the exception is raised only when the "__value__" '
+              'attribute of\n'
+              'the type alias or the "__bound__" attribute of the type '
+              'variable is\n'
+              'accessed.\n'
+              '\n'
+              'This behavior is primarily useful for references to types that '
+              'have\n'
+              'not yet been defined when the type alias or type variable is '
+              'created.\n'
+              'For example, lazy evaluation enables creation of mutually '
+              'recursive\n'
+              'type aliases:\n'
+              '\n'
+              '   from typing import Literal\n'
+              '\n'
+              '   type SimpleExpr = int | Parenthesized\n'
+              '   type Parenthesized = tuple[Literal["("], Expr, '
+              'Literal[")"]]\n'
+              '   type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", '
+              '"-"], Expr]\n'
+              '\n'
+              'Lazily evaluated values are evaluated in annotation scope, '
+              'which means\n'
+              'that names that appear inside the lazily evaluated value are '
+              'looked up\n'
+              'as if they were used in the immediately enclosing scope.\n'
+              '\n'
+              'New in version 3.12.\n'
+              '\n'
               '\n'
               'Builtins and restricted execution\n'
               '---------------------------------\n'
@@ -6872,8 +7258,8 @@ topics = {'assert': 'The "assert" statement\n'
              '(see\n'
              'section The standard type hierarchy):\n'
              '\n'
-             '   funcdef                   ::= [decorators] "def" funcname "(" '
-             '[parameter_list] ")"\n'
+             '   funcdef                   ::= [decorators] "def" funcname '
+             '[type_params] "(" [parameter_list] ")"\n'
              '               ["->" expression] ":" suite\n'
              '   decorators                ::= decorator+\n'
              '   decorator                 ::= "@" assignment_expression '
@@ -6935,6 +7321,19 @@ topics = {'assert': 'The "assert" statement\n'
              '"assignment_expression". Previously, the grammar was much more\n'
              'restrictive; see **PEP 614** for details.\n'
              '\n'
+             'A list of type parameters may be given in square brackets '
+             'between the\n'
+             'function’s name and the opening parenthesis for its parameter '
+             'list.\n'
+             'This indicates to static type checkers that the function is '
+             'generic.\n'
+             'At runtime, the type parameters can be retrieved from the '
+             'function’s\n'
+             '"__type_params__" attribute. See Generic functions for more.\n'
+             '\n'
+             'Changed in version 3.12: Type parameter lists are new in Python '
+             '3.12.\n'
+             '\n'
              'When one or more *parameters* have the form *parameter* "="\n'
              '*expression*, the function is said to have “default parameter '
              'values.”\n'
@@ -7277,19 +7676,24 @@ topics = {'assert': 'The "assert" statement\n'
                 '\n'
                 'Some identifiers are only reserved under specific contexts. '
                 'These are\n'
-                'known as *soft keywords*.  The identifiers "match", "case" '
-                'and "_" can\n'
-                'syntactically act as keywords in contexts related to the '
-                'pattern\n'
-                'matching statement, but this distinction is done at the '
-                'parser level,\n'
-                'not when tokenizing.\n'
+                'known as *soft keywords*.  The identifiers "match", "case", '
+                '"type" and\n'
+                '"_" can syntactically act as keywords in certain contexts, '
+                'but this\n'
+                'distinction is done at the parser level, not when '
+                'tokenizing.\n'
+                '\n'
+                'As soft keywords, their use in the grammar is possible while '
+                'still\n'
+                'preserving compatibility with existing code that uses these '
+                'names as\n'
+                'identifier names.\n'
+                '\n'
+                '"match", "case", and "_" are used in the "match" statement. '
+                '"type" is\n'
+                'used in the "type" statement.\n'
                 '\n'
-                'As soft keywords, their use with pattern matching is possible '
-                'while\n'
-                'still preserving compatibility with existing code that uses '
-                '"match",\n'
-                '"case" and "_" as identifier names.\n'
+                'Changed in version 3.12: "type" is now a soft keyword.\n'
                 '\n'
                 '\n'
                 'Reserved classes of identifiers\n'
@@ -7809,6 +8213,10 @@ topics = {'assert': 'The "assert" statement\n'
            '\n'
            '* "import" statements.\n'
            '\n'
+           '* "type" statements.\n'
+           '\n'
+           '* type parameter lists.\n'
+           '\n'
            'The "import" statement of the form "from ... import *" binds all '
            'names\n'
            'defined in the imported module, except those beginning with an\n'
@@ -7908,7 +8316,8 @@ topics = {'assert': 'The "assert" statement\n'
            'scope.\n'
            '"SyntaxError" is raised at compile time if the given name does '
            'not\n'
-           'exist in any enclosing function scope.\n'
+           'exist in any enclosing function scope. Type parameters cannot be\n'
+           'rebound with the "nonlocal" statement.\n'
            '\n'
            'The namespace for a module is automatically created the first time '
            'a\n'
@@ -7930,18 +8339,156 @@ topics = {'assert': 'The "assert" statement\n'
            'of\n'
            'the class. The scope of names defined in a class block is limited '
            'to\n'
-           'the class block; it does not extend to the code blocks of methods '
-           '–\n'
-           'this includes comprehensions and generator expressions since they '
-           'are\n'
-           'implemented using a function scope.  This means that the '
-           'following\n'
-           'will fail:\n'
+           'the class block; it does not extend to the code blocks of '
+           'methods.\n'
+           'This includes comprehensions and generator expressions, but it '
+           'does\n'
+           'not include annotation scopes, which have access to their '
+           'enclosing\n'
+           'class scopes. This means that the following will fail:\n'
            '\n'
            '   class A:\n'
            '       a = 42\n'
            '       b = list(a + i for i in range(10))\n'
            '\n'
+           'However, the following will succeed:\n'
+           '\n'
+           '   class A:\n'
+           '       type Alias = Nested\n'
+           '       class Nested: pass\n'
+           '\n'
+           "   print(A.Alias.__value__)  # <type 'A.Nested'>\n"
+           '\n'
+           '\n'
+           'Annotation scopes\n'
+           '=================\n'
+           '\n'
+           'Type parameter lists and "type" statements introduce *annotation\n'
+           'scopes*, which behave mostly like function scopes, but with some\n'
+           'exceptions discussed below. *Annotations* currently do not use\n'
+           'annotation scopes, but they are expected to use annotation scopes '
+           'in\n'
+           'Python 3.13 when **PEP 649** is implemented.\n'
+           '\n'
+           'Annotation scopes are used in the following contexts:\n'
+           '\n'
+           '* Type parameter lists for generic type aliases.\n'
+           '\n'
+           '* Type parameter lists for generic functions. A generic '
+           'function’s\n'
+           '  annotations are executed within the annotation scope, but its\n'
+           '  defaults and decorators are not.\n'
+           '\n'
+           '* Type parameter lists for generic classes. A generic class’s '
+           'base\n'
+           '  classes and keyword arguments are executed within the '
+           'annotation\n'
+           '  scope, but its decorators are not.\n'
+           '\n'
+           '* The bounds and constraints for type variables (lazily '
+           'evaluated).\n'
+           '\n'
+           '* The value of type aliases (lazily evaluated).\n'
+           '\n'
+           'Annotation scopes differ from function scopes in the following '
+           'ways:\n'
+           '\n'
+           '* Annotation scopes have access to their enclosing class '
+           'namespace. If\n'
+           '  an annotation scope is immediately within a class scope, or '
+           'within\n'
+           '  another annotation scope that is immediately within a class '
+           'scope,\n'
+           '  the code in the annotation scope can use names defined in the '
+           'class\n'
+           '  scope as if it were executed directly within the class body. '
+           'This\n'
+           '  contrasts with regular functions defined within classes, which\n'
+           '  cannot access names defined in the class scope.\n'
+           '\n'
+           '* Expressions in annotation scopes cannot contain "yield", "yield\n'
+           '  from", "await", or ":=" expressions. (These expressions are '
+           'allowed\n'
+           '  in other scopes contained within the annotation scope.)\n'
+           '\n'
+           '* Names defined in annotation scopes cannot be rebound with '
+           '"nonlocal"\n'
+           '  statements in inner scopes. This includes only type parameters, '
+           'as\n'
+           '  no other syntactic elements that can appear within annotation '
+           'scopes\n'
+           '  can introduce new names.\n'
+           '\n'
+           '* While annotation scopes have an internal name, that name is not\n'
+           '  reflected in the *__qualname__* of objects defined within the '
+           'scope.\n'
+           '  Instead, the "__qualname__" of such objects is as if the object '
+           'were\n'
+           '  defined in the enclosing scope.\n'
+           '\n'
+           'New in version 3.12: Annotation scopes were introduced in Python '
+           '3.12\n'
+           'as part of **PEP 695**.\n'
+           '\n'
+           '\n'
+           'Lazy evaluation\n'
+           '===============\n'
+           '\n'
+           'The values of type aliases created through the "type" statement '
+           'are\n'
+           '*lazily evaluated*. The same applies to the bounds and constraints '
+           'of\n'
+           'type variables created through the type parameter syntax. This '
+           'means\n'
+           'that they are not evaluated when the type alias or type variable '
+           'is\n'
+           'created. Instead, they are only evaluated when doing so is '
+           'necessary\n'
+           'to resolve an attribute access.\n'
+           '\n'
+           'Example:\n'
+           '\n'
+           '   >>> type Alias = 1/0\n'
+           '   >>> Alias.__value__\n'
+           '   Traceback (most recent call last):\n'
+           '     ...\n'
+           '   ZeroDivisionError: division by zero\n'
+           '   >>> def func[T: 1/0](): pass\n'
+           '   >>> T = func.__type_params__[0]\n'
+           '   >>> T.__bound__\n'
+           '   Traceback (most recent call last):\n'
+           '     ...\n'
+           '   ZeroDivisionError: division by zero\n'
+           '\n'
+           'Here the exception is raised only when the "__value__" attribute '
+           'of\n'
+           'the type alias or the "__bound__" attribute of the type variable '
+           'is\n'
+           'accessed.\n'
+           '\n'
+           'This behavior is primarily useful for references to types that '
+           'have\n'
+           'not yet been defined when the type alias or type variable is '
+           'created.\n'
+           'For example, lazy evaluation enables creation of mutually '
+           'recursive\n'
+           'type aliases:\n'
+           '\n'
+           '   from typing import Literal\n'
+           '\n'
+           '   type SimpleExpr = int | Parenthesized\n'
+           '   type Parenthesized = tuple[Literal["("], Expr, Literal[")"]]\n'
+           '   type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", "-"], '
+           'Expr]\n'
+           '\n'
+           'Lazily evaluated values are evaluated in annotation scope, which '
+           'means\n'
+           'that names that appear inside the lazily evaluated value are '
+           'looked up\n'
+           'as if they were used in the immediately enclosing scope.\n'
+           '\n'
+           'New in version 3.12.\n'
+           '\n'
            '\n'
            'Builtins and restricted execution\n'
            '=================================\n'
@@ -9105,6 +9652,14 @@ topics = {'assert': 'The "assert" statement\n'
                  '\n'
                  '   New in version 3.3.\n'
                  '\n'
+                 'definition.__type_params__\n'
+                 '\n'
+                 '   The type parameters of generic classes, functions, and '
+                 'type\n'
+                 '   aliases.\n'
+                 '\n'
+                 '   New in version 3.12.\n'
+                 '\n'
                  'class.__mro__\n'
                  '\n'
                  '   This attribute is a tuple of classes that are considered '
@@ -13430,6 +13985,14 @@ topics = {'assert': 'The "assert" statement\n'
           '|             |\n'
           '      '
           '+---------------------------+---------------------------------+-------------+\n'
+          '      | "__type_params__"         | A tuple containing the type     '
+          '| Writable    |\n'
+          '      |                           | parameters of a generic         '
+          '|             |\n'
+          '      |                           | function.                       '
+          '|             |\n'
+          '      '
+          '+---------------------------+---------------------------------+-------------+\n'
           '\n'
           '      Most of the attributes labelled “Writable” check the type of '
           'the\n'
@@ -13754,6 +14317,10 @@ topics = {'assert': 'The "assert" statement\n'
           '         with "__annotations__", please see Annotations Best\n'
           '         Practices.\n'
           '\n'
+          '      "__type_params__"\n'
+          '         A tuple containing the type parameters of a generic '
+          'class.\n'
+          '\n'
           'Class instances\n'
           '   A class instance is created by calling a class object (see '
           'above).\n'