Python 3.10.1
diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py
index 7720694..00c98ad 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 Oct 4 18:28:12 2021
+# Autogenerated by Sphinx on Mon Dec 6 17:57:38 2021
topics = {'assert': 'The "assert" statement\n'
'**********************\n'
'\n'
@@ -3339,9 +3339,9 @@
'\n'
'The same keyword should not be repeated in class patterns.\n'
'\n'
- 'The following is the logical flow for matching a mapping '
- 'pattern\n'
- 'against a subject value:\n'
+ 'The following is the logical flow for matching a class pattern '
+ 'against\n'
+ 'a subject value:\n'
'\n'
'1. If "name_or_attr" is not an instance of the builtin "type" , '
'raise\n'
@@ -5488,20 +5488,32 @@
'binding\n'
'operations.\n'
'\n'
- 'The following constructs bind names: formal parameters to '
- 'functions,\n'
- '"import" statements, class and function definitions (these bind '
- 'the\n'
- 'class or function name in the defining block), and targets that '
- 'are\n'
- 'identifiers if occurring in an assignment, "for" loop header, '
- 'or after\n'
- '"as" in a "with" statement or "except" clause. The "import" '
- 'statement\n'
- 'of the form "from ... import *" binds all names defined in the\n'
- 'imported module, except those beginning with an underscore. '
- 'This form\n'
- 'may only be used at the module level.\n'
+ 'The following constructs bind names:\n'
+ '\n'
+ '* formal parameters to functions,\n'
+ '\n'
+ '* class definitions,\n'
+ '\n'
+ '* function definitions,\n'
+ '\n'
+ '* assignment expressions,\n'
+ '\n'
+ '* targets that are identifiers if occurring in an assignment:\n'
+ '\n'
+ ' * "for" loop header,\n'
+ '\n'
+ ' * after "as" in a "with" statement, "except" clause or in the '
+ 'as-\n'
+ ' pattern in structural pattern matching,\n'
+ '\n'
+ ' * in a capture pattern in structural pattern matching\n'
+ '\n'
+ '* "import" statements.\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'
+ 'underscore. This form may only be used at the module level.\n'
'\n'
'A target occurring in a "del" statement is also considered '
'bound for\n'
@@ -5574,9 +5586,9 @@
'operations.\n'
'\n'
'If the "global" statement occurs within a block, all uses of '
- 'the name\n'
- 'specified in the statement refer to the binding of that name in '
- 'the\n'
+ 'the names\n'
+ 'specified in the statement refer to the bindings of those names '
+ 'in the\n'
'top-level namespace. Names are resolved in the top-level '
'namespace by\n'
'searching the global namespace, i.e. the namespace of the '
@@ -5585,9 +5597,10 @@
'namespace\n'
'of the module "builtins". The global namespace is searched '
'first. If\n'
- 'the name is not found there, the builtins namespace is '
- 'searched. The\n'
- '"global" statement must precede all uses of the name.\n'
+ 'the names are not found there, the builtins namespace is '
+ 'searched.\n'
+ 'The "global" statement must precede all uses of the listed '
+ 'names.\n'
'\n'
'The "global" statement has the same scope as a name binding '
'operation\n'
@@ -6943,22 +6956,31 @@
'trailing underscore characters:\n'
'\n'
'"_*"\n'
- ' Not imported by "from module import *". The special '
- 'identifier "_"\n'
- ' is used in the interactive interpreter to store the result '
- 'of the\n'
- ' last evaluation; it is stored in the "builtins" module. '
- 'When not\n'
- ' in interactive mode, "_" has no special meaning and is not '
- 'defined.\n'
- ' See section The import statement.\n'
+ ' Not imported by "from module import *".\n'
+ '\n'
+ '"_"\n'
+ ' In a "case" pattern within a "match" statement, "_" is a '
+ 'soft\n'
+ ' keyword that denotes a wildcard.\n'
+ '\n'
+ ' Separately, the interactive interpreter makes the result of '
+ 'the\n'
+ ' last evaluation available in the variable "_". (It is '
+ 'stored in the\n'
+ ' "builtins" module, alongside built-in functions like '
+ '"print".)\n'
+ '\n'
+ ' Elsewhere, "_" is a regular identifier. It is often used to '
+ 'name\n'
+ ' “special” items, but it is not special to Python itself.\n'
'\n'
' Note:\n'
'\n'
' The name "_" is often used in conjunction with\n'
' internationalization; refer to the documentation for the\n'
' "gettext" module for more information on this '
- 'convention.\n'
+ 'convention.It is\n'
+ ' also commonly used for unused variables.\n'
'\n'
'"__*__"\n'
' System-defined names, informally known as “dunder” names. '
@@ -7113,15 +7135,23 @@
'trailing underscore characters:\n'
'\n'
'"_*"\n'
- ' Not imported by "from module import *". The special '
- 'identifier "_"\n'
- ' is used in the interactive interpreter to store the result '
+ ' Not imported by "from module import *".\n'
+ '\n'
+ '"_"\n'
+ ' In a "case" pattern within a "match" statement, "_" is a '
+ 'soft\n'
+ ' keyword that denotes a wildcard.\n'
+ '\n'
+ ' Separately, the interactive interpreter makes the result '
'of the\n'
- ' last evaluation; it is stored in the "builtins" module. '
- 'When not\n'
- ' in interactive mode, "_" has no special meaning and is not '
- 'defined.\n'
- ' See section The import statement.\n'
+ ' last evaluation available in the variable "_". (It is '
+ 'stored in the\n'
+ ' "builtins" module, alongside built-in functions like '
+ '"print".)\n'
+ '\n'
+ ' Elsewhere, "_" is a regular identifier. It is often used '
+ 'to name\n'
+ ' “special” items, but it is not special to Python itself.\n'
'\n'
' Note:\n'
'\n'
@@ -7129,7 +7159,8 @@
' internationalization; refer to the documentation for '
'the\n'
' "gettext" module for more information on this '
- 'convention.\n'
+ 'convention.It is\n'
+ ' also commonly used for unused variables.\n'
'\n'
'"__*__"\n'
' System-defined names, informally known as “dunder” names. '
@@ -7590,20 +7621,32 @@
'*Names* refer to objects. Names are introduced by name binding\n'
'operations.\n'
'\n'
- 'The following constructs bind names: formal parameters to '
- 'functions,\n'
- '"import" statements, class and function definitions (these bind '
- 'the\n'
- 'class or function name in the defining block), and targets that '
- 'are\n'
- 'identifiers if occurring in an assignment, "for" loop header, or '
- 'after\n'
- '"as" in a "with" statement or "except" clause. The "import" '
- 'statement\n'
- 'of the form "from ... import *" binds all names defined in the\n'
- 'imported module, except those beginning with an underscore. This '
- 'form\n'
- 'may only be used at the module level.\n'
+ 'The following constructs bind names:\n'
+ '\n'
+ '* formal parameters to functions,\n'
+ '\n'
+ '* class definitions,\n'
+ '\n'
+ '* function definitions,\n'
+ '\n'
+ '* assignment expressions,\n'
+ '\n'
+ '* targets that are identifiers if occurring in an assignment:\n'
+ '\n'
+ ' * "for" loop header,\n'
+ '\n'
+ ' * after "as" in a "with" statement, "except" clause or in the '
+ 'as-\n'
+ ' pattern in structural pattern matching,\n'
+ '\n'
+ ' * in a capture pattern in structural pattern matching\n'
+ '\n'
+ '* "import" statements.\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'
+ 'underscore. This form may only be used at the module level.\n'
'\n'
'A target occurring in a "del" statement is also considered bound '
'for\n'
@@ -7673,8 +7716,8 @@
'operations.\n'
'\n'
'If the "global" statement occurs within a block, all uses of the '
- 'name\n'
- 'specified in the statement refer to the binding of that name in '
+ 'names\n'
+ 'specified in the statement refer to the bindings of those names in '
'the\n'
'top-level namespace. Names are resolved in the top-level '
'namespace by\n'
@@ -7683,9 +7726,9 @@
'namespace\n'
'of the module "builtins". The global namespace is searched '
'first. If\n'
- 'the name is not found there, the builtins namespace is searched. '
- 'The\n'
- '"global" statement must precede all uses of the name.\n'
+ 'the names are not found there, the builtins namespace is '
+ 'searched.\n'
+ 'The "global" statement must precede all uses of the listed names.\n'
'\n'
'The "global" statement has the same scope as a name binding '
'operation\n'
@@ -8020,9 +8063,9 @@
' of the object truncated to an "Integral" (typically an '
'"int").\n'
'\n'
- ' If "__int__()" is not defined then the built-in function '
- '"int()"\n'
- ' falls back to "__trunc__()".\n',
+ ' The built-in function "int()" falls back to '
+ '"__trunc__()" if\n'
+ ' neither "__int__()" nor "__index__()" is defined.\n',
'objects': 'Objects, values and types\n'
'*************************\n'
'\n'
@@ -8644,22 +8687,24 @@
'object.__getitem__(self, key)\n'
'\n'
' Called to implement evaluation of "self[key]". For '
- 'sequence types,\n'
- ' the accepted keys should be integers and slice '
- 'objects. Note that\n'
- ' the special interpretation of negative indexes (if the '
- 'class wishes\n'
- ' to emulate a sequence type) is up to the '
- '"__getitem__()" method. If\n'
- ' *key* is of an inappropriate type, "TypeError" may be '
- 'raised; if of\n'
- ' a value outside the set of indexes for the sequence '
- '(after any\n'
- ' special interpretation of negative values), '
- '"IndexError" should be\n'
- ' raised. For mapping types, if *key* is missing (not in '
+ '*sequence*\n'
+ ' types, the accepted keys should be integers and slice '
+ 'objects.\n'
+ ' Note that the special interpretation of negative '
+ 'indexes (if the\n'
+ ' class wishes to emulate a *sequence* type) is up to '
'the\n'
- ' container), "KeyError" should be raised.\n'
+ ' "__getitem__()" method. If *key* is of an inappropriate '
+ 'type,\n'
+ ' "TypeError" may be raised; if of a value outside the '
+ 'set of indexes\n'
+ ' for the sequence (after any special interpretation of '
+ 'negative\n'
+ ' values), "IndexError" should be raised. For *mapping* '
+ 'types, if\n'
+ ' *key* is missing (not in the container), "KeyError" '
+ 'should be\n'
+ ' raised.\n'
'\n'
' Note:\n'
'\n'
@@ -8669,6 +8714,15 @@
'of the\n'
' sequence.\n'
'\n'
+ ' Note:\n'
+ '\n'
+ ' When subscripting a *class*, the special class '
+ 'method\n'
+ ' "__class_getitem__()" may be called instead of '
+ '"__getitem__()".\n'
+ ' See __class_getitem__ versus __getitem__ for more '
+ 'details.\n'
+ '\n'
'object.__setitem__(self, key, value)\n'
'\n'
' Called to implement assignment to "self[key]". Same '
@@ -8704,19 +8758,13 @@
'\n'
'object.__iter__(self)\n'
'\n'
- ' This method is called when an iterator is required for '
- 'a container.\n'
- ' This method should return a new iterator object that '
- 'can iterate\n'
- ' over all the objects in the container. For mappings, '
- 'it should\n'
- ' iterate over the keys of the container.\n'
- '\n'
- ' Iterator objects also need to implement this method; '
- 'they are\n'
- ' required to return themselves. For more information on '
- 'iterator\n'
- ' objects, see Iterator Types.\n'
+ ' This method is called when an *iterator* is required '
+ 'for a\n'
+ ' container. This method should return a new iterator '
+ 'object that can\n'
+ ' iterate over all the objects in the container. For '
+ 'mappings, it\n'
+ ' should iterate over the keys of the container.\n'
'\n'
'object.__reversed__(self)\n'
'\n'
@@ -10294,9 +10342,33 @@
'Emulating generic types\n'
'=======================\n'
'\n'
- 'One can implement the generic class syntax as specified by '
- '**PEP 484**\n'
- '(for example "List[int]") by defining a special method:\n'
+ 'When using *type annotations*, it is often useful to '
+ '*parameterize* a\n'
+ '*generic type* using Python’s square-brackets notation. For '
+ 'example,\n'
+ 'the annotation "list[int]" might be used to signify a "list" '
+ 'in which\n'
+ 'all the elements are of type "int".\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 484** - Type Hints\n'
+ ' Introducing Python’s framework for type annotations\n'
+ '\n'
+ ' Generic Alias Types\n'
+ ' Documentation for objects representing parameterized '
+ 'generic\n'
+ ' classes\n'
+ '\n'
+ ' Generics, user-defined generics and "typing.Generic"\n'
+ ' Documentation on how to implement generic classes that '
+ 'can be\n'
+ ' parameterized at runtime and understood by static '
+ 'type-checkers.\n'
+ '\n'
+ 'A class can *generally* only be parameterized if it defines '
+ 'the\n'
+ 'special class method "__class_getitem__()".\n'
'\n'
'classmethod object.__class_getitem__(cls, key)\n'
'\n'
@@ -10304,18 +10376,144 @@
'generic class\n'
' by type arguments found in *key*.\n'
'\n'
- 'This method is looked up on the class object itself, and '
- 'when defined\n'
- 'in the class body, this method is implicitly a class '
- 'method. Note,\n'
- 'this mechanism is primarily reserved for use with static '
- 'type hints,\n'
- 'other usage is discouraged.\n'
+ ' When defined on a class, "__class_getitem__()" is '
+ 'automatically a\n'
+ ' class method. As such, there is no need for it to be '
+ 'decorated with\n'
+ ' "@classmethod" when it is defined.\n'
+ '\n'
+ '\n'
+ 'The purpose of *__class_getitem__*\n'
+ '----------------------------------\n'
+ '\n'
+ 'The purpose of "__class_getitem__()" is to allow runtime\n'
+ 'parameterization of standard-library generic classes in '
+ 'order to more\n'
+ 'easily apply *type hints* to these classes.\n'
+ '\n'
+ 'To implement custom generic classes that can be '
+ 'parameterized at\n'
+ 'runtime and understood by static type-checkers, users should '
+ 'either\n'
+ 'inherit from a standard library class that already '
+ 'implements\n'
+ '"__class_getitem__()", or inherit from "typing.Generic", '
+ 'which has its\n'
+ 'own implementation of "__class_getitem__()".\n'
+ '\n'
+ 'Custom implementations of "__class_getitem__()" on classes '
+ 'defined\n'
+ 'outside of the standard library may not be understood by '
+ 'third-party\n'
+ 'type-checkers such as mypy. Using "__class_getitem__()" on '
+ 'any class\n'
+ 'for purposes other than type hinting is discouraged.\n'
+ '\n'
+ '\n'
+ '*__class_getitem__* versus *__getitem__*\n'
+ '----------------------------------------\n'
+ '\n'
+ 'Usually, the subscription of an object using square brackets '
+ 'will call\n'
+ 'the "__getitem__()" instance method defined on the object’s '
+ 'class.\n'
+ 'However, if the object being subscribed is itself a class, '
+ 'the class\n'
+ 'method "__class_getitem__()" may be called instead.\n'
+ '"__class_getitem__()" should return a GenericAlias object if '
+ 'it is\n'
+ 'properly defined.\n'
+ '\n'
+ 'Presented with the *expression* "obj[x]", the Python '
+ 'interpreter\n'
+ 'follows something like the following process to decide '
+ 'whether\n'
+ '"__getitem__()" or "__class_getitem__()" should be called:\n'
+ '\n'
+ ' from inspect import isclass\n'
+ '\n'
+ ' def subscribe(obj, x):\n'
+ ' """Return the result of the expression `obj[x]`"""\n'
+ '\n'
+ ' class_of_obj = type(obj)\n'
+ '\n'
+ ' # If the class of obj defines __getitem__,\n'
+ ' # call class_of_obj.__getitem__(obj, x)\n'
+ " if hasattr(class_of_obj, '__getitem__'):\n"
+ ' return class_of_obj.__getitem__(obj, x)\n'
+ '\n'
+ ' # Else, if obj is a class and defines '
+ '__class_getitem__,\n'
+ ' # call obj.__class_getitem__(x)\n'
+ ' elif isclass(obj) and hasattr(obj, '
+ "'__class_getitem__'):\n"
+ ' return obj.__class_getitem__(x)\n'
+ '\n'
+ ' # Else, raise an exception\n'
+ ' else:\n'
+ ' raise TypeError(\n'
+ ' f"\'{class_of_obj.__name__}\' object is not '
+ 'subscriptable"\n'
+ ' )\n'
+ '\n'
+ 'In Python, all classes are themselves instances of other '
+ 'classes. The\n'
+ 'class of a class is known as that class’s *metaclass*, and '
+ 'most\n'
+ 'classes have the "type" class as their metaclass. "type" '
+ 'does not\n'
+ 'define "__getitem__()", meaning that expressions such as '
+ '"list[int]",\n'
+ '"dict[str, float]" and "tuple[str, bytes]" all result in\n'
+ '"__class_getitem__()" being called:\n'
+ '\n'
+ ' >>> # list has class "type" as its metaclass, like most '
+ 'classes:\n'
+ ' >>> type(list)\n'
+ " <class 'type'>\n"
+ ' >>> type(dict) == type(list) == type(tuple) == type(str) '
+ '== type(bytes)\n'
+ ' True\n'
+ ' >>> # "list[int]" calls "list.__class_getitem__(int)"\n'
+ ' >>> list[int]\n'
+ ' list[int]\n'
+ ' >>> # list.__class_getitem__ returns a GenericAlias '
+ 'object:\n'
+ ' >>> type(list[int])\n'
+ " <class 'types.GenericAlias'>\n"
+ '\n'
+ 'However, if a class has a custom metaclass that defines\n'
+ '"__getitem__()", subscribing the class may result in '
+ 'different\n'
+ 'behaviour. An example of this can be found in the "enum" '
+ 'module:\n'
+ '\n'
+ ' >>> from enum import Enum\n'
+ ' >>> class Menu(Enum):\n'
+ ' ... """A breakfast menu"""\n'
+ " ... SPAM = 'spam'\n"
+ " ... BACON = 'bacon'\n"
+ ' ...\n'
+ ' >>> # Enum classes have a custom metaclass:\n'
+ ' >>> type(Menu)\n'
+ " <class 'enum.EnumMeta'>\n"
+ ' >>> # EnumMeta defines __getitem__,\n'
+ ' >>> # so __class_getitem__ is not called,\n'
+ ' >>> # and the result is not a GenericAlias object:\n'
+ " >>> Menu['SPAM']\n"
+ " <Menu.SPAM: 'spam'>\n"
+ " >>> type(Menu['SPAM'])\n"
+ " <enum 'Menu'>\n"
'\n'
'See also:\n'
'\n'
- ' **PEP 560** - Core support for typing module and generic '
+ ' **PEP 560** - Core Support for typing module and generic '
'types\n'
+ ' Introducing "__class_getitem__()", and outlining when '
+ 'a\n'
+ ' subscription results in "__class_getitem__()" being '
+ 'called\n'
+ ' instead of "__getitem__()"\n'
'\n'
'\n'
'Emulating callable objects\n'
@@ -10445,22 +10643,23 @@
'object.__getitem__(self, key)\n'
'\n'
' Called to implement evaluation of "self[key]". For '
- 'sequence types,\n'
- ' the accepted keys should be integers and slice objects. '
- 'Note that\n'
- ' the special interpretation of negative indexes (if the '
- 'class wishes\n'
- ' to emulate a sequence type) is up to the "__getitem__()" '
- 'method. If\n'
- ' *key* is of an inappropriate type, "TypeError" may be '
- 'raised; if of\n'
- ' a value outside the set of indexes for the sequence '
- '(after any\n'
- ' special interpretation of negative values), "IndexError" '
+ '*sequence*\n'
+ ' types, the accepted keys should be integers and slice '
+ 'objects.\n'
+ ' Note that the special interpretation of negative indexes '
+ '(if the\n'
+ ' class wishes to emulate a *sequence* type) is up to the\n'
+ ' "__getitem__()" method. If *key* is of an inappropriate '
+ 'type,\n'
+ ' "TypeError" may be raised; if of a value outside the set '
+ 'of indexes\n'
+ ' for the sequence (after any special interpretation of '
+ 'negative\n'
+ ' values), "IndexError" should be raised. For *mapping* '
+ 'types, if\n'
+ ' *key* is missing (not in the container), "KeyError" '
'should be\n'
- ' raised. For mapping types, if *key* is missing (not in '
- 'the\n'
- ' container), "KeyError" should be raised.\n'
+ ' raised.\n'
'\n'
' Note:\n'
'\n'
@@ -10470,6 +10669,14 @@
'the\n'
' sequence.\n'
'\n'
+ ' Note:\n'
+ '\n'
+ ' When subscripting a *class*, the special class method\n'
+ ' "__class_getitem__()" may be called instead of '
+ '"__getitem__()".\n'
+ ' See __class_getitem__ versus __getitem__ for more '
+ 'details.\n'
+ '\n'
'object.__setitem__(self, key, value)\n'
'\n'
' Called to implement assignment to "self[key]". Same note '
@@ -10505,19 +10712,13 @@
'\n'
'object.__iter__(self)\n'
'\n'
- ' This method is called when an iterator is required for a '
- 'container.\n'
- ' This method should return a new iterator object that can '
- 'iterate\n'
- ' over all the objects in the container. For mappings, it '
- 'should\n'
- ' iterate over the keys of the container.\n'
- '\n'
- ' Iterator objects also need to implement this method; they '
- 'are\n'
- ' required to return themselves. For more information on '
- 'iterator\n'
- ' objects, see Iterator Types.\n'
+ ' This method is called when an *iterator* is required for '
+ 'a\n'
+ ' container. This method should return a new iterator '
+ 'object that can\n'
+ ' iterate over all the objects in the container. For '
+ 'mappings, it\n'
+ ' should iterate over the keys of the container.\n'
'\n'
'object.__reversed__(self)\n'
'\n'
@@ -10760,9 +10961,9 @@
' of the object truncated to an "Integral" (typically an '
'"int").\n'
'\n'
- ' If "__int__()" is not defined then the built-in function '
- '"int()"\n'
- ' falls back to "__trunc__()".\n'
+ ' The built-in function "int()" falls back to "__trunc__()" '
+ 'if\n'
+ ' neither "__int__()" nor "__index__()" is defined.\n'
'\n'
'\n'
'With Statement Context Managers\n'
@@ -12971,20 +13172,18 @@
' A function or method which uses the "yield" statement (see\n'
' section The yield statement) is called a *generator '
'function*.\n'
- ' Such a function, when called, always returns an iterator '
- 'object\n'
- ' which can be used to execute the body of the function: '
- 'calling\n'
- ' the iterator’s "iterator.__next__()" method will cause the\n'
- ' function to execute until it provides a value using the '
- '"yield"\n'
- ' statement. When the function executes a "return" statement '
- 'or\n'
- ' falls off the end, a "StopIteration" exception is raised and '
- 'the\n'
- ' iterator will have reached the end of the set of values to '
- 'be\n'
- ' returned.\n'
+ ' Such a function, when called, always returns an *iterator*\n'
+ ' object which can be used to execute the body of the '
+ 'function:\n'
+ ' calling the iterator’s "iterator.__next__()" method will '
+ 'cause\n'
+ ' the function to execute until it provides a value using the\n'
+ ' "yield" statement. When the function executes a "return"\n'
+ ' statement or falls off the end, a "StopIteration" exception '
+ 'is\n'
+ ' raised and the iterator will have reached the end of the set '
+ 'of\n'
+ ' values to be returned.\n'
'\n'
' Coroutine functions\n'
' A function or method which is defined using "async def" is\n'
@@ -13000,9 +13199,9 @@
' which uses the "yield" statement is called a *asynchronous\n'
' generator function*. Such a function, when called, returns '
'an\n'
- ' asynchronous iterator object which can be used in an "async '
- 'for"\n'
- ' statement to execute the body of the function.\n'
+ ' *asynchronous iterator* object which can be used in an '
+ '"async\n'
+ ' for" statement to execute the body of the function.\n'
'\n'
' Calling the asynchronous iterator’s "aiterator.__anext__()"\n'
' method will return an *awaitable* which when awaited will\n'