topics.py

             '~~~~~~~~~~~\n'
             '\n'
             'An OR pattern is two or more patterns separated by vertical bars '
             '"|".\n'
             'Syntax:\n'
             '\n'
             '   or_pattern ::= "|".closed_pattern+\n'
             '\n'
             'Only the final subpattern may be irrefutable, and each '
             'subpattern must\n'
             'bind the same set of names to avoid ambiguity.\n'
             '\n'
             'An OR pattern matches each of its subpatterns in turn to the '
             'subject\n'
             'value, until one succeeds.  The OR pattern is then considered\n'
             'successful.  Otherwise, if none of the subpatterns succeed, the '
             'OR\n'
             'pattern fails.\n'
             '\n'
             'In simple terms, "P1 | P2 | ..." will try to match "P1", if it '
             'fails\n'
             'it will try to match "P2", succeeding immediately if any '
             'succeeds,\n'
             'failing otherwise.\n'
             '\n'
             '\n'
             'AS Patterns\n'
             '~~~~~~~~~~~\n'
             '\n'
             'An AS pattern matches an OR pattern on the left of the "as" '
             'keyword\n'
             'against a subject.  Syntax:\n'
             '\n'
             '   as_pattern ::= or_pattern "as" capture_pattern\n'
             '\n'
             'If the OR pattern fails, the AS pattern fails.  Otherwise, the '
             'AS\n'
             'pattern binds the subject to the name on the right of the as '
             'keyword\n'
             'and succeeds. "capture_pattern" cannot be a a "_".\n'
             '\n'
             'In simple terms "P as NAME" will match with "P", and on success '
             'it\n'
             'will set "NAME = <subject>".\n'
             '\n'
             '\n'
             'Literal Patterns\n'
             '~~~~~~~~~~~~~~~~\n'
             '\n'
             'A literal pattern corresponds to most literals in Python.  '
             'Syntax:\n'
             '\n'
             '   literal_pattern ::= signed_number\n'
             '                       | signed_number "+" NUMBER\n'
             '                       | signed_number "-" NUMBER\n'
             '                       | strings\n'
             '                       | "None"\n'
             '                       | "True"\n'
             '                       | "False"\n'
             '                       | signed_number: NUMBER | "-" NUMBER\n'
             '\n'
             'The rule "strings" and the token "NUMBER" are defined in the '
             'standard\n'
             'Python grammar.  Triple-quoted strings are supported.  Raw '
             'strings and\n'
             'byte strings are supported.  Formatted string literals are not\n'
             'supported.\n'
             '\n'
             'The forms "signed_number \'+\' NUMBER" and "signed_number \'-\' '
             'NUMBER"\n'
             'are for expressing complex numbers; they require a real number '
             'on the\n'
             'left and an imaginary number on the right. E.g. "3 + 4j".\n'
             '\n'
             'In simple terms, "LITERAL" will succeed only if "<subject> ==\n'
             'LITERAL". For the singletons "None", "True" and "False", the '
             '"is"\n'
             'operator is used.\n'
             '\n'
             '\n'
             'Capture Patterns\n'
             '~~~~~~~~~~~~~~~~\n'
             '\n'
             'A capture pattern binds the subject value to a name. Syntax:\n'
             '\n'
             "   capture_pattern ::= !'_' NAME\n"
             '\n'
             'A single underscore "_" is not a capture pattern (this is what '
             '"!\'_\'"\n'
             'expresses). It is instead treated as a "wildcard_pattern".\n'
             '\n'
             'In a given pattern, a given name can only be bound once.  E.g. '
             '"case\n'
             'x, x: ..." is invalid while "case [x] | x: ..." is allowed.\n'
             '\n'
             'Capture patterns always succeed.  The binding follows scoping '
             'rules\n'
             'established by the assignment expression operator in **PEP '
             '572**; the\n'
             'name becomes a local variable in the closest containing function '
             'scope\n'
             'unless there’s an applicable "global" or "nonlocal" statement.\n'
             '\n'
             'In simple terms "NAME" will always succeed and it will set "NAME '
             '=\n'
             '<subject>".\n'
             '\n'
             '\n'
             'Wildcard Patterns\n'
             '~~~~~~~~~~~~~~~~~\n'
             '\n'
             'A wildcard pattern always succeeds (matches anything) and binds '
             'no\n'
             'name.  Syntax:\n'
             '\n'
             "   wildcard_pattern ::= '_'\n"
             '\n'
             '"_" is a soft keyword within any pattern, but only within '
             'patterns.\n'
             'It is an identifier, as usual, even within "match" subject\n'
             'expressions, "guard"s, and "case" blocks.\n'
             '\n'
             'In simple terms, "_" will always succeed.\n'
             '\n'
             '\n'
             'Value Patterns\n'
             '~~~~~~~~~~~~~~\n'
             '\n'
             'A value pattern represents a named value in Python. Syntax:\n'
             '\n'
             '   value_pattern ::= attr\n'
             '   attr          ::= name_or_attr "." NAME\n'
             '   name_or_attr  ::= attr | NAME\n'
             '\n'
             'The dotted name in the pattern is looked up using standard '
             'Python name\n'
             'resolution rules.  The pattern succeeds if the value found '
             'compares\n'
             'equal to the subject value (using the "==" equality operator).\n'
             '\n'
             'In simple terms "NAME1.NAME2" will succeed only if "<subject> '
             '==\n'
             'NAME1.NAME2"\n'
             '\n'
             'Note:\n'
             '\n'
             '  If the same value occurs multiple times in the same match '
             'statement,\n'
             '  the interpreter may cache the first value found and reuse it '
             'rather\n'
             '  than repeat the same lookup.  This cache is strictly tied to a '
             'given\n'
             '  execution of a given match statement.\n'
             '\n'
             '\n'
             'Group Patterns\n'
             '~~~~~~~~~~~~~~\n'
             '\n'
             'A group pattern allows users to add parentheses around patterns '
             'to\n'
             'emphasize the intended grouping.  Otherwise, it has no '
             'additional\n'
             'syntax. Syntax:\n'
             '\n'
             '   group_pattern ::= "(" pattern ")"\n'
             '\n'
             'In simple terms "(P)" has the same effect as "P".\n'
             '\n'
             '\n'
             'Sequence Patterns\n'
             '~~~~~~~~~~~~~~~~~\n'
             '\n'
             'A sequence pattern contains several subpatterns to be matched '
             'against\n'
             'sequence elements. The syntax is similar to the unpacking of a '
             'list or\n'
             'tuple.\n'
             '\n'
             '   sequence_pattern       ::= "[" [maybe_sequence_pattern] "]"\n'
             '                        | "(" [open_sequence_pattern] ")"\n'
             '   open_sequence_pattern  ::= maybe_star_pattern "," '
             '[maybe_sequence_pattern]\n'
             '   maybe_sequence_pattern ::= ",".maybe_star_pattern+ ","?\n'
             '   maybe_star_pattern     ::= star_pattern | pattern\n'
             '   star_pattern           ::= "*" (capture_pattern | '
             'wildcard_pattern)\n'
             '\n'
             'There is no difference if parentheses  or square brackets are '
             'used for\n'
             'sequence patterns (i.e. "(...)" vs "[...]" ).\n'
             '\n'
             'Note:\n'
             '\n'
             '  A single pattern enclosed in parentheses without a trailing '
             'comma\n'
             '  (e.g. "(3 | 4)") is a group pattern. While a single pattern '
             'enclosed\n'
             '  in square brackets (e.g. "[3 | 4]") is still a sequence '
             'pattern.\n'
             '\n'
             'At most one star subpattern may be in a sequence pattern.  The '
             'star\n'
             'subpattern may occur in any position. If no star subpattern is\n'
             'present, the sequence pattern is a fixed-length sequence '
             'pattern;\n'
             'otherwise it is a variable-length sequence pattern.\n'
             '\n'
             'The following is the logical flow for matching a sequence '
             'pattern\n'
             'against a subject value:\n'
             '\n'
             '1. If the subject value is not a sequence [2], the sequence '
             'pattern\n'
             '   fails.\n'
             '\n'
             '2. If the subject value is an instance of "str", "bytes" or\n'
             '   "bytearray" the sequence pattern fails.\n'
             '\n'
             '3. The subsequent steps depend on whether the sequence pattern '
             'is\n'
             '   fixed or variable-length.\n'
             '\n'
             '   If the sequence pattern is fixed-length:\n'
             '\n'
             '   1. If the length of the subject sequence is not equal to the '
             'number\n'
             '      of subpatterns, the sequence pattern fails\n'
             '\n'
             '   2. Subpatterns in the sequence pattern are matched to their\n'
             '      corresponding items in the subject sequence from left to '
             'right.\n'
             '      Matching stops as soon as a subpattern fails.  If all\n'
             '      subpatterns succeed in matching their corresponding item, '
             'the\n'
             '      sequence pattern succeeds.\n'
             '\n'
             '   Otherwise, if the sequence pattern is variable-length:\n'
             '\n'
             '   1. If the length of the subject sequence is less than the '
             'number of\n'
             '      non-star subpatterns, the sequence pattern fails.\n'
             '\n'
             '   2. The leading non-star subpatterns are matched to their\n'
             '      corresponding items as for fixed-length sequences.\n'
             '\n'
             '   3. If the previous step succeeds, the star subpattern matches '
             'a\n'
             '      list formed of the remaining subject items, excluding the\n'
             '      remaining items corresponding to non-star subpatterns '
             'following\n'
             '      the star subpattern.\n'
             '\n'
             '   4. Remaining non-star subpatterns are matched to their\n'
             '      corresponding subject items, as for a fixed-length '
             'sequence.\n'
             '\n'
             '   Note:\n'
             '\n'
             '     The length of the subject sequence is obtained via "len()" '
             '(i.e.\n'
             '     via the "__len__()" protocol).  This length may be cached '
             'by the\n'
             '     interpreter in a similar manner as value patterns.\n'
             '\n'
             'In simple terms "[P1, P2, P3," … ", P<N>]" matches only if all '
             'the\n'
             'following happens:\n'
             '\n'
             '* check "<subject>" is a sequence\n'
             '\n'
             '* "len(subject) == <N>"\n'
             '\n'
             '* "P1" matches "<subject>[0]" (note that this match can also '
             'bind\n'
             '  names)\n'
             '\n'
             '* "P2" matches "<subject>[1]" (note that this match can also '
             'bind\n'
             '  names)\n'
             '\n'
             '* … and so on for the corresponding pattern/element.\n'
             '\n'
             '\n'
             'Mapping Patterns\n'
             '~~~~~~~~~~~~~~~~\n'
             '\n'
             'A mapping pattern contains one or more key-value patterns.  The '
             'syntax\n'
             'is similar to the construction of a dictionary. Syntax:\n'
             '\n'
             '   mapping_pattern     ::= "{" [items_pattern] "}"\n'
             '   items_pattern       ::= ",".key_value_pattern+ ","?\n'
             '   key_value_pattern   ::= (literal_pattern | value_pattern) ":" '
             'pattern\n'
             '                         | double_star_pattern\n'
             '   double_star_pattern ::= "**" capture_pattern\n'
             '\n'
             'At most one double star pattern may be in a mapping pattern.  '
             'The\n'
             'double star pattern must be the last subpattern in the mapping\n'
             'pattern.\n'
             '\n'
             'Duplicate keys in mapping patterns are disallowed. Duplicate '
             'literal\n'
             'keys will raise a "SyntaxError". Two keys that otherwise have '
             'the same\n'
             'value will raise a "ValueError" at runtime.\n'
             '\n'
             'The following is the logical flow for matching a mapping '
             'pattern\n'
             'against a subject value:\n'
             '\n'
             '1. If the subject value is not a mapping [3],the mapping '
             'pattern\n'
             '   fails.\n'
             '\n'
             '2. If every key given in the mapping pattern is present in the '
             'subject\n'
             '   mapping, and the pattern for each key matches the '
             'corresponding\n'
             '   item of the subject mapping, the mapping pattern succeeds.\n'
             '\n'
             '3. If duplicate keys are detected in the mapping pattern, the '
             'pattern\n'
             '   is considered invalid. A "SyntaxError" is raised for '
             'duplicate\n'
             '   literal values; or a "ValueError" for named keys of the same '
             'value.\n'
             '\n'
             'Note:\n'
             '\n'
             '  Key-value pairs are matched using the two-argument form of '
             'the\n'
             '  mapping subject’s "get()" method.  Matched key-value pairs '
             'must\n'
             '  already be present in the mapping, and not created on-the-fly '
             'via\n'
             '  "__missing__()" or "__getitem__()".\n'
             '\n'
             'In simple terms "{KEY1: P1, KEY2: P2, ... }" matches only if all '
             'the\n'
             'following happens:\n'
             '\n'
             '* check "<subject>" is a mapping\n'
             '\n'
             '* "KEY1 in <subject>"\n'
             '\n'
             '* "P1" matches "<subject>[KEY1]"\n'
             '\n'
             '* … and so on for the corresponding KEY/pattern pair.\n'
             '\n'
             '\n'
             'Class Patterns\n'
             '~~~~~~~~~~~~~~\n'
             '\n'
             'A class pattern represents a class and its positional and '
             'keyword\n'
             'arguments (if any).  Syntax:\n'
             '\n'
             '   class_pattern       ::= name_or_attr "(" [pattern_arguments '
             '","?] ")"\n'
             '   pattern_arguments   ::= positional_patterns ["," '
             'keyword_patterns]\n'
             '                         | keyword_patterns\n'
             '   positional_patterns ::= ",".pattern+\n'
             '   keyword_patterns    ::= ",".keyword_pattern+\n'
             '   keyword_pattern     ::= NAME "=" pattern\n'
             '\n'
             'The same keyword should not be repeated in class patterns.\n'
             '\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'
             '   "TypeError".\n'
             '\n'
             '2. If the subject value is not an instance of "name_or_attr" '
             '(tested\n'
             '   via "isinstance()"), the class pattern fails.\n'
             '\n'
             '3. If no pattern arguments are present, the pattern succeeds.\n'
             '   Otherwise, the subsequent steps depend on whether keyword or\n'
             '   positional argument patterns are present.\n'
             '\n'
             '   For a number of built-in types (specified below), a single\n'
             '   positional subpattern is accepted which will match the '
             'entire\n'
             '   subject; for these types keyword patterns also work as for '
             'other\n'
             '   types.\n'
             '\n'
             '   If only keyword patterns are present, they are processed as\n'
             '   follows, one by one:\n'
             '\n'
             '   I. The keyword is looked up as an attribute on the subject.\n'
             '\n'
             '      * If this raises an exception other than "AttributeError", '
             'the\n'
             '        exception bubbles up.\n'
             '\n'
             '      * If this raises "AttributeError", the class pattern has '
             'failed.\n'
             '\n'
             '      * Else, the subpattern associated with the keyword pattern '
             'is\n'
             '        matched against the subject’s attribute value.  If this '
             'fails,\n'
             '        the class pattern fails; if this succeeds, the match '
             'proceeds\n'
             '        to the next keyword.\n'
             '\n'
             '   II. If all keyword patterns succeed, the class pattern '
             'succeeds.\n'
             '\n'
             '   If any positional patterns are present, they are converted '
             'to\n'
             '   keyword patterns using the "__match_args__" attribute on the '
             'class\n'
             '   "name_or_attr" before matching:\n'
             '\n'
             '   I. The equivalent of "getattr(cls, "__match_args__", ())" is\n'
             '   called.\n'
             '\n'
             '      * If this raises an exception, the exception bubbles up.\n'
             '\n'
             '      * If the returned value is not a tuple, the conversion '
             'fails and\n'
             '        "TypeError" is raised.\n'
             '\n'
             '      * If there are more positional patterns than\n'
             '        "len(cls.__match_args__)", "TypeError" is raised.\n'
             '\n'
             '      * Otherwise, positional pattern "i" is converted to a '
             'keyword\n'
             '        pattern using "__match_args__[i]" as the keyword.\n'
             '        "__match_args__[i]" must be a string; if not "TypeError" '
             'is\n'
             '        raised.\n'
             '\n'
             '      * If there are duplicate keywords, "TypeError" is raised.\n'
             '\n'
             '      See also:\n'
             '\n'
             '        Customizing positional arguments in class pattern '
             'matching\n'
             '\n'
             '   II. Once all positional patterns have been converted to '
             'keyword\n'
             '   patterns,\n'
             '      the match proceeds as if there were only keyword '
             'patterns.\n'
             '\n'
             '   For the following built-in types the handling of positional\n'
             '   subpatterns is different:\n'
             '\n'
             '   * "bool"\n'
             '\n'
             '   * "bytearray"\n'
             '\n'
             '   * "bytes"\n'
             '\n'
             '   * "dict"\n'
             '\n'
             '   * "float"\n'
             '\n'
             '   * "frozenset"\n'
             '\n'
             '   * "int"\n'
             '\n'
             '   * "list"\n'
             '\n'
             '   * "set"\n'
             '\n'
             '   * "str"\n'
             '\n'
             '   * "tuple"\n'
             '\n'
             '   These classes accept a single positional argument, and the '
             'pattern\n'
             '   there is matched against the whole object rather than an '
             'attribute.\n'
             '   For example "int(0|1)" matches the value "0", but not the '
             'values\n'
             '   "0.0" or "False".\n'
             '\n'
             'In simple terms "CLS(P1, attr=P2)" matches only if the '
             'following\n'
             'happens:\n'
             '\n'
             '* "isinstance(<subject>, CLS)"\n'
             '\n'
             '* convert "P1" to a keyword pattern using "CLS.__match_args__"\n'
             '\n'
             '* For each keyword argument "attr=P2":\n'
             '     * "hasattr(<subject>, "attr")"\n'
             '\n'
             '     * "P2" matches "<subject>.attr"\n'
             '\n'
             '* … and so on for the corresponding keyword argument/pattern '
             'pair.\n'
             '\n'
             'See also:\n'
             '\n'
             '  * **PEP 634** – Structural Pattern Matching: Specification\n'
             '\n'
             '  * **PEP 636** – Structural Pattern Matching: Tutorial\n'
             '\n'
             '\n'
             'Function definitions\n'
             '====================\n'
             '\n'
             'A function definition defines a user-defined function object '
             '(see\n'
             'section The standard type hierarchy):\n'
             '\n'
             '   funcdef                   ::= [decorators] "def" funcname "(" '
             '[parameter_list] ")"\n'
             '               ["->" expression] ":" suite\n'
             '   decorators                ::= decorator+\n'
             '   decorator                 ::= "@" assignment_expression '
             'NEWLINE\n'
             '   parameter_list            ::= defparameter ("," '
             'defparameter)* "," "/" ["," [parameter_list_no_posonly]]\n'
             '                        | parameter_list_no_posonly\n'
             '   parameter_list_no_posonly ::= defparameter ("," '
             'defparameter)* ["," [parameter_list_starargs]]\n'
             '                                 | parameter_list_starargs\n'
             '   parameter_list_starargs   ::= "*" [parameter] ("," '
             'defparameter)* ["," ["**" parameter [","]]]\n'
             '                               | "**" parameter [","]\n'
             '   parameter                 ::= identifier [":" expression]\n'
             '   defparameter              ::= parameter ["=" expression]\n'
             '   funcname                  ::= identifier\n'
             '\n'
             'A function definition is an executable statement.  Its execution '
             'binds\n'
             'the function name in the current local namespace to a function '
             'object\n'
             '(a wrapper around the executable code for the function).  This\n'
             'function object contains a reference to the current global '
             'namespace\n'
             'as the global namespace to be used when the function is called.\n'
             '\n'
             'The function definition does not execute the function body; this '
             'gets\n'
             'executed only when the function is called. [4]\n'
             '\n'
             'A function definition may be wrapped by one or more *decorator*\n'
             'expressions. Decorator expressions are evaluated when the '
             'function is\n'
             'defined, in the scope that contains the function definition.  '
             'The\n'
             'result must be a callable, which is invoked with the function '
             'object\n'
             'as the only argument. The returned value is bound to the '
             'function name\n'
             'instead of the function object.  Multiple decorators are applied '
             'in\n'
             'nested fashion. For example, the following code\n'
             '\n'
             '   @f1(arg)\n'
             '   @f2\n'
             '   def func(): pass\n'
             '\n'
             'is roughly equivalent to\n'
             '\n'
             '   def func(): pass\n'
             '   func = f1(arg)(f2(func))\n'
             '\n'
             'except that the original function is not temporarily bound to '
             'the name\n'
             '"func".\n'
             '\n'
             'Changed in version 3.9: Functions may be decorated with any '
             'valid\n'
             '"assignment_expression". Previously, the grammar was much more\n'
             'restrictive; see **PEP 614** for details.\n'
             '\n'
             'When one or more *parameters* have the form *parameter* "="\n'
             '*expression*, the function is said to have “default parameter '
             'values.”\n'
             'For a parameter with a default value, the corresponding '
             '*argument* may\n'
             'be omitted from a call, in which case the parameter’s default '
             'value is\n'
             'substituted.  If a parameter has a default value, all following\n'
             'parameters up until the “"*"” must also have a default value — '
             'this is\n'
             'a syntactic restriction that is not expressed by the grammar.\n'
             '\n'
             '**Default parameter values are evaluated from left to right when '
             'the\n'
             'function definition is executed.** This means that the '
             'expression is\n'
             'evaluated once, when the function is defined, and that the same '
             '“pre-\n'
             'computed” value is used for each call.  This is especially '
             'important\n'
             'to understand when a default parameter value is a mutable '
             'object, such\n'
             'as a list or a dictionary: if the function modifies the object '
             '(e.g.\n'
             'by appending an item to a list), the default parameter value is '
             'in\n'
             'effect modified.  This is generally not what was intended.  A '
             'way\n'
             'around this is to use "None" as the default, and explicitly test '
             'for\n'
             'it in the body of the function, e.g.:\n'
             '\n'
             '   def whats_on_the_telly(penguin=None):\n'
             '       if penguin is None:\n'
             '           penguin = []\n'
             '       penguin.append("property of the zoo")\n'
             '       return penguin\n'
             '\n'
             'Function call semantics are described in more detail in section '
             'Calls.\n'
             'A function call always assigns values to all parameters '
             'mentioned in\n'
             'the parameter list, either from positional arguments, from '
             'keyword\n'
             'arguments, or from default values.  If the form “"*identifier"” '
             'is\n'
             'present, it is initialized to a tuple receiving any excess '
             'positional\n'
             'parameters, defaulting to the empty tuple. If the form\n'
             '“"**identifier"” is present, it is initialized to a new ordered\n'
             'mapping receiving any excess keyword arguments, defaulting to a '
             'new\n'
             'empty mapping of the same type.  Parameters after “"*"” or\n'
             '“"*identifier"” are keyword-only parameters and may only be '
             'passed by\n'
             'keyword arguments.  Parameters before “"/"” are positional-only\n'
             'parameters and may only be passed by positional arguments.\n'
             '\n'
             'Changed in version 3.8: The "/" function parameter syntax may be '
             'used\n'
             'to indicate positional-only parameters. See **PEP 570** for '
             'details.\n'
             '\n'
             'Parameters may have an *annotation* of the form “": '
             'expression"”\n'
             'following the parameter name.  Any parameter may have an '
             'annotation,\n'
             'even those of the form "*identifier" or "**identifier".  '
             'Functions may\n'
             'have “return” annotation of the form “"-> expression"” after '
             'the\n'
             'parameter list.  These annotations can be any valid Python '
             'expression.\n'
             'The presence of annotations does not change the semantics of a\n'
             'function.  The annotation values are available as values of a\n'
             'dictionary keyed by the parameters’ names in the '
             '"__annotations__"\n'
             'attribute of the function object.  If the "annotations" import '
             'from\n'
             '"__future__" is used, annotations are preserved as strings at '
             'runtime\n'
             'which enables postponed evaluation.  Otherwise, they are '
             'evaluated\n'
             'when the function definition is executed.  In this case '
             'annotations\n'
             'may be evaluated in a different order than they appear in the '
             'source\n'
             'code.\n'
             '\n'
             'It is also possible to create anonymous functions (functions not '
             'bound\n'
             'to a name), for immediate use in expressions.  This uses lambda\n'
             'expressions, described in section Lambdas.  Note that the '
             'lambda\n'
             'expression is merely a shorthand for a simplified function '
             'definition;\n'
             'a function defined in a “"def"” statement can be passed around '
             'or\n'
             'assigned to another name just like a function defined by a '
             'lambda\n'
             'expression.  The “"def"” form is actually more powerful since '
             'it\n'
             'allows the execution of multiple statements and annotations.\n'
             '\n'
             '**Programmer’s note:** Functions are first-class objects.  A '
             '“"def"”\n'
             'statement executed inside a function definition defines a local\n'
             'function that can be returned or passed around.  Free variables '
             'used\n'
             'in the nested function can access the local variables of the '
             'function\n'
             'containing the def.  See section Naming and binding for '
             'details.\n'
             '\n'
             'See also:\n'
             '\n'
             '  **PEP 3107** - Function Annotations\n'
             '     The original specification for function annotations.\n'
             '\n'
             '  **PEP 484** - Type Hints\n'
             '     Definition of a standard meaning for annotations: type '
             'hints.\n'
             '\n'
             '  **PEP 526** - Syntax for Variable Annotations\n'
             '     Ability to type hint variable declarations, including '
             'class\n'
             '     variables and instance variables\n'
             '\n'
             '  **PEP 563** - Postponed Evaluation of Annotations\n'
             '     Support for forward references within annotations by '
             'preserving\n'
             '     annotations in a string form at runtime instead of eager\n'
             '     evaluation.\n'
             '\n'
             '\n'
             'Class definitions\n'
             '=================\n'
             '\n'
             'A class definition defines a class object (see section The '
             'standard\n'
             'type hierarchy):\n'
             '\n'
             '   classdef    ::= [decorators] "class" classname [inheritance] '
             '":" suite\n'
             '   inheritance ::= "(" [argument_list] ")"\n'
             '   classname   ::= identifier\n'
             '\n'
             'A class definition is an executable statement.  The inheritance '
             'list\n'
             'usually gives a list of base classes (see Metaclasses for more\n'
             'advanced uses), so each item in the list should evaluate to a '
             'class\n'
             'object which allows subclassing.  Classes without an inheritance '
             'list\n'
             'inherit, by default, from the base class "object"; hence,\n'
             '\n'
             '   class Foo:\n'
             '       pass\n'
             '\n'
             'is equivalent to\n'
             '\n'
             '   class Foo(object):\n'
             '       pass\n'
             '\n'
             'The class’s suite is then executed in a new execution frame '
             '(see\n'
             'Naming and binding), using a newly created local namespace and '
             'the\n'
             'original global namespace. (Usually, the suite contains mostly\n'
             'function definitions.)  When the class’s suite finishes '
             'execution, its\n'
             'execution frame is discarded but its local namespace is saved. '
             '[5] A\n'
             'class object is then created using the inheritance list for the '
             'base\n'
             'classes and the saved local namespace for the attribute '
             'dictionary.\n'
             'The class name is bound to this class object in the original '
             'local\n'
             'namespace.\n'
             '\n'
             'The order in which attributes are defined in the class body is\n'
             'preserved in the new class’s "__dict__".  Note that this is '
             'reliable\n'
             'only right after the class is created and only for classes that '
             'were\n'
             'defined using the definition syntax.\n'
             '\n'
             'Class creation can be customized heavily using metaclasses.\n'
             '\n'
             'Classes can also be decorated: just like when decorating '
             'functions,\n'
             '\n'
             '   @f1(arg)\n'
             '   @f2\n'
             '   class Foo: pass\n'
             '\n'
             'is roughly equivalent to\n'
             '\n'
             '   class Foo: pass\n'
             '   Foo = f1(arg)(f2(Foo))\n'
             '\n'
             'The evaluation rules for the decorator expressions are the same '
             'as for\n'
             'function decorators.  The result is then bound to the class '
             'name.\n'
             '\n'
             'Changed in version 3.9: Classes may be decorated with any valid\n'
             '"assignment_expression". Previously, the grammar was much more\n'
             'restrictive; see **PEP 614** for details.\n'
             '\n'
             '**Programmer’s note:** Variables defined in the class definition '
             'are\n'
             'class attributes; they are shared by instances.  Instance '
             'attributes\n'
             'can be set in a method with "self.name = value".  Both class '
             'and\n'
             'instance attributes are accessible through the notation '
             '“"self.name"”,\n'
             'and an instance attribute hides a class attribute with the same '
             'name\n'
             'when accessed in this way.  Class attributes can be used as '
             'defaults\n'
             'for instance attributes, but using mutable values there can lead '
             'to\n'
             'unexpected results.  Descriptors can be used to create instance\n'
             'variables with different implementation details.\n'
             '\n'
             'See also:\n'
             '\n'
             '  **PEP 3115** - Metaclasses in Python 3000\n'
             '     The proposal that changed the declaration of metaclasses to '
             'the\n'
             '     current syntax, and the semantics for how classes with\n'
             '     metaclasses are constructed.\n'
             '\n'
             '  **PEP 3129** - Class Decorators\n'
             '     The proposal that added class decorators.  Function and '
             'method\n'
             '     decorators were introduced in **PEP 318**.\n'
             '\n'
             '\n'
             'Coroutines\n'
             '==========\n'
             '\n'
             'New in version 3.5.\n'
             '\n'
             '\n'
             'Coroutine function definition\n'
             '-----------------------------\n'
             '\n'
             '   async_funcdef ::= [decorators] "async" "def" funcname "(" '
             '[parameter_list] ")"\n'
             '                     ["->" expression] ":" suite\n'
             '\n'
             'Execution of Python coroutines can be suspended and resumed at '
             'many\n'
             'points (see *coroutine*). "await" expressions, "async for" and '
             '"async\n'
             'with" can only be used in the body of a coroutine function.\n'
             '\n'
             'Functions defined with "async def" syntax are always coroutine\n'
             'functions, even if they do not contain "await" or "async" '
             'keywords.\n'
             '\n'
             'It is a "SyntaxError" to use a "yield from" expression inside '
             'the body\n'
             'of a coroutine function.\n'
             '\n'
             'An example of a coroutine function:\n'
             '\n'
             '   async def func(param1, param2):\n'
             '       do_stuff()\n'
             '       await some_coroutine()\n'
             '\n'
             'Changed in version 3.7: "await" and "async" are now keywords;\n'
             'previously they were only treated as such inside the body of a\n'
             'coroutine function.\n'
             '\n'
             '\n'
             'The "async for" statement\n'
             '-------------------------\n'
             '\n'
             '   async_for_stmt ::= "async" for_stmt\n'
             '\n'
             'An *asynchronous iterable* provides an "__aiter__" method that\n'
             'directly returns an *asynchronous iterator*, which can call\n'
             'asynchronous code in its "__anext__" method.\n'
             '\n'
             'The "async for" statement allows convenient iteration over\n'
             'asynchronous iterables.\n'
             '\n'
             'The following code:\n'
             '\n'
             '   async for TARGET in ITER:\n'
             '       SUITE\n'
             '   else:\n'
             '       SUITE2\n'
             '\n'
             'Is semantically equivalent to:\n'
             '\n'
             '   iter = (ITER)\n'
             '   iter = type(iter).__aiter__(iter)\n'
             '   running = True\n'
             '\n'
             '   while running:\n'
             '       try:\n'
             '           TARGET = await type(iter).__anext__(iter)\n'
             '       except StopAsyncIteration:\n'
             '           running = False\n'
             '       else:\n'
             '           SUITE\n'
             '   else:\n'
             '       SUITE2\n'
             '\n'
             'See also "__aiter__()" and "__anext__()" for details.\n'
             '\n'
             'It is a "SyntaxError" to use an "async for" statement outside '
             'the body\n'
             'of a coroutine function.\n'
             '\n'
             '\n'
             'The "async with" statement\n'
             '--------------------------\n'
             '\n'
             '   async_with_stmt ::= "async" with_stmt\n'
             '\n'
             'An *asynchronous context manager* is a *context manager* that is '
             'able\n'
             'to suspend execution in its *enter* and *exit* methods.\n'
             '\n'
             'The following code:\n'
             '\n'
             '   async with EXPRESSION as TARGET:\n'
             '       SUITE\n'
             '\n'
             'is semantically equivalent to:\n'
             '\n'
             '   manager = (EXPRESSION)\n'
             '   aenter = type(manager).__aenter__\n'
             '   aexit = type(manager).__aexit__\n'
             '   value = await aenter(manager)\n'
             '   hit_except = False\n'
             '\n'
             '   try:\n'
             '       TARGET = value\n'
             '       SUITE\n'
             '   except:\n'
             '       hit_except = True\n'
             '       if not await aexit(manager, *sys.exc_info()):\n'
             '           raise\n'
             '   finally:\n'
             '       if not hit_except:\n'
             '           await aexit(manager, None, None, None)\n'
             '\n'
             'See also "__aenter__()" and "__aexit__()" for details.\n'
             '\n'
             'It is a "SyntaxError" to use an "async with" statement outside '
             'the\n'
             'body of a coroutine function.\n'
             '\n'
             'See also:\n'
             '\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'