Remove unused suspicious rule in the docs
diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py
index ba4e290..0048f79 100644
--- a/Lib/pydoc_data/topics.py
+++ b/Lib/pydoc_data/topics.py
@@ -1,5 +1,5 @@
# -*- coding: utf-8 -*-
-# Autogenerated by Sphinx on Tue Feb 2 20:44:10 2021
+# Autogenerated by Sphinx on Mon Mar 1 16:48:51 2021
topics = {'assert': 'The "assert" statement\n'
'**********************\n'
'\n'
@@ -2183,6 +2183,7 @@
' | for_stmt\n'
' | try_stmt\n'
' | with_stmt\n'
+ ' | match_stmt\n'
' | funcdef\n'
' | classdef\n'
' | async_with_stmt\n'
@@ -2681,6 +2682,737 @@
' statement.\n'
'\n'
'\n'
+ 'The "match" statement\n'
+ '=====================\n'
+ '\n'
+ 'New in version 3.10.\n'
+ '\n'
+ 'The match statement is used for pattern matching. Syntax:\n'
+ '\n'
+ ' match_stmt ::= \'match\' subject_expr ":" NEWLINE INDENT '
+ 'case_block+ DEDENT\n'
+ ' subject_expr ::= star_named_expression "," '
+ 'star_named_expressions?\n'
+ ' | named_expression\n'
+ " case_block ::= 'case' patterns [guard] ':' block\n"
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' This section uses single quotes to denote soft keywords.\n'
+ '\n'
+ 'Pattern matching takes a pattern as input (following "case") and '
+ 'a\n'
+ 'subject value (following "match"). The pattern (which may '
+ 'contain\n'
+ 'subpatterns) is matched against the subject value. The outcomes '
+ 'are:\n'
+ '\n'
+ '* A match success or failure (also termed a pattern success or\n'
+ ' failure).\n'
+ '\n'
+ '* Possible binding of matched values to a name. The '
+ 'prerequisites for\n'
+ ' this are further discussed below.\n'
+ '\n'
+ 'The "match" and "case" keywords are soft keywords.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' * **PEP 634** – Structural Pattern Matching: Specification\n'
+ '\n'
+ ' * **PEP 636** – Structural Pattern Matching: Tutorial\n'
+ '\n'
+ '\n'
+ 'Overview\n'
+ '--------\n'
+ '\n'
+ 'Here’s an overview of the logical flow of a match statement:\n'
+ '\n'
+ '1. The subject expression "subject_expr" is evaluated and a '
+ 'resulting\n'
+ ' subject value obtained. If the subject expression contains a '
+ 'comma,\n'
+ ' a tuple is constructed using the standard rules.\n'
+ '\n'
+ '2. Each pattern in a "case_block" is attempted to match with '
+ 'the\n'
+ ' subject value. The specific rules for success or failure are\n'
+ ' described below. The match attempt can also bind some or all '
+ 'of the\n'
+ ' standalone names within the pattern. The precise pattern '
+ 'binding\n'
+ ' rules vary per pattern type and are specified below. **Name\n'
+ ' bindings made during a successful pattern match outlive the\n'
+ ' executed block and can be used after the match statement**.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' During failed pattern matches, some subpatterns may '
+ 'succeed.\n'
+ ' Do not rely on bindings being made for a failed match.\n'
+ ' Conversely, do not rely on variables remaining unchanged '
+ 'after\n'
+ ' a failed match. The exact behavior is dependent on\n'
+ ' implementation and may vary. This is an intentional '
+ 'decision\n'
+ ' made to allow different implementations to add '
+ 'optimizations.\n'
+ '\n'
+ '3. If the pattern succeeds, the corresponding guard (if present) '
+ 'is\n'
+ ' evaluated. In this case all name bindings are guaranteed to '
+ 'have\n'
+ ' happened.\n'
+ '\n'
+ ' * If the guard evaluates as truthy or missing, the "block" '
+ 'inside\n'
+ ' "case_block" is executed.\n'
+ '\n'
+ ' * Otherwise, the next "case_block" is attempted as described '
+ 'above.\n'
+ '\n'
+ ' * If there are no further case blocks, the match statement '
+ 'is\n'
+ ' completed.\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' Users should generally never rely on a pattern being '
+ 'evaluated.\n'
+ ' Depending on implementation, the interpreter may cache values '
+ 'or use\n'
+ ' other optimizations which skip repeated evaluations.\n'
+ '\n'
+ 'A sample match statement:\n'
+ '\n'
+ ' >>> flag = False\n'
+ ' >>> match (100, 200):\n'
+ ' ... case (100, 300): # Mismatch: 200 != 300\n'
+ " ... print('Case 1')\n"
+ ' ... case (100, 200) if flag: # Successful match, but '
+ 'guard fails\n'
+ " ... print('Case 2')\n"
+ ' ... case (100, y): # Matches and binds y to 200\n'
+ " ... print(f'Case 3, y: {y}')\n"
+ ' ... case _: # Pattern not attempted\n'
+ " ... print('Case 4, I match anything!')\n"
+ ' ...\n'
+ ' Case 3, y: 200\n'
+ '\n'
+ 'In this case, "if flag" is a guard. Read more about that in the '
+ 'next\n'
+ 'section.\n'
+ '\n'
+ '\n'
+ 'Guards\n'
+ '------\n'
+ '\n'
+ ' guard ::= "if" named_expression\n'
+ '\n'
+ 'A "guard" (which is part of the "case") must succeed for code '
+ 'inside\n'
+ 'the "case" block to execute. It takes the form: "if" followed '
+ 'by an\n'
+ 'expression.\n'
+ '\n'
+ 'The logical flow of a "case" block with a "guard" follows:\n'
+ '\n'
+ '1. Check that the pattern in the "case" block succeeded. If '
+ 'the\n'
+ ' pattern failed, the "guard" is not evaluated and the next '
+ '"case"\n'
+ ' block is checked.\n'
+ '\n'
+ '2. If the pattern succeeded, evaluate the "guard".\n'
+ '\n'
+ ' * If the "guard" condition evaluates to “truthy”, the case '
+ 'block is\n'
+ ' selected.\n'
+ '\n'
+ ' * If the "guard" condition evaluates to “falsy”, the case '
+ 'block is\n'
+ ' not selected.\n'
+ '\n'
+ ' * If the "guard" raises an exception during evaluation, the\n'
+ ' exception bubbles up.\n'
+ '\n'
+ 'Guards are allowed to have side effects as they are '
+ 'expressions.\n'
+ 'Guard evaluation must proceed from the first to the last case '
+ 'block,\n'
+ 'one at a time, skipping case blocks whose pattern(s) don’t all\n'
+ 'succeed. (I.e., guard evaluation must happen in order.) Guard\n'
+ 'evaluation must stop once a case block is selected.\n'
+ '\n'
+ '\n'
+ 'Irrefutable Case Blocks\n'
+ '-----------------------\n'
+ '\n'
+ 'An irrefutable case block is a match-all case block. A match\n'
+ 'statement may have at most one irrefutable case block, and it '
+ 'must be\n'
+ 'last.\n'
+ '\n'
+ 'A case block is considered irrefutable if it has no guard and '
+ 'its\n'
+ 'pattern is irrefutable. A pattern is considered irrefutable if '
+ 'we can\n'
+ 'prove from its syntax alone that it will always succeed. Only '
+ 'the\n'
+ 'following patterns are irrefutable:\n'
+ '\n'
+ '* AS Patterns whose left-hand side is irrefutable\n'
+ '\n'
+ '* OR Patterns containing at least one irrefutable pattern\n'
+ '\n'
+ '* Capture Patterns\n'
+ '\n'
+ '* Wildcard Patterns\n'
+ '\n'
+ '* parenthesized irrefutable patterns\n'
+ '\n'
+ '\n'
+ 'Patterns\n'
+ '--------\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' This section uses grammar notations beyond standard EBNF:\n'
+ '\n'
+ ' * the notation "SEP.RULE+" is shorthand for "RULE (SEP '
+ 'RULE)*"\n'
+ '\n'
+ ' * the notation "!RULE" is shorthand for a negative lookahead\n'
+ ' assertion\n'
+ '\n'
+ 'The top-level syntax for "patterns" is:\n'
+ '\n'
+ ' patterns ::= open_sequence_pattern | pattern\n'
+ ' pattern ::= as_pattern | or_pattern\n'
+ ' closed_pattern ::= | literal_pattern\n'
+ ' | capture_pattern\n'
+ ' | wildcard_pattern\n'
+ ' | value_pattern\n'
+ ' | group_pattern\n'
+ ' | sequence_pattern\n'
+ ' | mapping_pattern\n'
+ ' | class_pattern\n'
+ '\n'
+ 'The descriptions below will include a description “in simple '
+ 'terms” of\n'
+ 'what a pattern does for illustration purposes (credits to '
+ 'Raymond\n'
+ 'Hettinger for a document that inspired most of the '
+ 'descriptions). Note\n'
+ 'that these descriptions are purely for illustration purposes and '
+ '**may\n'
+ 'not** reflect the underlying implementation. Furthermore, they '
+ 'do not\n'
+ 'cover all valid forms.\n'
+ '\n'
+ '\n'
+ 'OR Patterns\n'
+ '~~~~~~~~~~~\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). And 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.\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 an instance of a\n'
+ ' "collections.abc.Sequence" the sequence pattern 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'
+ '* "isinstance(<subject>, collections.abc.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 key values in mapping patterns are disallowed. (If all '
+ 'key\n'
+ 'patterns are literal patterns this is considered a syntax '
+ 'error;\n'
+ 'otherwise this is a runtime error and will raise "ValueError".)\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 an instance of\n'
+ ' "collections.abc.Mapping", the mapping pattern 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 and "ValueError" is raised.\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'
+ '* "isinstance(<subject>, collections.abc.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 mapping '
+ 'pattern\n'
+ 'against 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 no keyword patterns are accepted.\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 list or tuple, the '
+ 'conversion\n'
+ ' fails and "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'
@@ -6197,6 +6929,28 @@
' async elif if or yield\n'
'\n'
'\n'
+ 'Soft Keywords\n'
+ '=============\n'
+ '\n'
+ 'New in version 3.10.\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'
+ '\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'
+ '\n'
+ '\n'
'Reserved classes of identifiers\n'
'===============================\n'
'\n'
@@ -9907,6 +10661,52 @@
' statement.\n'
'\n'
'\n'
+ 'Customizing positional arguments in class pattern matching\n'
+ '==========================================================\n'
+ '\n'
+ 'When using a class name in a pattern, positional arguments '
+ 'in the\n'
+ 'pattern are not allowed by default, i.e. "case MyClass(x, '
+ 'y)" is\n'
+ 'typically invalid without special support in "MyClass". To '
+ 'be able to\n'
+ 'use that kind of patterns, the class needs to define a\n'
+ '*__match_args__* attribute.\n'
+ '\n'
+ 'object.__match_args__\n'
+ '\n'
+ ' This class variable can be assigned a tuple or list of '
+ 'strings.\n'
+ ' When this class is used in a class pattern with '
+ 'positional\n'
+ ' arguments, each positional argument will be converted '
+ 'into a\n'
+ ' keyword argument, using the corresponding value in '
+ '*__match_args__*\n'
+ ' as the keyword. The absence of this attribute is '
+ 'equivalent to\n'
+ ' setting it to "()".\n'
+ '\n'
+ 'For example, if "MyClass.__match_args__" is "("left", '
+ '"center",\n'
+ '"right")" that means that "case MyClass(x, y)" is equivalent '
+ 'to "case\n'
+ 'MyClass(left=x, center=y)". Note that the number of '
+ 'arguments in the\n'
+ 'pattern must be smaller than or equal to the number of '
+ 'elements in\n'
+ '*__match_args__*; if it is larger, the pattern match attempt '
+ 'will\n'
+ 'raise a "TypeError".\n'
+ '\n'
+ 'New in version 3.10.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 634** - Structural Pattern Matching\n'
+ ' The specification for the Python "match" statement.\n'
+ '\n'
+ '\n'
'Special method lookup\n'
'=====================\n'
'\n'