匹配语义

匹配语句首先计算主题表达式。如果存在逗号，则使用标准规则构造元组。

然后使用生成的主题值选择其模式成功匹配它并且其守卫条件（如果存在）为“真值”的第一个case块。如果没有case块符合条件，则匹配语句完成；否则，将执行所选case块的块。嵌套在复合语句内的块的执行通常规则适用（例如if语句）。

在成功模式匹配期间进行的名称绑定将超出执行的块，并且可以在匹配语句之后使用。

在模式匹配失败期间，一些子模式可能会成功。例如，当使用值[0, 1, 2]匹配模式(0, x, 1)时，如果列表元素从左到右匹配，则子模式x可能会成功。实现可以选择是否为这些部分匹配创建持久绑定。包含匹配语句的用户代码不应依赖于为失败的匹配创建的绑定，但也不应假设变量在失败的匹配后保持不变。此行为的一部分有意未指定，以便不同的实现可以添加优化，并防止引入可能限制此功能可扩展性的语义限制。

精确的模式绑定规则因模式类型而异，并在下面指定。

守卫

如果case块上存在守卫，则一旦case块中的模式或模式成功，则计算守卫中的表达式。如果这引发异常，则异常冒泡。否则，如果条件为“真值”，则选择case块；如果条件为“假值”，则不选择case块。

由于守卫是表达式，因此允许它们具有副作用。守卫评估必须从第一个到最后一个case块依次进行，一次一个，跳过其模式不都成功的case块。（即，即使确定这些模式是否成功可能发生在无序的情况下，守卫评估也必须按顺序发生。）一旦选择了一个case块，守卫评估必须停止。

不可反驳的case块

如果我们可以仅从其语法证明模式将始终成功，则该模式被认为是不可反驳的。特别是，捕获模式和通配符模式是不可反驳的，AS模式的左侧也是不可反驳的，包含至少一个不可反驳模式的OR模式以及带括号的不可反驳模式也是如此。

如果case块没有守卫并且其模式是不可反驳的，则该case块被认为是不可反驳的。

匹配语句最多可以有一个不可反驳的case块，并且它必须是最后一个。

AS模式

语法

as_pattern: or_pattern 'as' capture_pattern

（注意：右侧的名称不能为_。）

AS模式将as关键字左侧的OR模式与主题匹配。如果失败，则AS模式失败。否则，AS模式将主题绑定到as关键字右侧的名称并成功。

OR模式

语法

or_pattern: '|'.closed_pattern+

当两个或多个模式用竖线 (|) 分隔时，这称为OR模式。（单个闭合模式就是这样。）

只有最后一个子模式可以是不可反驳的。

每个子模式必须绑定相同的名称集。

OR模式依次将每个子模式与主题匹配，直到一个成功。然后认为OR模式成功。如果所有子模式都失败，则OR模式失败。

字面量模式

语法

literal_pattern:
    | signed_number
    | signed_number '+' NUMBER
    | signed_number '-' NUMBER
    | strings
    | 'None'
    | 'True'
    | 'False'
signed_number: NUMBER | '-' NUMBER

规则strings和标记NUMBER在标准Python语法中定义。

支持三引号字符串。支持原始字符串和字节字符串。不支持F字符串。

表单signed_number '+' NUMBER和signed_number '-' NUMBER仅允许表达复数；它们需要左侧为实数，右侧为虚数。

如果主题值使用以下比较规则与字面量表达的值相等，则字面量模式成功

• 使用==运算符比较数字和字符串。
• 使用is运算符比较单例字面量None、True和False。

捕获模式

语法

capture_pattern: !"_" NAME

单个下划线 (_) 不是捕获模式（这就是!"_"表达的）。它被视为通配符模式。

捕获模式总是成功。它使用PEP 572中为海豹运算符建立的名称绑定作用域规则将主题值绑定到名称。（摘要：除非存在适用的nonlocal或global语句，否则该名称将成为最接近的包含函数作用域中的局部变量。）

在给定的模式中，给定的名称只能绑定一次。例如，这禁止case x, x: ...，但允许case [x] | x: ...。

通配符模式

语法

wildcard_pattern: "_"

通配符模式总是成功。它不绑定任何名称。

值模式

语法

value_pattern: attr
attr: name_or_attr '.' NAME
name_or_attr: attr | NAME

模式中的点分名称使用标准Python名称解析规则查找。但是，当相同的价值模式在同一匹配语句中出现多次时，解释器可能会缓存找到的第一个值并重用它，而不是重复相同的查找。（澄清一下，此缓存严格绑定到给定匹配语句的给定执行。）

如果找到的值与目标值相等（使用==运算符），则模式匹配成功。

组模式

语法

group_pattern: '(' pattern ')'

（有关pattern的语法，请参见上文的模式。请注意，它不包含逗号——包含至少一个逗号的括号内项目序列是序列模式，()也是。）

括号模式没有额外的语法。它允许用户在模式周围添加括号以强调预期的分组。

序列模式

语法

sequence_pattern:
  | '[' [maybe_sequence_pattern] ']'
  | '(' [open_sequence_pattern] ')'
open_sequence_pattern: maybe_star_pattern ',' [maybe_sequence_pattern]
maybe_sequence_pattern: ','.maybe_star_pattern+ ','?
maybe_star_pattern: star_pattern | pattern
star_pattern: '*' (capture_pattern | wildcard_pattern)

（请注意，没有尾随逗号的单个括号模式是组模式，而不是序列模式。但是，用[...]括起来的单个模式仍然是序列模式。）

使用[...]的序列模式、使用(...)的序列模式和开放序列模式之间没有语义差异。

序列模式最多可以包含一个星号子模式。星号子模式可以出现在任何位置。如果没有星号子模式，则序列模式是固定长度序列模式；否则，它是可变长度序列模式。

为了使序列模式匹配成功，目标必须是序列，其中序列的定义是其类属于以下之一

• 继承自collections.abc.Sequence的类
• 已注册为collections.abc.Sequence的Python类
• 其Py_TPFLAGS_SEQUENCE位已设置的内置类
• 继承自上述任何类的类（包括在父类的Sequence注册之前定义的类）

以下标准库类将设置其Py_TPFLAGS_SEQUENCE位

• array.array
• collections.deque
• list
• memoryview
• range
• tuple

如果目标序列的长度不等于子模式的数量，则固定长度序列模式匹配失败。

如果目标序列的长度小于非星号子模式的数量，则可变长度序列模式匹配失败。

目标序列的长度是使用内置的len()函数（即，通过__len__协议）获得的。但是，解释器可能会以类似于值模式中描述的方式缓存此值。

固定长度序列模式将子模式与目标序列的对应项匹配，从左到右。一旦子模式匹配失败，匹配就会停止（并失败）。如果所有子模式都成功匹配其对应的项，则序列模式匹配成功。

可变长度序列模式首先将前导非星号子模式与目标序列的对应项匹配，就像固定长度序列一样。如果成功，则星号子模式匹配由剩余的目标项组成的列表，其中删除了对应于星号子模式之后非星号子模式末尾的项。然后，将剩余的非星号子模式与对应的目标项匹配，就像固定长度序列一样。

映射模式

语法

mapping_pattern: '{' [items_pattern] '}'
items_pattern: ','.key_value_pattern+ ','?
key_value_pattern:
    | (literal_pattern | value_pattern) ':' pattern
    | double_star_pattern
double_star_pattern: '**' capture_pattern

（请注意，此语法不允许使用**_。）

映射模式最多可以包含一个双星号模式，并且它必须位于最后。

映射模式不能包含重复的键值。（如果所有键模式都是文字模式，则这被视为语法错误；否则，这将是运行时错误，并引发ValueError。）

为了使映射模式匹配成功，目标必须是映射，其中映射的定义是其类属于以下之一

• 继承自collections.abc.Mapping的类
• 已注册为collections.abc.Mapping的Python类
• 其Py_TPFLAGS_MAPPING位已设置的内置类
• 继承自上述任何类的类（包括在父类的Mapping注册之前定义的类）

标准库类dict和mappingproxy将设置其Py_TPFLAGS_MAPPING位。

如果映射模式中给出的每个键都存在于目标映射中，并且每个键的模式都匹配目标映射的对应项，则映射模式匹配成功。键始终使用==运算符进行比较。如果存在'**' NAME形式，则该名称将绑定到一个dict，其中包含来自目标映射的其余键值对。

如果在映射模式中检测到重复键，则该模式被认为无效，并引发ValueError。

键值对使用目标的get()方法的双参数形式进行匹配。因此，匹配的键值对必须已存在于映射中，并且不能由__missing__或__getitem__动态创建。例如，collections.defaultdict实例仅与在匹配语句进入时已存在的键的模式匹配。

类模式

语法

class_pattern:
    | name_or_attr '(' [pattern_arguments ','?] ')'
pattern_arguments:
    | positional_patterns [',' keyword_patterns]
    | keyword_patterns
positional_patterns: ','.pattern+
keyword_patterns: ','.keyword_pattern+
keyword_pattern: NAME '=' pattern

类模式不能多次重复相同的关键字。

如果name_or_attr不是内置type的实例，则会引发TypeError。

如果目标不是name_or_attr的实例，则类模式匹配失败。这是使用isinstance()进行测试的。

如果没有参数，则如果isinstance()检查成功，则模式匹配成功。否则

• 如果仅存在关键字模式，则按以下方式逐一处理它们
  • 在目标上将关键字查找为属性。
    • 如果这引发了AttributeError以外的异常，则异常会冒泡。
    • 如果这引发了AttributeError，则类模式匹配失败。
    • 否则，与关键字关联的子模式将与属性值匹配。如果失败，则类模式匹配失败。如果成功，则匹配继续到下一个关键字。
  • 如果所有关键字模式都成功，则整个类模式匹配成功。
• 如果存在任何位置模式，则将其转换为关键字模式（见下文），并将其视为额外的关键字模式，位于语法关键字模式（如果有）之前。

位置模式使用name_or_attr指定的类的__match_args__属性转换为关键字模式，如下所示

• 对于许多内置类型（如下所示），接受单个位置子模式，它将匹配整个目标。（关键字模式在此处的行为与其他类型相同。）
• 调用等效于getattr(cls, "__match_args__", ()))。
• 如果这引发了异常，则异常会冒泡。
• 如果返回值不是元组，则转换失败并引发TypeError。
• 如果位置模式的数量大于__match_args__的长度（使用len()获得），则引发TypeError。
• 否则，位置模式i使用__match_args__[i]作为关键字转换为关键字模式，前提是后者是字符串；如果不是，则引发TypeError。
• 对于重复的关键字，会引发TypeError。

一旦位置模式转换为关键字模式，匹配将继续进行，就像只有关键字模式一样。

如上所述，对于以下内置类型，位置子模式的处理方式有所不同：bool、bytearray、bytes、dict、float、frozenset、int、list、set、str和tuple。

此行为大致等效于以下内容

class C:
    __match_args__ = ("__match_self_prop__",)
    @property
    def __match_self_prop__(self):
        return self