PEP 622 – Structural Pattern Matching

A simplified, approximate grammar for the proposed syntax is:

...
compound_statement:
    | if_stmt
    ...
    | match_stmt
match_stmt: "match" expression ':' NEWLINE INDENT case_block+ DEDENT
case_block: "case" pattern [guard] ':' block
guard: 'if' expression
pattern: NAME ':=' or_pattern | or_pattern
or_pattern: closed_pattern ('|' closed_pattern)*
closed_pattern:
    | name_pattern
    | literal_pattern
    | constant_pattern
    | group_pattern
    | sequence_pattern
    | mapping_pattern
    | class_pattern

(Seefor the full, unabridged grammar.)

We propose the match syntax to be a statement, not an expression. Although in many languages it is an expression, being a statement better suits the general logic of Python syntax. Seefor more discussion. The list of allowed patterns is specified below in thesubsection.

The match and case keywords are proposed to be soft keywords, so that they are recognized as keywords at the beginning of a match statement or case block respectively, but are allowed to be used in other places as variable or argument names.

The proposed indentation structure is as following:

match some_expression:
    case pattern_1:
        ...
    case pattern_2:
        ...

The proposed large scale semantics for choosing the match is to choose the first matching pattern and execute the corresponding suite. The remaining patterns are not tried. If there are no matching patterns, the statement 'falls through', and execution continues at the following statement.

Essentially this is equivalent to a chain of if ... elif ... else statements. Note that unlike for the previously proposed switch statement, the pre-computed dispatch dictionary semantics does not apply here.

There is no default or else case - instead the special wildcard _ can be used (see the section on) as a final 'catch-all' pattern.

Name bindings made during a successful pattern match outlive the executed suite and can be used after the match statement. This follows the logic of other Python statements that can bind names, such as for loop and with statement. For example:

match shape:
    case Point(x, y):
        ...
    case Rectangle(x, y, _, _):
        ...
print(x, y)  # This works

We introduce the proposed syntax gradually. Here we start from the main building blocks. The following patterns are supported:

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...")

match greeting:
    case "":
        print("Hello!")
    case name:
        print(f"Hi {name}!")

match greeting:
    case "":
        print("Hello!")
    case name:
        print(f"Hi {name}!")
if name == "Santa":      # <-- might raise UnboundLocalError
    ...                  # but works fine if greeting was not empty

match data:
    case [x, x]:  # Error!
        ...
    case [_, _]:
        print("Some pair")
        print(_)  # Error!

from enum import Enum

class Color(Enum):
    BLACK = 1
    RED = 2

BLACK = 1
RED = 2

match color:
    case .BLACK | Color.BLACK:
        print("Black suits every color")
    case BLACK:  # This will just assign a new value to BLACK.
        ...

case ._: ...
case _.a: ...

match collection:
    case 1, [x, *others]:
        print("Got 1 and a nested sequence")
    case (1, x):
        print(f"Got 1 and {x}")

import constants

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

match shape:
    case Point(x, y):
        ...
    case Rectangle(x0, y0, x1, y1, painted=True):
        ...

Combining multiple patterns

Multiple alternative patterns can be combined into one using | . This means the the whole pattern matches if at least one alternative matches. Alternatives are tried from left to right and have short-circuit property, subsequent patterns are not tried if one matched. Examples:

match something:
    case 0 | 1 | 2:
        print("Small number")
    case [] | [_]:
        print("A short sequence")
    case str() | bytes():
        print("Something string-like")
    case _:
        print("Something else")

The alternatives may bind variables, as long as each alternative binds the same set of variables (excluding _ ). For example:

match something:
    case 1 | x:  # Error!
        ...
    case x | 1:  # Error!
        ...
    case one := [1] | two := [2]:  # Error!
        ...
    case Foo(arg=x) | Bar(arg=x):  # Valid, both arms bind 'x'
        ...
    case [x] | x:  # Valid, both arms bind 'x'
        ...

Each top-level pattern can be followed by a guard of the form if expression . A case clause succeeds if the pattern matches and the guard evaluates to a true value. For example:

match input:
    case [x, y] if x > MAX_INT and y > MAX_INT:
        print("Got a pair of large numbers")
    case x if x > MAX_INT:
        print("Got a large number")
    case [x, y] if x == y:
        print("Got equal items")
    case _:
        print("Not an outstanding input")

If evaluating a guard raises an exception, it is propagated onwards rather than fail the case clause. Names that appear in a pattern are bound before the guard succeeds. So this will work:

values = [0]

match value:
    case [x] if x:
        ...  # This is not executed
    case _:
        ...
print(x)  # This will print "0"

Note that guards are not allowed for nested patterns, so that [x if x > 0] is a SyntaxError and 1 | 2 if 3 | 4 will be parsed as (1 | 2) if (3 | 4) .

It is often useful to match a sub-pattern and to bind the corresponding value to a name. For example, it can be useful to write more efficient matches, or simply to avoid repetition. To simplify such cases, a name pattern can be combined with another arbitrary pattern using named sub-patterns of the form name := pattern . For example:

match get_shape():
    case Line(start := Point(x, y), end) if start == end:
        print(f"Zero length line at {x}, {y}")

Note that the name pattern used in the named sub-pattern can be used in the match suite, or after the match statement. However, the name will only be bound if the sub-pattern succeeds. Another example:

match group_shapes():
    case [], [point := Point(x, y), *other]:
        print(f"Got {point} in the second group")
        process_coordinates(x, y)
        ...

Technically, most such examples can be rewritten using guards and/or nested match statements, but this will be less readable and/or will produce less efficient code. Essentially, most of the arguments inPEP 572 apply here equally.

_ is not a valid name here.

The __match__() protocol

TODO: Show equivalent pseudo code.

The __match__() method is used to decide whether an object matches a given class pattern and to extract the corresponding attributes. It must be a class method or a static method returning an object (typically the same as the argument), or None to indicate that no match is possible. (More about the return value in the next section.)

The procedure is as following:

• The class object for Class in Class(<sub-patterns>) is looked up and Class.__match__(obj) is called where obj is the value being matched.
• If the result of the call (which we are referring to as "match proxy") is None , the match fails.
• Otherwise, if any sub-patterns are given in the form of positional or keyword arguments, these are matched from left to right, as follows. The match fails as soon as a sub-pattern fails; if all sub-patterns succeed, the overall class pattern match succeeds.
• If there are match-by-position items and the class has a __match_args__ which is not None , the item at position i is matched against the value looked up by attribute __match_args__[i] . For example, a pattern Point2D(5, 8) , where Point2D.__match_args__ == ["x", "y"] , is translated (approximately) into obj.x == 5 and obj.y == 8 .
• When __match_args__ is missing (as is the default) or None , a single positional sub-pattern is allowed to be passed to the call. Rather than being matched against any particular attribute on the proxy, it is instead matched against the proxy itself. This creates default behavior that is useful and intuitive for most objects:
  • bool(False) matches False (but not 0 ).
  • tuple((0, 1, 2)) matches (0, 1, 2) (but not [0, 1, 2] ).
  • int(i) matches any int and binds it to the name i .
• If there are more positional items than the length of __match_args__ , an ImpossibleMatchError is raised.
• If the __match_args__ attribute is absent on the matched class or None , but more than one positional item appears in a match, ImpossibleMatchError is also raised. We don't fall back on using __slots__ or __annotations__ -- "In the face of ambiguity, refuse the temptation to guess."
• If there are any match-by-keyword items the keywords are looked up as attributes on the proxy. If the lookup succeeds the value is matched against the corresponding sub-pattern. If the lookup fails, two cases are distinguished:
• If an attribute is missing on the proxy and the class being matched has no __match_args__ attribute (or it is None ), the match fails. This allows one to write case object(name=_) to implement a check for the presence of a given attribute, or case object(name=var) to check for its presence and extract its value.
• If an attribute is missing and the class has a __match_args__ which is not None , the match fails if the attribute name is in __match_args__ , else the match raises ImpossibleMatchError .

Such a protocol favors simplicity of implementation over flexibility and performance. For other considered alternatives, see.

Result value of __match__()

If a match is successful, the __match__() method should return an object whose attribute values will then be bound to the corresponding keyword argument names in the pattern after the match is complete. For each possible name that is legal in the match pattern, the returned object should have a corresponding attribute with that name, that can be used to access that value. (Positional sub-patterns are matched to keyword sub-patterns using __match_args__ as shown in the previous section.)

For most ordinary objects, this returned object can simply be the original object, unchanged.

However, there may be cases where the internal implementation of a class is very different than its public representation, for example a Point class with x , y and z attributes may be represented internally as a vector; in such cases a 'proxy object' may be returned whose attributes correspond to the matchable names. There is no requirement that the attributes on the proxy object be the same type or value as the attributes of the original object; one envisioned use case is for expensive-to-compute properties to be computed lazily on the proxy object via property getters.

In deciding what names should be available for matching, the recommended practice is that class patterns should be the mirror of construction; that is, the set of available names and their types should resemble the arguments to __init__() .

Impossible and ambiguous matches are detected at runtime and a special exception ImpossibleMatchError (proposed to be a subclass of TypeError ) will be raised. In addition to basic checks described in the previous subsection:

• The interpreter will check that two match items are not targeting the same attribute, for example Point2D(1, 2, y=3) is an error.

Special attribute __match_args__

The __match_args__ attribute complements the __match__ method and is always looked up on the same class as the __match__ method. __match_args__ , if it is present and not None , must be a list or tuple of strings naming the allowed positional arguments.

Default object.__match__()

The default implementation aims at providing a basic, useful (but still safe) experience with pattern matching out of the box. For this purpose the default __match__() method follows this logic (pseudo-code):

class object:
    @classmethod
    def __match__(cls, instance):
        if isinstance(instance, cls):
            return instance

This means that pattern matching is allowed by default for every class. If a class wants to disallow pattern matching against itself, it should define __match__ = None . This will cause an exception when trying to match against such a class.

The above implementation means that by default only match-by-name and a single positional match by value against the proxy will work, and classes should define __match_args__ (e.g. as a class attribute) if they would like to support match-by-position. Additionally, dataclasses will support match-by-position out of the box. See below for more details.

Finally, all attributes are exposed for matching, if a class wants to hide some attributes from matching against them, a custom __match__() method is required.

To facilitate the use of pattern matching, several changes will be made to the standard library:

• Namedtuples and dataclasses will have auto-generated __match_args__ .
• For dataclasses the order of attributes in the generated __match_args__ will be the same as the order of corresponding arguments in the generated __init__() method. This includes the situations where attributes are inherited from a superclass.

In addition, a systematic effort will be put into going through existing standard library classes and adding custom __match__() and/or __match_args__ where it looks beneficial.

Exhaustiveness checks

From a reliability perspective, experience shows that missing a case when dealing with a set of possible data values leads to hard to debug issues, thus forcing people to add safety asserts like this:

def get_first(data: Union[int, list[int]]) -> int:
    if isinstance(data, list) and data:
        return data[0]
    elif isinstance(data, int):
        return data
    else:
        assert False, "should never get here"

PEP 484 specifies that static type checkers should support exhaustiveness in conditional checks with respect to enum values.PEP 586 later generalized this requirement to literal types.

This PEP further generalizes this requirement to arbitrary patterns. A typical situation where this applies is matching an expression with a union type:

def classify(val: Union[int, Tuple[int, int], List[int]]) -> str:
    match val:
        case [x, *other]:
            return f"A sequence starting with {x}"
        case [x, y] if x > 0 and y > 0:
            return f"A pair of {x} and {y}"
        case int():
            return f"Some integer"
        # Type-checking error: some cases unhandled.

The exhaustiveness checks should also apply where both pattern matching and enum values are combined:

from enum import Enum
from typing import Union

class Level(Enum):
    BASIC = 1
    ADVANCED = 2
    PRO = 3

class User:
    name: str
    level: Level

class Admin:
    name: str

account: Union[User, Admin]

match account:
    case Admin(name=name) | User(name=name, level=Level.PRO):
        ...
    case User(level=Level.ADVANCED):
        ...
    # Type-checking error: basic user unhandled

Obviously, no Matchable protocol (in terms ofPEP 544) is needed, since every class is matchable and therefore is subject to the checks specified above.

Sealed classes as ADTs

Quite often it is desirable to apply exhaustiveness to a set of classes without defining ad-hoc union types, which is itself fragile if a class is missing in the union definition. A design pattern where a group of record-like classes is combined into a union is popular in other languages that support pattern matching and is known under a name of algebraic data typesor ADTs.

We propose to add a special decorator class @sealed to the typing module, that will have no effect at runtime, but will indicate to static type checkers that all subclasses (direct and indirect) of this class should be defined in the same module as the base class.

The idea is that since all subclasses are known, the type checker can treat the sealed base class as a union of all its subclasses. Together with dataclasses this allows a clean and safe support of ADTs in Python. Consider this example:

from dataclasses import dataclass
from typing import sealed

@sealed
class Node:
    ...

class Expression(Node):
    ...

class Statement(Node):
    ...

@dataclass
class Name(Expression):
    name: str

@dataclass
class Operation(Expression):
    left: Expression
    op: str
    right: Expression

@dataclass
class Assignment(Statement):
    target: str
    value: Expression

@dataclass
class Print(Statement):
    value: Expression

With such definition, a type checker can safely treat Node as Union[Name, Operation, Assignment, Print] , and also safely treat e.g. Expression as Union[Name, Operation] . So this will result in a type checking error in the below snippet, because Name is not handled (and type checker can give a useful error message):

def dump(node: Node) -> str:
    match node:
        case Assignment(target, value):
            return f"{target} = {dump(value)}"
        case Print(value):
            return f"print({dump(value)})"
        case Operation(left, op, right):
            return f"({dump(left)} {op} {dump(right)})"

Class patterns are subject to runtime type erasure. Namely, although one can define a type alias IntQueue = Queue[int] so that a pattern like IntQueue() is syntactically valid, type checkers should reject such a match:

queue: Union[Queue[int], Queue[str]]
match queue:
    case IntQueue():  # Type-checking error here
        ...

Note that the above snippet actually fails at runtime with the current implementation of generic classes in the typing module, as well as with builtin generic classes in the recently acceptedPEP 585, because they prohibit isinstance checks.

To clarify, generic classes are not prohibited in general from participating in pattern matching, just that their type parameters can't be explicitly specified. It is still fine if sub-patterns or literals bind the type variables. For example:

from typing import Generic, TypeVar, Union

T = TypeVar('T')

class Result(Generic[T]):
    first: T
    other: list[T]

result: Union[Result[int], Result[str]]

match result:
    case Result(first=int()):
        ...  # Type of result is Result[int] here
    case Result(other=["foo", "bar", *rest]):
        ...  # Type of result is Result[str] here

The fact that name pattern is always an assignment target may create unwanted consequences when a user by mistake tries to "match" a value against a constant instead of using the constant value pattern. As a result, at runtime such match will always succeed and moreover override the value of the constant. It is important therefore that static type checkers warn about such situations. For example:

from typing import Final

MAX_INT: Final = 2 ** 64

value = 0

match value:
    case MAX_INT:  # Type-checking error here: cannot assign to final name
        print("Got big number")
    case .MAX_INT:  # This is OK
        print("Got big number")
    case _:
        print("Something else")

Precise type checking of star matches

Type checkers should perform precise type checking of star items in pattern matching giving them either a heterogeneous list[T] type, or a TypedDict type as specified byPEP 589. For example:

stuff: Tuple[int, str, str, float]

match stuff:
    case a, *b, 0.5:
        # Here a is int and b is list[str]
        ...

Don't do this, pattern matching is hard to learn

In our opinion, the proposed pattern matching is not more difficult than adding isinstance() and getattr() to iterable unpacking. Also, we believe the proposed syntax significantly improves readability for a wide range of code patterns, by allowing to express what one wants to do, rather than how to do it. We hope the few real code snippets we included in the PEP above illustrate this comparison well enough. For more real code examples and their translations see Ref..

Allow more flexible assignment targets instead

There was an idea to instead just generalize the iterable unpacking to much more general assignment targets, instead of adding a new kind of statement. This concept is known in some other languages as "irrefutable matches". We decided not to do this because inspection of real-life potential use cases showed that in vast majority of cases destructuring is related to an if condition. Also many of those are grouped in a series of exclusive choices.

Make it an expression

In most other languages pattern matching is represented by an expression, not statement. But making it an expression would be inconsistent with other syntactic choices in Python. All decision making logic is expressed almost exclusively in statements, so we decided to not deviate from this.

There were options to make match a hard keyword, or choose a different keyword. Although using a hard keyword would simplify life for simple-minded syntax highlighters, we decided not to use hard keyword for several reasons:

• Most importantly, the new parser doesn't require us to do this. Unlike with async that caused hardships with being a soft keyword for few releases, here we can make match a permanent soft keyword.
• match is so commonly used in existing code, that it would break almost every existing program and will put a burden to fix code on many people who may not even benefit from the new syntax.
• It is hard to find an alternative keyword that would not be commonly used in existing programs as an identifier, and would still clearly reflect the meaning of the statement.

Use as or | instead of case for case clauses

The pattern matching proposed here is a combination of multi-branch control flow (in line with switch in Algol-derived languages or cond in Lisp) and object-deconstruction as found in functional languages. While the proposed keyword case highlights the multi-branch aspect, alternative keywords such as as would equally be possible, highlighting the deconstruction aspect. as or with , for instance, also have the advantage of already being keywords in Python. However, since case as a keyword can only occur as a leading keyword inside a match statement, it is easy for a parser to distinguish between its use as a keyword or as a variable.

Other variants would use a symbol like | or => , or go entirely without special marker.

Since Python is a statement-oriented language in the tradition of Algol, and as each composite statement starts with an identifying keyword, case seemed to be most in line with Python's style and traditions.

Use a flat indentation scheme

There was an idea to use an alternative indentation scheme, for example where every case clause would not be indented with respect to the initial match part:

match expression:
case pattern_1:
    ...
case pattern_2:
    ...

The motivation is that although flat indentation saves some horizontal space, it may look awkward to an eye of a Python programmer, because everywhere else colon is followed by an indent. This will also complicate life for simple-minded code editors. Finally, the horizontal space issue can be alleviated by allowing "half-indent" (i.e. two spaces instead of four) for match statements.

In sample programs using match , written as part of the development of this PEP, a noticeable improvement in code brevity is observed, more than making up for the additional indentation level.

TODO: flat indentation with "match: expression" at the top.

Alternatives for constant value pattern

This is probably the trickiest item. Matching against some pre-defined constants is very common, but the dynamic nature of Python also makes it ambiguous with name patterns. Four other alternatives were considered:

• Use some implicit rules. For example if a name was defined in the global scope, then it refers to a constant, rather than represents a name pattern:

  FOO = 1
  value = 0
  
  match value:
      case FOO:  # This would not be matched
          ...
      case BAR:  # This would be matched
          ...

  This however can cause surprises and action at a distance if someone defines an unrelated coinciding name before the match statement.

• Use a rule based on the case of a name. In particular, if the name starts with a lowercase letter it would be a name pattern, while if it starts with uppercase it would refer to a constant:

  FOO = 1
  value = 0
  
  match value:
      case FOO:  # This would not be matched
          ...
      case bar:  # This would be matched
          ...

  This works well with the recommendations for naming constants fromPEP 8. The main objection is that there's no other part of core Python where the case of a name is semantically significant. (Then again a leading dot in an expression has no precedent either -- its use in import statements is quite different, since it resembles the . used to denote the current directory in filesystems.)

• Use extra parentheses to indicate lookup semantics for a given name. For example:

  FOO = 1
  value = 0
  
  match value:
      case (FOO):  # This would not be matched
          ...
      case BAR:    # This would be matched
          ...

  This may be a viable option, but it can create some visual noise if used often. Also honestly it looks pretty unusual, especially in nested contexts.

  This also has the problem that we may want or need parentheses to disambiguate grouping in patterns, e.g. in Point(x, y=(y := complex())) .

• Introduce a special symbol, for example $ or ^ to indicate that a given name is a constant to be matched against, not to be assigned to:

  FOO = 1
  value = 0
  
  match value:
      case $FOO:  # This would not be matched
          ...
      case BAR:  # This would be matched
          ...

  The problem with this approach is that introducing a new syntax for such narrow use-case is probably an overkill.

• There was also on idea to make lookup semantics the default, and require $ to be used in name patterns:

  FOO = 1
  value = 0
  
  match value:
      case FOO:  # This would not be matched
          ...
      case $BAR:  # This would be matched
          ...

  But the name patterns are more common in typical code, so having special syntax for common case would be weird.

In the end, these alternatives were rejected because of the mentioned drawbacks.

Disallow float literals in patterns

Because of the inexactness of floats, an early version of this proposal did not allow floating-point constants to be used as match patterns. Part of the justification for this prohibition is that Rust does this.

However, during implementation, it was discovered that distinguishing between float values and other types required extra code in the VM that would slow matches generally. Given that Python and Rust are very different languages with different user bases and underlying philosophies, it was felt that allowing float literals would not cause too much harm, and would be less surprising to users.

Range matching patterns

This would allow patterns such as 1...6 . However, there are a host of ambiguities:

• Is the range open, half-open, or closed? (I.e. is 6 included in the above example or not?)
• Does the range match a single number, or a range object?
• Range matching is often used for character ranges ('a'...'z') but that won't work in Python since there's no character data type, just strings.
• Range matching can be a significant performance optimization if you can pre-build a jump table, but that's not generally possible in Python due to the fact that names can be dynamically rebound.

Rather than creating a special-case syntax for ranges, it was decided that allowing custom pattern objects ( InRange(0, 6) ) would be more flexible and less ambiguous; however those ideas have been postponed for the time being (See).

Use dispatch dict semantics for matches

Implementations for classic switch statement sometimes use a pre-computed hash table instead of a chained equality comparisons to gain some performance. In the context of match statement this is technically also possible for matches against literal patterns. However, having subtly different semantics for different kinds of patterns would be too surprising for potentially modest performance win.

We can still experiment with possible performance optimizations in this direction if they will not cause semantic differences.

Use continue and break in case clauses.

Another rejected proposal was to define new meanings for continue and break inside of match , which would have the following behavior:

• continue would exit the current case clause and continue matching at the next case clause.
• break would exit the match statement.

However, there is a serious drawback to this proposal: if the match statement is nested inside of a loop, the meanings of continue and break are now changed. This may cause unexpected behavior during refactorings; also, an argument can be made that there are other means to get the same behavior (such as using guard conditions), and that in practice it's likely that the existing behavior of continue and break are far more useful.

Negative match patterns

A negation of a match pattern using the operator ! as a prefix would match exactly if the pattern itself does not match. For instance, !(3 | 4) would match anything except 3 or 4 .

This was rejected because there is documented evidencethat this feature is rarely useful (in languages which support it) or used as double negation !! to control variable scopes and prevent variable bindings (which does not apply to Python). It can also be simulated using guard conditions.

Check exhaustiveness at runtime

The question is what to do if no case clause has a matching pattern, and there is no default case. An earlier version of the proposal specified that the behavior in this case would be to throw an exception rather than silently falling through.

The arguments back and forth were many, but in the end the EIBTI (Explicit Is Better Than Implicit) argument won out: it's better to have the programmer explicitly throw an exception if that is the behavior they want.

For cases such as sealed classes and enums, where the patterns are all known to be members of a discrete set,can warn about missing patterns.

Type annotations for pattern variables

The proposal was to combine patterns with type annotations:

match x:
    case [a: int, b: str]: print(f"An int {a} and a string {b}:)
    case [a: int, b: int, c: int]: print(f"Three ints", a, b, c)
    ...

This idea has a lot of problems. For one, the colon can only be used inside of brackets or parens, otherwise the syntax becomes ambiguous. And because Python disallows isinstance() checks on generic types, type annotations containing generics will not work as expected.

Allow *rest in class patterns

It was proposed to allow *rest in a class pattern, giving a variable to be bound to all positional arguments at once (similar to its use in unpacking assignments). It would provide some symmetry with sequence patterns. But it might be confused with a feature to provide the values for all positional arguments at once. And there seems to be no practical need for it, so it was scrapped. (It could easily be added at a later stage if a need arises.)

One-off syntax variant

While inspecting some code-bases that may benefit the most from the proposed syntax, it was found that single clause matches would be used relatively often, mostly for various special-casing. In other languages this is supported in the form of one-off matches. We proposed to support such one-off matches too:

if match value as pattern [and guard]:
    ...

or, alternatively, without the if :

match value as pattern [if guard]:
    ...

as equivalent to the following expansion:

match value:
    case pattern [if guard]:
        ...

To illustrate how this will benefit readability, consider this (slightly simplified) snippet from real code:

if isinstance(node, CallExpr):
    if (isinstance(node.callee, NameExpr) and len(node.args) == 1 and
            isinstance(node.args[0], NameExpr)):
        call = node.callee.name
        arg = node.args[0].name
        ...  # Continue special-casing 'call' and 'arg'
...  # Follow with common code

This can be rewritten in a more straightforward way as:

if match node as CallExpr(callee=NameExpr(name=call), args=[NameExpr(name=arg)]):
    ...  # Continue special-casing 'call' and 'arg'
...  # Follow with common code

This one-off form would not allow elif match statements, as it was only meant to handle a single pattern case. It was intended to be special case of a match statement, not a special case of an if statement:

if match value_1 as patter_1 [and guard_1]:
    ...
elif match value_2 as pattern_2 [and guard_2]:  # Not allowed
    ...
elif match value_3 as pattern_3 [and guard_3]:  # Not allowed
    ...
else:  # Also not allowed
    ...

This would defeat the purpose of one-off matches as a complement to exhaustive full matches - it's better and clearer to use a full match in this case.

Similarly, if not match would not be allowed, since match ... as ... is not an expression. Nor do we propose a while match construct present in some languages with pattern matching, since although it may be handy, it will likely be used rarely.

Algebraic matching of repeated names

A technique occasionally seen in functional languages like Haskell is to use a match variable multiple times in the same pattern:

match value:
    case Point(x, x):
        print("Point is on a diagonal!")

The idea here is that the first appearance of x would bind the value to the name, and subsequent occurrences would verify that the incoming value was equal to the value previously bound. If the value was not equal, the match would fail.

However, there are a number of subtleties involved with mixing load-store semantics for name patterns. For the moment, we decided to make repeated use of names within the same pattern an error; we can always relax this restriction later without affecting backwards compatibility.

Note that you can use the same name more than once in alternate choices:

match value:
    case x | [x]:
        # etc.

Extended matching protocol

During the initial design discussions for this PEP, there were a lot of ideas thrown around about exotic custom matchers: IsInstance() , InRange() , RegexMatchingGroup() and so on. In fact, part of the proposal included a new Python standard library module containing a menagerie of such diverse matchers.

However, these matchers require a much more flexible and expensive custom matching protocol. In particular, it meant that the __match__ method would need to have an additional "match signature" argument which would let it know exactly what values the pattern was seeking.

Part of the argument against this more flexible protocol was that this match signature argument would be expensive to construct. Due to the dynamic nature of Python name binding, it could not be a constant, but would have to be created anew each time; and there is no guarantee that the __match__ function would even use this argument in its internal logic.

The decision to postpone this feature came with a realization that this is not a one-way door; that an extended matching protocol could be added later, using a variety of techniques (such as defining a new custom match magic method with a different name) to signal that a class wished to opt-in in the extended protocol and that the VM should compute the extended signature object.

The authors of this PEP expect that the match statement will evolve over time as usage patterns and idioms evolve, in a way similar to what other "multi-stage" PEPs have done in the past. When this happens, the extended matching issue can be revisited.

There was an idea to send partial context like literals only, or custom pattern objects that will provide the full context. For example the below match would generate the following call:

match expr:
    case BinaryOp(left=Number(value=x), op=op, right=Number(value=y)):
        ...

from types import PatternObject
BinaryOp.__match__(
    (),
    {
        "left": PatternObject(Number, (), {"value": ...}, -1, False),
        "op": ...,
        "right": PatternObject(Number, (), {"value": ...}, -1, False),
    },
    -1,
    False,
)

This would allow faster __match__() implementations and give better support for customization in user-defined classes. There is however a big downside to this: it would make the basic implementation of this method quite complicated. Also, there would be a performance penalty if the user did not treat the pattern object properly.

Parameterized Matching Syntax

(Also known as "Class Instance Matchers".)

This is another variant of the "custom match classes" idea that would allow diverse kinds of custom matchers mentioned in the previous section -- however, instead of using an extended matching protocol, it would be achieved by introducing an additional pattern type with its own syntax. This pattern type would accept two distinct sets of parameters: one set which consists of the actual parameters passed into the pattern object's constructor, and another set representing the binding variables for the pattern.

The __match__ method of these objects could use the constructor parameter values in deciding what was a valid match.

This would allow patterns such as InRange<0, 6>(value) , which would match a number in the range 0..6 and assign the matched value to 'value'. Similarly, one could have a pattern which tests for the existence of a named group in a regular expression match result (different meaning of the word 'match').

Although there is some support for this idea, there was a lot of bikeshedding on the syntax (there are not a lot of attractive options available) and no clear consensus was reached, so it was decided that for now, this feature is not essential to the PEP.

Pattern Utility Library

Both of the previous ideas would be accompanied by a new Python standard library module which would contain a rich set of exotic and useful matchers. However, it it not really possible to implement such a library without adopting one of the extended pattern proposals given in the previous sections, so this idea is also deferred.