The Match Statement

Surface syntax:

match_stmt: "match" subject_expr ':' NEWLINE INDENT case_block+ DEDENT
subject_expr:
    | star_named_expression ',' star_named_expressions?
    | named_expression
case_block: "case" (guarded_pattern | open_pattern) ':' block

guarded_pattern: closed_pattern 'if' named_expression

open_pattern:
    | as_pattern
    | or_pattern

closed_pattern:
    | wildcard_pattern
    | group_pattern
    | structural_constraint

Abstract syntax:

Match(expr subject, match_case* cases)
match_case = (pattern pattern, expr? guard, stmt* body)

The rules star_named_expression, star_named_expressions, named_expression and block are part of the standard Python grammar.

Open patterns are patterns which consist of multiple tokens, and aren’t necessarily terminated by a closing delimiter (for example, __ as x, int() | bool()). To avoid ambiguity for human readers, their usage is restricted to top level patterns and to group patterns (which are patterns surrounded by parentheses).

Closed patterns are patterns which either consist of a single token (i.e. __), or else have a closing delimiter as a required part of their syntax (e.g. [as x, as y], object{.x as x, .y as y}).

As in PEP 634, 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 means 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.

Unlike PEP 634, patterns are explicitly defined as a new kind of node in the abstract syntax tree - even when surface syntax is shared with existing expression nodes, a distinct abstract node is emitted by the parser.

For context, match_stmt is a new alternative for compound_statement in the surface syntax and Match is a new alternative for stmt in the abstract syntax.

Patterns

The top-level surface syntax for patterns is as follows:

open_pattern: # Pattern may use multiple tokens with no closing delimiter
    | as_pattern
    | or_pattern

as_pattern: [closed_pattern] pattern_as_clause

or_pattern: '|'.simple_pattern+

simple_pattern: # Subnode where "as" and "or" patterns must be parenthesised
    | closed_pattern
    | value_constraint

closed_pattern: # Require a single token or a closing delimiter in pattern
    | wildcard_pattern
    | group_pattern
    | structural_constraint

As described above, the usage of open patterns is limited to top level case clauses and when parenthesised in a group pattern.

The abstract syntax for patterns explicitly indicates which elements are subpatterns and which elements are subexpressions or identifiers:

pattern = MatchAlways
     | MatchValue(matchop op, expr value)
     | MatchSequence(pattern* patterns)
     | MatchMapping(expr* keys, pattern* patterns)
     | MatchAttrs(expr cls, identifier* attrs, pattern* patterns)
     | MatchClass(expr cls, pattern* patterns, identifier* extra_attrs, pattern* extra_patterns)

     | MatchRestOfSequence(identifier? target)
     -- A NULL entry in the MatchMapping key list handles capturing extra mapping keys

     | MatchAs(pattern? pattern, identifier target)
     | MatchOr(pattern* patterns)

as_pattern: [closed_pattern] pattern_as_clause
pattern_as_clause: 'as' pattern_capture_target
pattern_capture_target: !"__" NAME !('.' | '(' | '=')

MatchAs(pattern? pattern, identifier target)

or_pattern: '|'.simple_pattern+

simple_pattern: # Subnode where "as" and "or" patterns must be parenthesised
    | closed_pattern
    | value_constraint

MatchOr(pattern* patterns)

value_constraint:
    | eq_constraint
    | id_constraint

eq_constraint: '==' closed_expr
id_constraint: 'is' closed_expr

closed_expr: # Require a single token or a closing delimiter in expression
    | primary
    | closed_factor

closed_factor: # "factor" is the main grammar node for these unary ops
    | '+' primary
    | '-' primary
    | '~' primary

MatchValue(matchop op, expr value)
matchop = EqCheck | IdCheck

# Literal patterns
match number:
    case == 0:
        print("Nothing")
    case == 1:
        print("Just one")
    case == 2:
        print("A couple")
    case == -1:
        print("One less than nothing")
    case == (1-1j):
        print("Good luck with that...")

# Additional literal patterns
match value:
    case == True:
        print("True or 1")
    case == False:
        print("False or 0")
    case == None:
        print("None")
    case == "Hello":
        print("Text 'Hello'")
    case == b"World!":
        print("Binary 'World!'")

# Matching by identity rather than equality
SENTINEL = object()
match value:
    case is True:
        print("True, not 1")
    case is False:
        print("False, not 0")
    case is None:
        print("None, following PEP 8 comparison guidelines")
    case is ...:
        print("May be useful when writing __getitem__ methods?")
    case is SENTINEL:
        print("Matches the sentinel by identity, not just value")

# Matching against variables and attributes
from enum import Enum
class Sides(str, Enum):
    SPAM = "Spam"
    EGGS = "eggs"
    ...

preferred_side = Sides.EGGS
match entree[-1]:
    case == Sides.SPAM:  # Compares entree[-1] == Sides.SPAM.
        response = "Have you got anything without Spam?"
    case == preferred_side:  # Compares entree[-1] == preferred_side
        response = f"Oh, I love {preferred_side}!"
    case as side:  # Assigns side = entree[-1].
        response = f"Well, could I have their Spam instead of the {side} then?"

wildcard_pattern: "__"

MatchAlways

match sequence:
    case [__]:               # any sequence with a single element
        return True
    case [start, *__, end]:  # a sequence with at least two elements
        return start == end
    case __:                 # anything
        return False

group_pattern: '(' open_pattern ')'

structural_constraint:
    | sequence_constraint
    | mapping_constraint
    | attrs_constraint
    | class_constraint

sequence_constraint: '[' [sequence_constraint_elements] ']'
sequence_constraint_elements: ','.sequence_constraint_element+ ','?
sequence_constraint_element:
    | star_pattern
    | simple_pattern
    | pattern_as_clause
star_pattern: '*' (pattern_as_clause | wildcard_pattern)

simple_pattern: # Subnode where "as" and "or" patterns must be parenthesised
    | closed_pattern
    | value_constraint

pattern_as_clause: 'as' pattern_capture_target

MatchSequence(pattern* patterns)

MatchRestOfSequence(identifier? target)

mapping_constraint: '{' [mapping_constraint_elements] '}'
mapping_constraint_elements: ','.key_value_constraint+ ','?
key_value_constraint:
    | closed_expr pattern_as_clause
    | closed_expr ':' simple_pattern
    | double_star_capture
double_star_capture: '**' pattern_as_clause

MatchMapping(expr* keys, pattern* patterns)

attrs_constraint:
    | name_or_attr '{' [attrs_constraint_elements] '}'
attrs_constraint_elements: ','.attr_value_pattern+ ','?
attr_value_pattern:
    | '.' NAME pattern_as_clause
    | '.' NAME value_constraint
    | '.' NAME ':' simple_pattern
    | '.' NAME

MatchAttrs(expr cls, identifier* attrs, pattern* patterns)

class_constraint:
    | name_or_attr '(' ')'
    | name_or_attr '(' positional_patterns ','? ')'
    | name_or_attr '(' class_constraint_attrs ')'
    | name_or_attr '(' positional_patterns ',' class_constraint_attrs] ')'
positional_patterns: ','.positional_pattern+
positional_pattern:
    | simple_pattern
    | pattern_as_clause
class_constraint_attrs:
    | '**' '{' [attrs_constraint_elements] '}'

MatchClass(expr cls, pattern* patterns, identifier* extra_attrs, pattern* extra_patterns)

Requiring explicit qualification of simple names in match patterns

The first iteration of this PEP accepted the basic premise of PEP 634 that iterable unpacking syntax would provide a good foundation for defining a new syntax for pattern matching.

During the review process, however, two major and one minor ambiguity problems were highlighted that arise directly from that core assumption:

• most problematically, when binding simple names by default is extended to PEP 634’s proposed class pattern syntax, the ATTR=TARGET_NAME construct binds to the right without using the as keyword, and uses the normal assignment-to-the-left sigil (=) to do it!
• when binding simple names by default is extended to PEP 634’s proposed mapping pattern syntax, the KEY: TARGET_NAME construct binds to the right without using the as keyword
• using a PEP 634 capture pattern together with an AS pattern (TARGET_NAME_1 as TARGET_NAME_2) gives an odd “binds to both the left and right” behaviour

The third revision of this PEP accounted for this problem by abandoning the alignment with iterable unpacking syntax, and instead requiring that all uses of bare simple names for anything other than a variable lookup be qualified by a preceding sigil or keyword:

• as NAME: local variable binding
• .NAME: attribute lookup
• == NAME: variable lookup
• is NAME: variable lookup
• any other usage: variable lookup

The key benefit of this approach is that it makes interpretation of simple names in patterns a local activity: a leading as indicates a name binding, a leading . indicates an attribute lookup, and anything else is a variable lookup (regardless of whether we’re reading a subpattern or a subexpression).

With the syntax now proposed in this PEP, the problematic cases identified above no longer read poorly:

• .ATTR as TARGET_NAME is more obviously a binding than ATTR=TARGET_NAME
• KEY as TARGET_NAME is more obviously a binding than KEY: TARGET_NAME
• (as TARGET_NAME_1) as TARGET_NAME_2 is more obviously two bindings than TARGET_NAME_1 as TARGET_NAME_2

Resisting the temptation to guess

PEP 635 looks at the way pattern matching is used in other languages, and attempts to use that information to make plausible predictions about the way pattern matching will be used in Python:

• wanting to extract values to local names will probably be more common than wanting to match against values stored in local names
• wanting comparison by equality will probably be more common than wanting comparison by identity
• users will probably be able to at least remember that bare names bind values and attribute references look up values, even if they can’t figure that out for themselves without reading the documentation or having someone tell them

To be clear, I think these predictions actually are plausible. However, I also don’t think we need to guess about this up front: I think we can start out with a more explicit syntax that requires users to state their intent using a prefix marker (either as, ==, or is), and then reassess the situation in a few years based on how pattern matching is actually being used in Python.

At that point, we’ll be able to choose amongst at least the following options:

• deciding the explicit syntax is concise enough, and not changing anything
• adding inferred identity constraints for one or more of None, ..., True and False
• adding inferred equality constraints for other literals (potentially including complex literals)
• adding inferred equality constraints for attribute lookups
• adding either inferred equality constraints or inferred capture patterns for bare names

All of those ideas could be considered independently on their own merits, rather than being a potential barrier to introducing pattern matching in the first place.

If any of these syntactic shortcuts were to eventually be introduced, they’d also be straightforward to explain in terms of the underlying more explicit syntax (the leading as, ==, or is would just be getting inferred by the parser, without the user needing to provide it explicitly). At the implementation level, only the parser should need to be change, as the existing AST nodes could be reused.

Interaction with caching of attribute lookups in local variables

One of the major changes between this PEP and PEP 634 is to use == EXPR for equality constraint lookups, rather than only offering NAME.ATTR. The original motivation for this was to avoid the semantic conflict with regular assignment targets, where NAME.ATTR is already used in assignment statements to set attributes, so if NAME.ATTR were the only syntax for symbolic value matching, then we’re pre-emptively ruling out any future attempts to allow matching against single patterns using the existing assignment statement syntax. The current motivation is more about the general desire to avoid guessing about user’s intent, and instead requiring them to state it explicitly in the syntax.

However, even within match statements themselves, the name.attr syntax for value patterns has an undesirable interaction with local variable assignment, where routine refactorings that would be semantically neutral for any other Python statement introduce a major semantic change when applied to a PEP 634 style match statement.

Consider the following code:

while value < self.limit:
    ... # Some code that adjusts "value"

The attribute lookup can be safely lifted out of the loop and only performed once:

_limit = self.limit:
while value < _limit:
    ... # Some code that adjusts "value"

With the marker prefix based syntax proposal in this PEP, value constraints would be similarly tolerant of match patterns being refactored to use a local variable instead of an attribute lookup, with the following two statements being functionally equivalent:

match expr:
    case {"key": == self.target}:
        ... # Handle the case where 'expr["key"] == self.target'
    case __:
        ... # Handle the non-matching case

_target = self.target
match expr:
    case {"key": == _target}:
        ... # Handle the case where 'expr["key"] == self.target'
    case __:
        ... # Handle the non-matching case

By contrast, when using PEP 634’s value and capture pattern syntaxes that omit the marker prefix, the following two statements wouldn’t be equivalent at all:

# PEP 634's value pattern syntax
match expr:
    case {"key": self.target}:
        ... # Handle the case where 'expr["key"] == self.target'
    case _:
        ... # Handle the non-matching case

# PEP 634's capture pattern syntax
_target = self.target
match expr:
    case {"key": _target}:
        ... # Matches any mapping with "key", binding its value to _target
    case _:
        ... # Handle the non-matching case

This PEP ensures the original semantics are retained under this style of simplistic refactoring: use == name to force interpretation of the result as a value constraint, use as name for a name binding.

PEP 634’s proposal to offer only the shorthand syntax, with no explicitly prefixed form, means that the primary answer on offer is “Well, don’t do that, then, only compare against attributes in namespaces, don’t compare against simple names”.

PEP 622’s walrus pattern syntax had another odd interaction where it might not bind the same object as the exact same walrus expression in the body of the case clause, but PEP 634 fixed that discrepancy by replacing walrus patterns with AS patterns (where the fact that the value bound to the name on the RHS might not be the same value as returned by the LHS is a standard feature common to all uses of the “as” keyword).

Using existing comparison operators as the value constraint prefix

If the benefit of a dedicated value constraint prefix is accepted, then the next question is to ask exactly what that prefix should be.

The initially published version of this PEP proposed using the previously unused ? symbol as the prefix for equality constraints, and ?is as the prefix for identity constraints. When reviewing the PEP, Steven D’Aprano presented a compelling counterproposal [5] to use the existing comparison operators (== and is) instead.

There were a few concerns with == as a prefix that kept it from being chosen as the prefix in the initial iteration of the PEP:

• for common use cases, it’s even more visually noisy than ?, as a lot of folks with PEP 8 trained aesthetic sensibilities are going to want to put a space between it and the following expression, effectively making it a 3 character prefix instead of 1
• when used in a mapping pattern, there needs to be a space between the : key/value separator and the == prefix, or the tokeniser will split them up incorrectly (getting := and = instead of : and ==)
• when used in an OR pattern, there needs to be a space between the | pattern separator and the == prefix, or the tokeniser will split them up incorrectly (getting |= and = instead of | and ==)
• if used in a PEP 634 style class pattern, there needs to be a space between the = keyword separator and the == prefix, or the tokeniser will split them up incorrectly (getting == and = instead of = and ==)

Rather than introducing a completely new symbol, Steven’s proposed resolution to this verbosity problem was to retain the ability to omit the prefix marker in syntactically unambiguous cases.

While the idea of omitting the prefix marker was accepted for the second revision of the proposal, it was dropped again in the third revision due to ambiguity concerns. Instead, the following points apply:

• for class patterns, other syntax changes allow equality constraints to be written as .ATTR == EXPR, and identity constraints to be written as .ATTR is EXPR, both of which are quite easy to read
• for mapping patterns, the extra syntactic noise is just tolerated (at least for now)
• for OR patterns, the extra syntactic noise is just tolerated (at least for now). However, membership constraints may offer a future path to reducing the need to combine OR patterns with equality constraints (instead, the values to be checked against would be collected as a set, list, or tuple).

Given that perspective, PEP 635’s arguments against using ? as part of the pattern matching syntax held for this proposal as well, and so the PEP was amended accordingly.

Using __ as the wildcard pattern marker

PEP 635 makes a solid case that introducing ? solely as a wildcard pattern marker would be a bad idea. With the syntax for value constraints changed to use existing comparison operations rather than ? and ?is, that argument holds for this PEP as well.

However, as noted by Thomas Wouters in [6], PEP 634’s choice of _ remains problematic as it would likely mean that match patterns would have a permanent difference from all other parts of Python - the use of _ in software internationalisation and at the interactive prompt means that there isn’t really a plausible path towards using it as a general purpose “skipped binding” marker.

__ is an alternative “this value is not needed” marker drawn from a Stack Overflow answer [7] (originally posted by the author of this PEP) on the various meanings of _ in existing Python code.

This PEP also proposes adopting an implementation technique that limits the scope of the associated special casing of __ to the parser: defining a new AST node type (MatchAlways) specifically for wildcard markers, rather than passing it through to the AST as a Name node.

Within the parser, __ still means either a regular name or a wildcard marker in a match pattern depending on where you were in the parse tree, but within the rest of the compiler, Name("__") is still a normal variable name, while MatchAlways() is always a wildcard marker in a match pattern.

Unlike _, the lack of other use cases for __ means that there would be a plausible path towards restoring identifier handling consistency with the rest of the language by making __ mean “skip this name binding” everywhere in Python:

• in the interpreter itself, deprecate loading variables with the name __. This would make reading from __ emit a deprecation warning, while writing to it would initially be unchanged. To avoid slowing down all name loads, this could be handled by having the compiler emit additional code for the deprecated name, rather than using a runtime check in the standard name loading opcodes.
• after a suitable number of releases, change the parser to emit a new SkippedBinding AST node for all uses of __ as an assignment target, and update the rest of the compiler accordingly
• consider making __ a true hard keyword rather than a soft keyword

This deprecation path couldn’t be followed for _, as there’s no way for the interpreter to distinguish between attempts to read back _ when nominally used as a “don’t care” marker, and legitimate reads of _ as either an i18n text translation function or as the last statement result at the interactive prompt.

Names starting with double-underscores are also already reserved for use by the language, whether that is for compile time constants (i.e. __debug__), special methods, or class attribute name mangling, so using __ here would be consistent with that existing approach.

Representing patterns explicitly in the Abstract Syntax Tree

PEP 634 doesn’t explicitly discuss how match statements should be represented in the Abstract Syntax Tree, instead leaving that detail to be defined as part of the implementation.

As a result, while the reference implementation of PEP 634 definitely works (and formed the basis of the reference implementation of this PEP), it does contain a significant design flaw: despite the notes in PEP 635 that patterns should be considered as distinct from expressions, the reference implementation goes ahead and represents them in the AST as expression nodes.

The result is an AST that isn’t very abstract at all: nodes that should be compiled completely differently (because they’re patterns rather than expressions) are represented the same way, and the type system of the implementation language (e.g. C for CPython) can’t offer any assistance in keeping track of which subnodes should be ordinary expressions and which should be subpatterns.

Rather than continuing with that approach, this PEP has instead defined a new explicit “pattern” node in the AST, which allows the patterns and their permitted subnodes to be defined explicitly in the AST itself, making the code implementing the new feature clearer, and allowing the C compiler to provide more assistance in keeping track of when the code generator is dealing with patterns or expressions.

This change in implementation approach is actually orthogonal to the surface syntax changes proposed in this PEP, so it could still be adopted even if the rest of the PEP were to be rejected.

Changes to sequence patterns

This PEP makes one notable change to sequence patterns relative to PEP 634:

• only the square bracket form of sequence pattern is supported. Neither open (no delimiters) nor tuple style (parentheses as delimiters) sequence patterns are supported.

Relative to PEP 634, sequence patterns are also significantly affected by the change to require explicit qualification of capture patterns and value constraints, as it means case [a, b, c]: must instead be written as case [as a, as b, as c]: and case [0, 1]: must instead be written as case [== 0, == 1]:.

With the syntax for sequence patterns no longer being derived directly from the syntax for iterable unpacking, it no longer made sense to keep the syntactic flexibility that had been included in the original syntax proposal purely for consistency with iterable unpacking.

Allowing open and tuple style sequence patterns didn’t increase expressivity, only ambiguity of intent (especially relative to group patterns), and encouraged readers down the path of viewing pattern matching syntax as intrinsically linked to assignment target syntax (which the PEP 634 authors have stated multiple times is not a desirable path to have readers take, and a view the author of this PEP now shares, despite disagreeing with it originally).

Changes to mapping patterns

This PEP makes two notable changes to mapping patterns relative to PEP 634:

• value capturing is written as KEY as NAME rather than as KEY: NAME
• a wider range of keys are permitted: any “closed expression”, rather than only literals and attribute references

As discussed above, the first change is part of ensuring that all binding operations with the target name to the right of a subexpression or pattern use the as keyword.

The second change is mostly a matter of simplifying the parser and code generator code by reusing the existing expression handling machinery. The restriction to closed expressions is designed to help reduce ambiguity as to where the key expression ends and the match pattern begins. This mostly allows a superset of what PEP 634 allows, except that complex literals must be written in parentheses (at least for now).

Adapting PEP 635’s mapping pattern examples to the syntax proposed in this PEP:

match json_pet:
    case {"type": == "cat", "name" as name, "pattern" as pattern}:
        return Cat(name, pattern)
    case {"type": == "dog", "name" as name, "breed" as breed}:
        return Dog(name, breed)
    case __:
        raise ValueError("Not a suitable pet")

def change_red_to_blue(json_obj):
    match json_obj:
        case { 'color': (== 'red' | == '#FF0000') }:
            json_obj['color'] = 'blue'
        case { 'children' as children }:
            for child in children:
                change_red_to_blue(child)

For reference, the equivalent PEP 634 syntax:

match json_pet:
    case {"type": "cat", "name": name, "pattern": pattern}:
        return Cat(name, pattern)
    case {"type": "dog", "name": name, "breed": breed}:
        return Dog(name, breed)
    case _:
        raise ValueError("Not a suitable pet")

def change_red_to_blue(json_obj):
    match json_obj:
        case { 'color': ('red' | '#FF0000') }:
            json_obj['color'] = 'blue'
        case { 'children': children }:
            for child in children:
                change_red_to_blue(child)

Changes to class patterns

This PEP makes several notable changes to class patterns relative to PEP 634:

• the syntactic alignment with class instantiation is abandoned as being actively misleading and unhelpful. Instead, a new dedicated syntax for checking additional attributes is introduced that draws inspiration from mapping patterns rather than class instantiation
• a new dedicated syntax for simple ducktyping that will work for any class is introduced
• the special casing of various builtin and standard library types is supplemented by a general check for the existence of a __match_args__ attribute with the value of None

As discussed above, the first change has two purposes:

• it’s part of ensuring that all binding operations with the target name to the right of a subexpression or pattern use the as keyword. Using = to assign to the right is particularly problematic.
• it’s part of ensuring that all uses of simple names in patterns have a prefix that indicates their purpose (in this case, a leading . to indicate an attribute lookup)

The syntactic alignment with class instantion was also judged to be unhelpful in general, as class patterns are about matching patterns against attributes, while class instantiation is about matching call arguments to parameters in class constructors, which may not bear much resemblance to the resulting instance attributes at all.

The second change is intended to make it easier to use pattern matching for the “ducktyping” style checks that are already common in Python.

The concrete syntax proposal for these patterns then arose from viewing instances as mappings of attribute names to values, and combining the attribute lookup syntax (.ATTR), with the mapping pattern syntax {KEY: PATTERN} to give cls{.ATTR: PATTERN}.

Allowing cls{.ATTR} to mean the same thing as cls{.ATTR: __} was a matter of considering the leading . sufficient to render the name usage unambiguous (it’s clearly an attribute reference, whereas matching against a variable key in a mapping pattern would be arguably ambiguous)

The final change just supplements a CPython-internal-only check in the PEP 634 reference implementation by making it the default behaviour that classes get if they don’t define __match_args__ (the optimised fast path for the builtin and standard library types named in PEP 634 is retained).

Adapting the class matching example linked from PEP 635 shows that for purely positional class matching, the main impact comes from the changes to value constraints and name binding, not from the class matching changes:

match expr:
    case BinaryOp(== '+', as left, as right):
        return eval_expr(left) + eval_expr(right)
    case BinaryOp(== '-', as left, as right):
        return eval_expr(left) - eval_expr(right)
    case BinaryOp(== '*', as left, as right):
        return eval_expr(left) * eval_expr(right)
    case BinaryOp(== '/', as left, as right):
        return eval_expr(left) / eval_expr(right)
    case UnaryOp(== '+', as arg):
        return eval_expr(arg)
    case UnaryOp(== '-', as arg):
        return -eval_expr(arg)
    case VarExpr(as name):
        raise ValueError(f"Unknown value of: {name}")
    case float() | int():
        return expr
    case __:
        raise ValueError(f"Invalid expression value: {repr(expr)}")

For reference, the equivalent PEP 634 syntax:

match expr:
    case BinaryOp('+', left, right):
        return eval_expr(left) + eval_expr(right)
    case BinaryOp('-', left, right):
        return eval_expr(left) - eval_expr(right)
    case BinaryOp('*', left, right):
        return eval_expr(left) * eval_expr(right)
    case BinaryOp('/', left, right):
        return eval_expr(left) / eval_expr(right)
    case UnaryOp('+', arg):
        return eval_expr(arg)
    case UnaryOp('-', arg):
        return -eval_expr(arg)
    case VarExpr(name):
        raise ValueError(f"Unknown value of: {name}")
    case float() | int():
        return expr
    case _:
        raise ValueError(f"Invalid expression value: {repr(expr)}")

The changes to the class pattern syntax itself are more relevant when checking for named attributes and extracting their values without relying on __match_args__:

match expr:
    case object{.host as host, .port as port}:
        pass
    case object{.host as host}:
        pass

Compare this to the PEP 634 equivalent, where it really isn’t clear which names are referring to attributes of the match subject and which names are referring to local variables:

match expr:
    case object(host=host, port=port):
        pass
    case object(host=host):
        pass

In this specific case, that ambiguity doesn’t matter (since the attribute and variable names are the same), but in the general case, knowing which is which will be critical to reasoning correctly about the code being read.

Inferred value constraints

As discussed above, this PEP doesn’t rule out the possibility of adding inferred equality and identity constraints in the future.

These could be particularly valuable for literals, as it is quite likely that many “magic” strings and numbers with self-evident meanings will be written directly into match patterns, rather than being stored in named variables. (Think constants like None, or obviously special numbers like 0 and 1, or strings where their contents are as descriptive as any variable name, rather than cryptic checks against opaque numbers like 739452)

Making some required parentheses optional

The PEP currently errs heavily on the side of requiring parentheses in the face of potential ambiguity.

However, there are a number of cases where it at least arguably goes too far, mostly involving AS patterns with an explicit pattern.

In any position that requires a closed pattern, AS patterns may end up starting with doubled parentheses, as the nested pattern is also required to be a closed pattern: ((OPEN PTRN) as NAME)

Due to the requirement that the subpattern be closed, it should be reasonable in many of these cases (e.g. sequence pattern subpatterns) to accept CLOSED_PTRN as NAME directly.

Further consideration of this point has been deferred, as making required parentheses optional is a backwards compatible change, and hence relaxing the restrictions later can be considered on a case-by-case basis.

Accepting complex literals as closed expressions

PEP 634’s reference implementation includes a lot of special casing of binary operations in both the parser and the rest of the compiler in order to accept complex literals without accepting arbitrary binary numeric operations on literal values.

Ideally, this problem would be dealt with at the parser layer, with the parser directly emitting a Constant AST node prepopulated with a complex number. If that was the way things worked, then complex literals could be accepted through a similar mechanism to any other literal.

This isn’t how complex literals are handled, however. Instead, they’re passed through to the AST as regular BinOp nodes, and then the constant folding pass on the AST resolves them down to Constant nodes with a complex value.

For the parser to resolve complex literals directly, the compiler would need to be able to tell the tokenizer to generate a distinct token type for imaginary numbers (e.g. INUMBER), which would then allow the parser to handle NUMBER + INUMBER and NUMBER - INUMBER separately from other binary operations.

Alternatively, a new ComplexNumber AST node type could be defined, which would allow the parser to notify the subsequent compiler stages that a particular node should specifically be a complex literal, rather than an arbitrary binary operation. Then the parser could accept NUMBER + NUMBER and NUMBER - NUMBER for that node, while letting the AST validation for ComplexNumber take care of ensuring that the real and imaginary parts of the literal were real and imaginary numbers as expected.

For now, this PEP has postponed dealing with this question, and instead just requires that complex literals be parenthesised in order to be used in value constraints and as mapping pattern keys.

Allowing negated constraints in match patterns

With the syntax proposed in this PEP, it isn’t permitted to write != expr or is not expr as a match pattern.

Both of these forms have clear potential interpretations as a negated equality constraint (i.e. x != expr) and a negated identity constraint (i.e. x is not expr).

However, it’s far from clear either form would come up often enough to justify the dedicated syntax, so the possible extension has been deferred pending further community experience with match statements.

Allowing membership checks in match patterns

The syntax used for equality and identity constraints would be straightforward to extend to membership checks: in container.

One downside of the proposals in both this PEP and PEP 634 is that checking for multiple values in the same case doesn’t look like any existing container membership check in Python:

# PEP 634's literal patterns
match value:
    case 0 | 1 | 2 | 3:
        ...

# This PEP's equality constraints
match value:
    case == 0 | == 1 | == 2 | == 3:
        ...

Allowing inferred equality constraints under this PEP would only make it look like the PEP 634 example, it still wouldn’t look like the equivalent if statement header (if value in {0, 1, 2, 3}:).

Membership constraints would provide a more explicit, but still concise, way to check if the match subject was present in a container, and it would look the same as an ordinary containment check:

match value:
    case in {0, 1, 2, 3}:
        ...
    case in {one, two, three, four}:
        ...
    case in range(4): # It would accept any container, not just literal sets
        ...

Such a feature would also be readily extensible to allow all kinds of case clauses without any further syntax updates, simply by defining __contains__ appropriately on a custom class definition.

However, while this does seem like a useful extension, and a good way to resolve this PEP’s verbosity problem when combining multiple equality checks in an OR pattern, it isn’t essential to making match statements a valuable addition to the language, so it seems more appropriate to defer it to a separate proposal, rather than including it here.

Inferring a default type for instance attribute constraints

The dedicated syntax for instance attribute constraints means that object could be omitted from object{.ATTR} to give {.ATTR} without introducing any syntactic ambiguity (if no class was given, object would be implied, just as it is for the base class list in class definitions).

However, it’s far from clear saving six characters is worth making it harder to visually distinguish mapping patterns from instance attribute patterns, so allowing this has been deferred as a topic for possible future consideration.

Avoiding special cases in sequence patterns

Sequence patterns in both this PEP and PEP 634 currently special case str, bytes, and bytearray as specifically never matching a sequence pattern.

This special casing could potentially be removed if we were to define a new collections.abc.AtomicSequence abstract base class for types like these, where they’re conceptually a single item, but still implement the sequence protocol to allow random access to their component parts.

Expression syntax to retrieve multiple attributes from an instance

The instance attribute pattern syntax has been designed such that it could be used as the basis for a general purpose syntax for retrieving multiple attributes from an object in a single expression:

host, port = obj{.host, .port}

Similar to slice syntax only being allowed inside bracket subscrpts, the .attr syntax for naming attributes would only be allowed inside brace subscripts.

This idea isn’t required for pattern matching to be useful, so it isn’t part of this PEP. However, it’s mentioned as a possible path towards making pattern matching feel more integrated into the rest of the language, rather than existing forever in its own completely separated world.

Expression syntax to retrieve multiple attributes from an instance

If the brace subscript syntax were to be accepted for instance attribute pattern matching, and then subsequently extended to offer general purpose extraction of multiple attributes, then it could be extended even further to allow for retrieval of multiple items from containers based on the syntax used for mapping pattern matching:

host, port = obj{"host", "port"}
first, last = obj{0, -1}

Again, this idea isn’t required for pattern matching to be useful, so it isn’t part of this PEP. As with retrieving multiple attributes, however, it is included as an example of the proposed pattern matching syntax inspiring ideas for making object deconstruction easier in general.

Restricting permitted expressions in value constraints and mapping pattern keys

While it’s entirely technically possible to restrict the kinds of expressions permitted in value constraints and mapping pattern keys to just attribute lookups and constant literals (as PEP 634 does), there isn’t any clear runtime value in doing so, so this PEP proposes allowing any kind of primary expression (primary expressions are an existing node type in the grammar that includes things like literals, names, attribute lookups, function calls, container subscripts, parenthesised groups, etc), as well as high precedence unary operations (+, -, ~) on primary expressions.

While PEP 635 does emphasise several times that literal patterns and value patterns are not full expressions, it doesn’t ever articulate a concrete benefit that is obtained from that restriction (just a theoretical appeal to it being useful to separate static checks from dynamic checks, which a code style tool could still enforce, even if the compiler itself is more permissive).

The last time we imposed such a restriction was for decorator expressions and the primary outcome of that was that users had to put up with years of awkward syntactic workarounds (like nesting arbitrary expressions inside function calls that just returned their argument) to express the behaviour they wanted before the language definition was finally updated to allow arbitrary expressions and let users make their own decisions about readability.

The situation in PEP 634 that bears a resemblance to the situation with decorator expressions is that arbitrary expressions are technically supported in value patterns, they just require awkward workarounds where either all the values to match need to be specified in a helper class that is placed before the match statement:

# Allowing arbitrary match targets with PEP 634's value pattern syntax
class mt:
    value = func()
match expr:
    case (_, mt.value):
        ... # Handle the case where 'expr[1] == func()'

Or else they need to be written as a combination of a capture pattern and a guard expression:

# Allowing arbitrary match targets with PEP 634's guard expressions
match expr:
    case (_, _matched) if _matched == func():
        ... # Handle the case where 'expr[1] == func()'

This PEP proposes skipping requiring any such workarounds, and instead supporting arbitrary value constraints from the start:

match expr:
    case (__, == func()):
        ... # Handle the case where 'expr == func()'

Whether actually writing that kind of code is a good idea would be a topic for style guides and code linters, not the language compiler.

In particular, if static analysers can’t follow certain kinds of dynamic checks, then they can limit the permitted expressions at analysis time, rather than the compiler restricting them at compile time.

There are also some kinds of expressions that are almost certain to give nonsensical results (e.g. yield, yield from, await) due to the pattern caching rule, where the number of times the constraint expression actually gets evaluated will be implementation dependent. Even here, the PEP takes the view of letting users write nonsense if they really want to.

Aside from the recently updated decorator expressions, another situation where Python’s formal syntax offers full freedom of expression that is almost never used in practice is in except clauses: the exceptions to match against almost always take the form of a simple name, a dotted name, or a tuple of those, but the language grammar permits arbitrary expressions at that point. This is a good indication that Python’s user base can be trusted to take responsibility for finding readable ways to use permissive language features, by avoiding writing hard to read constructs even when they’re permitted by the compiler.

This permissiveness comes with a real concrete benefit on the implementation side: dozens of lines of match statement specific code in the compiler is replaced by simple calls to the existing code for compiling expressions (including in the AST validation pass, the AST optimization pass, the symbol table analysis pass, and the code generation pass). This implementation benefit would accrue not just to CPython, but to every other Python implementation looking to add match statement support.

Requiring the use of constraint prefix markers for mapping pattern keys

The initial (unpublished) draft of this proposal suggested requiring mapping pattern keys be value constraints, just as PEP 634 requires that they be valid literal or value patterns:

import constants

match config:
    case {== "route": route}:
        process_route(route)
    case {== constants.DEFAULT_PORT: sub_config, **rest}:
        process_config(sub_config, rest)

However, the extra characters were syntactically noisy and unlike its use in value constraints (where it distinguishes them from non-pattern expressions), the prefix doesn’t provide any additional information here that isn’t already conveyed by the expression’s position as a key within a mapping pattern.

Accordingly, the proposal was simplified to omit the marker prefix from mapping pattern keys.

This omission also aligns with the fact that containers may incorporate both identity and equality checks into their lookup process - they don’t purely rely on equality checks, as would be incorrectly implied by the use of the equality constraint prefix.

Allowing the key/value separator to be omitted for mapping value constraints

Instance attribute patterns allow the : separator to be omitted when writing attribute value constraints like case object{.attr == expr}.

Offering a similar shorthand for mapping value constraints was considered, but permitting it allows thoroughly baffling constructs like case {0 == 0}: where the compiler knows this is the key 0 with the value constraint == 0, but a human reader sees the tautological comparison operation 0 == 0. With the key/value separator included, the intent is more obvious to a human reader as well: case {0: == 0}: