intermediate changes

ref:102662f6c42fba80d7bfd4a328124cbb4294be48

1 files changed, 100 insertions, 78 deletions

diff --git a/contrib/tools/python3/src/Lib/pydoc_data/topics.py b/contrib/tools/python3/src/Lib/pydoc_data/topics.py
index 67a51977cf..0e63c31f1b 100644
--- a/contrib/tools/python3/src/Lib/pydoc_data/topics.py
+++ b/contrib/tools/python3/src/Lib/pydoc_data/topics.py
@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Autogenerated by Sphinx on Thu Jan 13 21:46:32 2022
+# Autogenerated by Sphinx on Tue Mar 15 21:44:32 2022
 topics = {'assert': 'The "assert" statement\n'
            '**********************\n'
            '\n'
@@ -5408,19 +5408,19 @@ topics = {'assert': 'The "assert" statement\n'
                   'with an\n'
                   '*alignment* type of "\'=\'".\n'
                   '\n'
-                  'The *precision* is a decimal number indicating how many '
+                  'The *precision* is a decimal integer indicating how many '
                   'digits should\n'
-                  'be displayed after the decimal point for a floating point '
-                  'value\n'
-                  'formatted with "\'f\'" and "\'F\'", or before and after the '
-                  'decimal point\n'
-                  'for a floating point value formatted with "\'g\'" or '
-                  '"\'G\'".  For non-\n'
-                  'number types the field indicates the maximum field size - '
-                  'in other\n'
-                  'words, how many characters will be used from the field '
-                  'content. The\n'
-                  '*precision* is not allowed for integer values.\n'
+                  'be displayed after the decimal point for presentation types '
+                  '"\'f\'" and\n'
+                  '"\'F\'", or before and after the decimal point for '
+                  'presentation types\n'
+                  '"\'g\'" or "\'G\'".  For string presentation types the '
+                  'field indicates the\n'
+                  'maximum field size - in other words, how many characters '
+                  'will be used\n'
+                  'from the field content.  The *precision* is not allowed for '
+                  'integer\n'
+                  'presentation types.\n'
                   '\n'
                   'Finally, the *type* determines how the data should be '
                   'presented.\n'
@@ -7515,12 +7515,12 @@ topics = {'assert': 'The "assert" statement\n'
           '\n'
           '   raise_stmt ::= "raise" [expression ["from" expression]]\n'
           '\n'
-          'If no expressions are present, "raise" re-raises the last '
-          'exception\n'
-          'that was active in the current scope.  If no exception is active '
-          'in\n'
-          'the current scope, a "RuntimeError" exception is raised indicating\n'
-          'that this is an error.\n'
+          'If no expressions are present, "raise" re-raises the exception that '
+          'is\n'
+          'currently being handled, which is also known as the *active\n'
+          'exception*. If there isn’t currently an active exception, a\n'
+          '"RuntimeError" exception is raised indicating that this is an '
+          'error.\n'
           '\n'
           'Otherwise, "raise" evaluates the first expression as the exception\n'
           'object.  It must be either a subclass or an instance of\n'
@@ -7575,11 +7575,14 @@ topics = {'assert': 'The "assert" statement\n'
           '     File "<stdin>", line 4, in <module>\n'
           '   RuntimeError: Something bad happened\n'
           '\n'
-          'A similar mechanism works implicitly if an exception is raised '
-          'inside\n'
-          'an exception handler or a "finally" clause: the previous exception '
-          'is\n'
-          'then attached as the new exception’s "__context__" attribute:\n'
+          'A similar mechanism works implicitly if a new exception is raised '
+          'when\n'
+          'an exception is already being handled.  An exception may be '
+          'handled\n'
+          'when an "except" or "finally" clause, or a "with" statement, is '
+          'used.\n'
+          'The previous exception is then attached as the new exception’s\n'
+          '"__context__" attribute:\n'
           '\n'
           '   >>> try:\n'
           '   ...     print(1 / 0)\n'
@@ -9079,14 +9082,14 @@ topics = {'assert': 'The "assert" statement\n'
                  '\n'
                  'Whenever a class inherits from another class, '
                  '"__init_subclass__()" is\n'
-                 'called on that class. This way, it is possible to write '
-                 'classes which\n'
-                 'change the behavior of subclasses. This is closely related '
-                 'to class\n'
-                 'decorators, but where class decorators only affect the '
-                 'specific class\n'
-                 'they’re applied to, "__init_subclass__" solely applies to '
-                 'future\n'
+                 'called on the parent class. This way, it is possible to '
+                 'write classes\n'
+                 'which change the behavior of subclasses. This is closely '
+                 'related to\n'
+                 'class decorators, but where class decorators only affect the '
+                 'specific\n'
+                 'class they’re applied to, "__init_subclass__" solely applies '
+                 'to future\n'
                  'subclasses of the class defining the method.\n'
                  '\n'
                  'classmethod object.__init_subclass__(cls)\n'
@@ -11393,67 +11396,86 @@ topics = {'assert': 'The "assert" statement\n'
  'subscriptions': 'Subscriptions\n'
                   '*************\n'
                   '\n'
-                  'Subscription of a sequence (string, tuple or list) or '
-                  'mapping\n'
-                  '(dictionary) object usually selects an item from the '
-                  'collection:\n'
+                  'The subscription of an instance of a container class will '
+                  'generally\n'
+                  'select an element from the container. The subscription of a '
+                  '*generic\n'
+                  'class* will generally return a GenericAlias object.\n'
                   '\n'
                   '   subscription ::= primary "[" expression_list "]"\n'
                   '\n'
+                  'When an object is subscripted, the interpreter will '
+                  'evaluate the\n'
+                  'primary and the expression list.\n'
+                  '\n'
                   'The primary must evaluate to an object that supports '
-                  'subscription\n'
-                  '(lists or dictionaries for example).  User-defined objects '
-                  'can support\n'
-                  'subscription by defining a "__getitem__()" method.\n'
+                  'subscription. An\n'
+                  'object may support subscription through defining one or '
+                  'both of\n'
+                  '"__getitem__()" and "__class_getitem__()". When the primary '
+                  'is\n'
+                  'subscripted, the evaluated result of the expression list '
+                  'will be\n'
+                  'passed to one of these methods. For more details on when\n'
+                  '"__class_getitem__" is called instead of "__getitem__", '
+                  'see\n'
+                  '__class_getitem__ versus __getitem__.\n'
+                  '\n'
+                  'If the expression list contains at least one comma, it will '
+                  'evaluate\n'
+                  'to a "tuple" containing the items of the expression list. '
+                  'Otherwise,\n'
+                  'the expression list will evaluate to the value of the '
+                  'list’s sole\n'
+                  'member.\n'
                   '\n'
                   'For built-in objects, there are two types of objects that '
                   'support\n'
-                  'subscription:\n'
+                  'subscription via "__getitem__()":\n'
                   '\n'
-                  'If the primary is a mapping, the expression list must '
-                  'evaluate to an\n'
-                  'object whose value is one of the keys of the mapping, and '
+                  '1. Mappings. If the primary is a *mapping*, the expression '
+                  'list must\n'
+                  '   evaluate to an object whose value is one of the keys of '
                   'the\n'
-                  'subscription selects the value in the mapping that '
-                  'corresponds to that\n'
-                  'key.  (The expression list is a tuple except if it has '
-                  'exactly one\n'
-                  'item.)\n'
-                  '\n'
-                  'If the primary is a sequence, the expression list must '
-                  'evaluate to an\n'
-                  'integer or a slice (as discussed in the following '
-                  'section).\n'
+                  '   mapping, and the subscription selects the value in the '
+                  'mapping that\n'
+                  '   corresponds to that key. An example of a builtin mapping '
+                  'class is\n'
+                  '   the "dict" class.\n'
+                  '\n'
+                  '2. Sequences. If the primary is a *sequence*, the '
+                  'expression list must\n'
+                  '   evaluate to an "int" or a "slice" (as discussed in the '
+                  'following\n'
+                  '   section). Examples of builtin sequence classes include '
+                  'the "str",\n'
+                  '   "list" and "tuple" classes.\n'
                   '\n'
                   'The formal syntax makes no special provision for negative '
                   'indices in\n'
-                  'sequences; however, built-in sequences all provide a '
+                  '*sequences*. However, built-in sequences all provide a '
                   '"__getitem__()"\n'
                   'method that interprets negative indices by adding the '
                   'length of the\n'
-                  'sequence to the index (so that "x[-1]" selects the last '
-                  'item of "x").\n'
-                  'The resulting value must be a nonnegative integer less than '
-                  'the number\n'
-                  'of items in the sequence, and the subscription selects the '
-                  'item whose\n'
-                  'index is that value (counting from zero). Since the support '
-                  'for\n'
-                  'negative indices and slicing occurs in the object’s '
-                  '"__getitem__()"\n'
-                  'method, subclasses overriding this method will need to '
-                  'explicitly add\n'
-                  'that support.\n'
-                  '\n'
-                  'A string’s items are characters.  A character is not a '
-                  'separate data\n'
-                  'type but a string of exactly one character.\n'
-                  '\n'
-                  'Subscription of certain *classes* or *types* creates a '
-                  'generic alias.\n'
-                  'In this case, user-defined classes can support subscription '
-                  'by\n'
-                  'providing a "__class_getitem__()" classmethod.\n',
+                  'sequence to the index so that, for example, "x[-1]" selects '
+                  'the last\n'
+                  'item of "x". The resulting value must be a nonnegative '
+                  'integer less\n'
+                  'than the number of items in the sequence, and the '
+                  'subscription selects\n'
+                  'the item whose index is that value (counting from zero). '
+                  'Since the\n'
+                  'support for negative indices and slicing occurs in the '
+                  'object’s\n'
+                  '"__getitem__()" method, subclasses overriding this method '
+                  'will need to\n'
+                  'explicitly add that support.\n'
+                  '\n'
+                  'A "string" is a special kind of sequence whose items are '
+                  '*characters*.\n'
+                  'A character is not a separate data type but a string of '
+                  'exactly one\n'
+                  'character.\n',
  'truth': 'Truth Value Testing\n'
           '*******************\n'
           '\n'