Text of peps.python.org › pep-0634 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 634 – Structural Pattern Matching: Specification | peps.python.org

PEP 634 – Structural Pattern Matching: Specification PEP 634 – Structural Pattern Matching: Specification Author : Brandt Bucher <brandt at python.org>, Guido van Rossum <guido at python.org> BDFL-Delegate : Discussions-To : Python-Dev list Status : Final Type : Standards Track Created : 12-Sep-2020 Python-Version : 3.10 Post-History : 22-Oct-2020, 08-Feb-2021 Replaces : 622 Resolution : Python-Committers message Table of Contents Abstract Syntax and Semantics Overview and Terminology The Match Statement Match Semantics Guards Irrefutable case blocks Patterns AS Patterns OR Patterns Literal Patterns Capture Patterns Wildcard Pattern Value Patterns Group Patterns Sequence Patterns Mapping Patterns Class Patterns Side Effects and Undefined Behavior The Standard Library Appendix A – Full Grammar Copyright Important This PEP is a historical document.

The up-to-date, canonical documentation can now be found at The match statement . × See PEP 1 for how to propose changes. Abstract This PEP provides the technical specification for the match statement. It replaces PEP 622 , which is hereby split in three parts: PEP 634 : Specification PEP 635 : Motivation and Rationale PEP 636 : Tutorial This PEP is intentionally devoid of commentary; the motivation and all explanations of our design choices are in PEP 635 .

First-time readers are encouraged to start with PEP 636 , which provides a gentler introduction to the concepts, syntax and semantics of patterns. Syntax and Semantics See Appendix A for the complete grammar. Overview and Terminology The pattern matching process takes as input a pattern (following case ) and a subject value (following match ). Phrases to describe the process include “the pattern is matched with (or against) the subject value” and “we match the pattern against (or with) the subject value”.

The primary outcome of pattern matching is success or failure. In case of success we may say “the pattern succeeds”, “the match succeeds”, or “the pattern matches the subject value”. In many cases a pattern contains subpatterns, and success or failure is determined by the success or failure of matching those subpatterns against the value (e.g., for OR patterns) or against parts of the value (e.g., for sequence patterns).

This process typically processes the subpatterns from left to right until the overall outcome is determined. E.g., an OR pattern succeeds at the first succeeding subpattern, while a sequence patterns fails at the first failing subpattern. A secondary outcome of pattern matching may be one or more name bindings. We may say “the pattern binds a value to a name”. When subpatterns tried until the first success, only the bindings due to the successful subpattern are valid; when trying until the first failure, the bindings are merged.

Several more rules, explained below, apply to these cases. The Match Statement Syntax: match_stmt: "match" subject_expr ':' NEWLINE INDENT case_block+ DEDENT subject_expr: | star_named_expression ',' star_named_expressions? | named_expression case_block: "case" patterns [guard] ':' block guard: 'if' named_expression The rules star_named_expression , star_named_expressions , named_expression and block are part of the standard Python grammar .

The rule patterns is specified below. For context, match_stmt is a new alternative for compound_statement : compound_statement : | if_stmt ... | match_stmt The match and case keywords are soft keywords, i.e. they are not reserved words in other grammatical contexts (including at the start of a line if there is no colon where expected). This implies that they are recognized as keywords when part of a match statement or case block only, and are allowed to be used in all other contexts as variable or argument names.

Match Semantics The match statement first evaluates the subject expression. If a comma is present a tuple is constructed using the standard rules. The resulting subject value is then used to select the first case block whose patterns succeeds matching it and whose guard condition (if present) is “truthy”. If no case blocks qualify the match statement is complete; otherwise, the block of the selected case block is executed.

The usual rules for executing a block nested inside a compound statement apply (e.g. an if statement). Name bindings made during a successful pattern match outlive the executed block and can be used after the match statement. During failed pattern matches, some subpatterns may succeed. For example, while matching the pattern (0, x, 1) with the value [0, 1, 2] , the subpattern x may succeed if the list elements are matched from left to right.

The implementation may choose to either make persistent bindings for those partial matches or not. User code including a match statement should not rely on the bindings being made for a failed match, but also shouldn’t assume that variables are unchanged by a failed match. This part of the behavior is left intentionally unspecified so different implementations can add optimizations, and to prevent introducing semantic restrictions that could limit the extensibility of this feature.

The precise pattern binding rules vary per pattern type and are specified below. Guards If a guard is present on a case block, once the pattern or patterns in the case block succeed, the expression in the guard is evaluated. If this raises an exception, the exception bubbles up. Otherwise, if the condition is “truthy” the case block is selected; if it is “falsy” the case block is not selected. Since guards are expressions they are allowed to have side effects.

Guard evaluation must proceed from the first to the last case block, one at a time, skipping case blocks whose pattern(s) don’t all succeed. (I.e., even if determining whether those patterns succeed may happen out of order, guard evaluation must happen in order.) Guard evaluation must stop once a case block is selected. Irrefutable case blocks A pattern is considered irrefutable if we can prove from its syntax alone that it will always succeed.

In particular, capture patterns and wildcard patterns are irrefutable, and so are AS patterns whose left-hand side is irrefutable, OR patterns containing at least one irrefutable pattern, and parenthesized irrefutable patterns. A case block is considered irrefutable if it has no guard and its pattern is irrefutable. A match statement may have at most one irrefutable case block, and it must be last. Patterns The top-level syntax for patterns is as follows: patterns : open_sequence_pattern | pattern pattern : as_pattern | or_pattern as_pattern : or_pattern 'as' capture_pattern or_pattern : '|' . closed_pattern + closed_pattern : | literal_pattern | capture_pattern | wildcard_pattern | value_pattern | group_pattern | sequence_pattern | mapping_pattern | class_pattern AS Patterns Syntax: as_pattern : or_pattern 'as' capture_pattern (Note: the name on the right may not be _ .) An AS pattern matches the OR pattern on the left of the as keyword against the subject.

If this fails, the AS pattern fails. Otherwise, the AS pattern binds the subject to the name on the right of the as keyword and succeeds. OR Patterns Syntax: or_pattern : '|' . closed_pattern + When two or more patterns are separated by vertical bars ( | ), this is called an OR pattern. (A single closed pattern is just that.) Only the final subpattern may be irrefutable. Each subpattern must bind the same set of names.

An OR pattern matches each of its subpatterns in turn to the subject, until one succeeds. The OR pattern is then deemed to succeed. If none of the subpatterns succeed the OR pattern fails. Literal Patterns Syntax: literal_pattern : | signed_number | signed_number '+' NUMBER | signed_number '-' NUMBER | strings | 'None' | 'True' | 'False' signed_number : NUMBER | '-' NUMBER The rule strings and the token NUMBER are defined in the standard Python grammar.

Triple-quoted strings are supported. Raw strings and byte strings a

The rest of this page is on the live site.