Structural Pattern Matching in Python

What Is Pattern Matching?

You can think of pattern matching as a form of syntactic sugar built on top of existing language constructs, including conditional statements and tuple unpacking. While you can absolutely live without pattern matching, it gives you new superpowers, making this feature more convenient than the conventional syntax in some situations.

Pattern matching often leads to more elegant, concise, and readable code written in a declarative style. To get a taste of it, take a quick look at the following example without trying to fully understand how it works just yet:

import json

def log(event):
    match json.loads(event):
        case {"keyboard": {"key": {"code": code}}}:
            print(f"Key pressed: {code}")
        case {"mouse": {"cursor": {"screen": [x, y]}}}:
            print(f"Mouse cursor: {x=}, {y=}")
        case _:
            print("Unknown event type")

The match statement takes a subject, which can be any valid Python expression, such as a string literal or a function call, and compares the resulting value to one or more patterns listed in the case clauses. The first pattern that matches the given subject will trigger the corresponding case block to run. You’ll learn more about the match statement and case clauses later in this tutorial.

At first glance, the syntax of structural pattern matching in Python looks a bit like the switch statement found in the C-family programming languages if you squint your eyes:

void log_event(enum Event event) {
    switch (event) {
        case KEYBOARD:
            printf("Keyboard event\n");
            break;
        case MOUSE:
            printf("Mouse event\n");
            break;
        default:
            printf("Unknown event\n");
    }
}

This resemblance is deceptive, though. The classic switch statement controls the execution flow based on the exact value stored in a variable. It effectively works as a chained sequence of mutually exclusive if..elif... equality comparisons, but with a more succinct and readable syntax.

Although you can use pattern matching this way, you’d be missing out on its true power and flexibility. Structural pattern matching was designed to go beyond value comparisons. In particular, it combines conditional statements or branching based on a logical predicate with destructuring or object deconstruction, which is the inverse of object construction. You’ll see examples of destructuring in the next section.

The brief code snippet above merely scratches the surface of what you can achieve with pattern matching, but it already shows you its expressiveness, especially when you compare it with the traditional if...elif... statements and isinstance() checks. Here’s one of the many ways you can implement the equivalent logic using standard Python:

import json

def log(event):
    parsed_event = json.loads(event)
    if (
        "keyboard" in parsed_event and
        "key" in parsed_event["keyboard"] and
        "code" in parsed_event["keyboard"]["key"]
    ):
        code = parsed_event["keyboard"]["key"]["code"]
        print(f"Key pressed: {code}")
    elif (
        "mouse" in parsed_event and
        "cursor" in parsed_event["mouse"] and
        "screen" in parsed_event["mouse"]["cursor"]
    ):
        screen = parsed_event["mouse"]["cursor"]["screen"]
        if isinstance(screen, list) and len(screen) == 2:
            x, y = screen
            print(f"Mouse cursor: x={x}, y={y}")
        else:
            print("Unknown event type")
    else:
        print("Unknown event type")

This code is functionally identical to the previous version but is longer and has more indentation levels than before. Additionally, it looks more verbose and imperative in style, describing not only what to do but also how to perform the individual steps. Granted, you could try making it slightly shorter by using the Walrus operator and following the EAFP principle without explicit checks, but it’d remain somewhat convoluted.

It’s worth noting that structural pattern matching first emerged in compiled functional languages with static typing. The attempt to implement it in Python, which is a dynamic language, presented completely new and unique challenges. You can read more about them in the paper entitled Dynamic Pattern Matching with Python, which was co-authored by Guido van Rossum and published in the proceedings of the Dynamic Languages Symposium in 2020.

Now that you’ve seen the most basic form of pattern matching in Python, it’s time to unravel the meaning of a structural pattern.

What Is a Structural Pattern?

Python supports several types of structural patterns, which you’ll explore in detail throughout this tutorial. Each pattern describes the structure of an object to match, including its type, shape, value, and identity. It can also specify the individual pieces of which an object is made. For example, you may want to define a pattern that will match three-dimensional points that lie on the z-axis:

match subject:
    case list([int() | float() as x, int() | float() as y, 0]):
        print(f"Point({x=}, {y=})")

The pattern defined in the case clause above will match a numeric list of size three whose last element is equal to zero. This concise pattern matching encapsulates the same logic as the following much longer code snippet:

if isinstance(subject, list) and len(subject) == 3:
    if (
        isinstance(subject[0], int | float) and
        isinstance(subject[1], int | float) and
        subject[2] == 0
    ):
        x, y, _ = subject
        print(f"Point({x=}, {y=})")

As you can see, structural patterns let you express intricate conditional logic clearly and precisely. Their second but equally important trait is selective data extraction from complex data structures. In this case, your pattern unpacks the first two values from the matched list and binds them to the x and y variables.

A common point of confusion about structural patterns is that they look familiar to most Python programmers but mean something completely different in the context of pattern matching. A pattern is not your typical expression. Although it looks like an object literal or a class constructor, it doesn’t actually instantiate a new object. Here’s an example leveraging a data class to illustrate this:

>>> from dataclasses import dataclass

>>> @dataclass
... class User:
...     name: str
...
...     def __post_init__(self):
...         print(f"Created a new user named {self.name}")
...
>>> match User("Alice"):
...     case User("Bob"):
...         pass
...
Created a new user named Alice

The User("Alice") expression in the match statement does indeed create a new User instance, but a similarly looking User("Bob") pattern in the case clause doesn’t. Whether a piece of code becomes an expression or a structural pattern depends on where you put it. In particular, whatever follows a case clause is always interpreted as a pattern.

Patterns represent a relatively little-known concept in Python: object deconstruction or destructuring, which means pulling apart structured data. Before Python 3.10, you had only a handful of ways to deconstruct compound objects like sequences and mappings, such as these:

Structural patterns extend this idea by adding a few more destructuring techniques to the list, albeit strictly in the context of pattern matching. This is different from some other programming languages, which allow you to destructure objects without conditional matching.

If you’ve ever dipped your toes into JavaScript, then you’re probably familiar with destructuring assignments, which can streamline the extraction of values from arbitrary objects:

function sayHello({ name, age }) {
    console.log(`My name's ${name}, and I'm ${age} years old.`);
}

sayHello(new Person("Alice", 42, "New York", "Software Engineer"))

In this example, you extract the values corresponding to the .name and .age attributes of a user-defined Person type. Later, you’ll learn how to take advantage of similar patterns in Python.

Upon closer inspection, a structural pattern is the opposite of object construction. It’s the “left side” of the assignment statement, conceptually similar to tuple unpacking:

>>> a, b, c = range(3)
>>> print(f"Point({a=}, {b=}, {c=})")
Point(a=0, b=1, c=2)

>>> match range(3):
...     case x, y, z:
...         print(f"Point({x=}, {y=}, {z=})")
...
Point(x=0, y=1, z=2)

The a, b, and c variables in the code snippet above appear to the left of the assignment operator (=), making them the target of that assignment. The x, y, and z variables in the case clause serve a similar purpose, acting as placeholders for values matched from the subject.

However, there’s a subtle difference. Unpacking is unconditional, meaning that it can fail, whereas pattern matching is conditional, so it’ll only run if the pattern matches the subject. Consider the following example:

>>> a, b, c = range(2)
Traceback (most recent call last):
  ...
ValueError: not enough values to unpack (expected 3, got 2)

>>> match range(2):
...     case x, y, z:
...         print(f"Point({x=}, {y=}, {z=})")
...

The unpacking operation fails with an error this time because there aren’t enough values to assign to the variables. The range() function generates only two numbers, while the unpacking expects three values, resulting in a ValueError. An attempt to destructure the same object into too many variables never runs because the corresponding pattern doesn’t succeed, letting your program continue without interruption.

At this point, you should have a rough idea of how structural pattern matching works. But, if you’re new to this concept, then it still might not be entirely clear how to apply pattern matching in the wild and what use cases it fits best.

When to Use Structural Pattern Matching?

The answer to when to use pattern matching is right there in its name: structural pattern matching. In short, you should use pattern matching when you want to make a decision based on the structure of complex data and possibly destructure it at the same time. This approach can help you adopt a more declarative coding style, which is especially beneficial if you’re following the functional programming paradigm:

from pathlib import Path
from urllib.request import urlretrieve

def fetch(resource):
    match resource:
        case {"protocol": "http" | "ftp", "full_url": url}:
            match urlretrieve(url):
                case file_path, _:
                    return Path(file_path).read_text("utf-8")
        case _:
            raise ValueError("Unsupported protocol")

Although not purely functional in style, this example leverages two match statements nested one in another to handle different types of resources based on their structure. If the first resource is a Python dictionary with a "protocol" key equal to either "http" or "ftp" and has a "full_url" key, then you retrieve the file from that URL. Upon successful retrieval, you read and return the content of the resulting temporary file.

In contrast, if you’re making a decision based on complex business rules that require a lot of computation, especially if the conditions are non-exclusive or incremental, then you may be better off choosing a different language construct. There are some well-established and usually more appropriate idioms in Python for such scenarios, like a chain of if...elif... statements:

def get_shipping_cost(order):
    if (
        order.priority is Priority.STANDARD and
        order.domestic and
        any(order.shipping_address.close_to(x) for x in WAREHOUSES)
    ):
        cost = 5 if order.weight <= MAX_WEIGHT_SMALL_PACKAGE else 10
    elif (
        order.priority is Priority.STANDARD and
        order.international
    ):
        cost = 20 if order.weight <= MAX_WEIGHT_SMALL_PACKAGE else 40
    # ...
    else:
        raise ValueError("Invalid order")

    if not order.shipping_address.country.is_vat_exempt:
        cost *= order.shipping_address.country.vat_rate

    return cost

This function calculates the shipping cost based on several factors, including the order’s priority, whether it’s domestic or international, the delivery distance, and the weight of the package. It also adjusts the cost based on the VAT rate of the destination country if it applies. Codifying this logic with pattern matching would prove cumbersome.

As a rule of thumb, try to avoid using pattern matching as a switch statement replacement. A popular method to emulate the switch statement in Python involves a dictionary-based jump table, which you can use to implement dynamic dispatch:

from operator import add, sub, mul, truediv as div

def apply(operator, left, right):
    return {
        "+": add,
        "-": sub,
        "*": mul,
        "/": div,
    }.get(operator, lambda *args: None)(left, right)

Here, you use a Python dictionary to map string representations of binary operators to their corresponding functions from the operator module. If the provided operator isn’t defined in the dictionary, then you default to a lambda expression that always returns None. This method lets you extend the dictionary with additional operators if necessary.

By the end of this tutorial, you’ll have discovered numerous practical use cases for pattern matching through concrete examples. Some of them include parsing deeply nested hierarchical data like JSON, processing user input, or traversing recursive data structures, such as abstract syntax trees (AST). But, before diving into these examples, you should first have a better understanding of the syntax and semantics of pattern matching.

Soft Keywords in Python 3.10 and Later

To facilitate the use of pattern matching in Python, the interpreter itself had to undergo significant changes. Python 3.9 introduced the concept of soft keywords, and Python 3.10 delivered their first implementation. Standard keywords like with or return are reserved, meaning that you can’t use them as identifiers for your variables, functions, and other elements in your code. As soon as you try, you’ll encounter a syntax error:

>>> ticket.class = "business"
  File "<input>", line 1
    ticket.class = "business"
           ^^^^^
SyntaxError: invalid syntax

In this case, .class isn’t allowed as an attribute name because it’s a keyword reserved for defining Python classes only. To circumvent this limitation, you can rename the attribute by appending a trailing underscore (_), which is a common practice in Python.

On the other hand, soft keywords are contextual. They act as keywords only in specific contexts. This new capability was made possible thanks to the introduction of the PEG parser in Python 3.9, which changed how the interpreter reads the source code. For instance, since Python 3.12, type becomes a keyword when you use it as a type alias definition, but it behaves as a regular identifier everywhere else:

>>> type String = str

>>> type(42)
<class 'int'>

>>> Blood = type("Blood", (), {
...         "__init__": lambda self, group: setattr(self, "group", group),
...         "__repr__": lambda self: f"Blood(group={self.group!r})",
...     },
... )

>>> type = Blood("AB+")

Although type() also happens to be a built-in function, which you can use for type checking or making new data types at runtime, it’s technically a valid identifier for user-defined symbols as well.

This lenient naming policy allows new keywords to be added into the language without breaking existing code. Back in Python 3.5, when async def syntax (PEP 492) was introduced, the language tokenizer had to be modified to treat async and await as keywords only in certain contexts. This ensured backward compatibility with legacy code that used these common words as identifiers, like so:

from concurrent.futures import ThreadPoolExecutor
import requests

executor = ThreadPoolExecutor()

def fetch(urls, async=True):
    if async:
        return [executor.submit(requests.get, url) for url in urls]
    else:
        return [requests.get(url) for url in urls]

When the async parameter is equal to True, this function returns immediately with a list of future objects that you can await by calling as_completed(). Otherwise, the function works synchronously by blocking the current thread of execution until all requests are completed.

The change in Python’s tokenizer was a one-time workaround to allow for an interim deprecation period before async and await finally became reserved keywords in Python 3.7. This resulted in making the above code syntactically incorrect going forward.

The idea behind soft keywords aims to achieve similar benefits without resorting to dirty hacks. The authors of pattern matching in Python picked the match keyword because it was widely used for that purpose in many other programming languages.

Unfortunately, the standard-library module for regular expressions already contained a function named match(), which wouldn’t be allowed anymore, necessitating breaking changes. Additionally, it’s become idiomatic to assign the result of re.match() to a variable called match. This is a common pattern, so making match a hard keyword would cause widespread disruption in existing codebases. So, it was decided to make match a soft keyword instead.

With soft keywords in place, you can reuse the same name more than once on a single line of code without ambiguity. Depending on the color theme of your choice, most IDEs and code editors should display each instance of match using distinct colors to differentiate their meaning:

The screenshot above depicts a fragment of code in PyCharm with the Xcode Light theme selected. The first occurrence of match is in purple to indicate it’s a keyword, followed by a match variable in black, and a match function call in teal. You can expand the collapsible section below to reveal the code snippet in text format:

from re import match

match match := match(r"([^@]+)@.*", "alice@email.com").group(1):
    case "alice":
        print("Welcome, Alice!")
    case "bob":
        print("Welcome, Bob!")
    case _:
        print("Welcome, stranger!")

Although this is perfectly valid Python, it might look confusing even to those familiar with the nuances of pattern matching, regular expressions, and the Walrus operator. In general, you should find ways to avoid such “clever” code.

If you’re unsure whether a particular word is a reserved keyword in your current Python version, then you can always check by using the standard-library keyword module:

>>> import keyword

>>> keyword.iskeyword("match")
False

>>> keyword.issoftkeyword("match")
True

>>> keyword.kwlist
['False', 'None', ..., 'while', 'with', 'yield']

>>> keyword.softkwlist
['_', 'case', 'match', 'type']

As of Python 3.12, there are thirty-five reserved keywords and only four soft keywords in Python, three of which are related to pattern matching. The underscore character (_) is one of them.

The underscore is a valid identifier that has had many conventional meanings in Python, including:

• Unused variables that linters should ignore without complaining
• Throwaway variables in loops and other constructs
• The last evaluated expression in a Python REPL
• Alias of the multilingual translation function like gettext()

Now, it’s adopted yet another meaning. In the context of pattern matching, an underscore represents the wildcard pattern typically used as a default catch-all case. The other two keywords associated with pattern matching are match and case, which you’ll learn about next.

Match Statement and Case Clauses

Imagine you wanted to build a bare-bones Python REPL, which takes user input and interprets the entered line of code. Pattern matching is the perfect tool for such a task. To keep things simple, you’ll only allow statements that can fit on a single line. However, for a more complete solution that offers multiline code block support, scroll down and expand the collapsible section at the end of the next section.

Okay. Define your first match statement followed by an expression, which is called the subject value, and a colon (:) to start a new block of code:

PROMPT = "\N{snake} "

match input(PROMPT):

In this case, you call the built-in input() function with the snake emoji prompt represented as a Unicode escape sequence. The value returned from the function is your subject.

match subject := input(PROMPT):

The body of the match statement can only consist of a non-empty sequence of case clauses. You’re not allowed to use any other types of statements inside the match code block. That includes the pass statement and the ellipsis literal (...). Furthermore, you must place at least one case clause followed by a structural pattern and a colon, which starts another nested block of code:

import sys

PROMPT = "\N{snake} "

match input(PROMPT):
    case "help":
        message = f"Python {sys.version}"
        print(message)

Here, you use a literal pattern, which matches the exact string "help". If the user types the help command at the prompt, then you display a message indicating their current Python version in response:

$ python repl.py
🐍 help
Python 3.12.4 (main, Jun 10 2024, 12:47:23) [GCC 13.2.0]

More often than not, you’ll collapse each block belonging to a case clause into a single line of code while calling some function to delegate the execution:

import sys

PROMPT = "\N{snake} "

match input(PROMPT):
    case "help":
        print(f"Python {sys.version}")

This practice can make your code look more concise and easier to follow.

Note that you’re not restricted to the global scope when it comes to using pattern matching. You can declare the match statement anywhere in your code, for example, within a nested code block in a function:

import sys
import traceback

PROMPT = "\N{snake} "

def main():
    while True:
        try:
            match input(PROMPT):
                case "help":
                    print(f"Python {sys.version}")
        except:
            traceback.print_exc(file=sys.stdout)

if __name__ == "__main__":
    main()

The code above follows the name-main idiom by calling the main() function at the bottom of the file. This function runs an infinite loop, which continuously prompts the user for input without the possibility to gracefully terminate the program, not even by raising an exception.

To let the user break out of the loop, you must handle another command, such as exit or quit. You should also avoid a bare except: clause to allow the built-in system exceptions to propagate:

import sys
import traceback

PROMPT = "\N{snake} "

def main():
    print('Type "help" for more information, "exit" or "quit" to finish.')
    while True:
        try:
            match input(PROMPT):
                case "help":
                    print(f"Python {sys.version}")
                case "exit" | "quit":
                    break
        except Exception:
            traceback.print_exc(file=sys.stdout)

if __name__ == "__main__":
    main()

You use the vertical bar (|) to combine two subpatterns into a union, which is a neat way to avoid code duplication. By having Python match one of the alternatives, you reuse a code block common to multiple patterns. In this case, they’re both literal patterns.

Now, you have a basic program that your users can interact with. It’ll continue running until the user types either exit or quit:

$ python repl.py
Type "help" for more information, "exit" or "quit" to finish.
🐍 help
Python 3.12.4 (main, Jun 10 2024, 12:47:23) [GCC 13.2.0]
🐍 EXIT
🐍 exit

Notice, however, that your commands are case-sensitive. If the user types EXIT instead of exit, then nothing happens. One way to address this issue is by having a cascade of nested match statements:

import sys
import traceback

PROMPT = "\N{snake} "
COMMANDS = ("help", "exit", "quit")

def main():
    print('Type "help" for more information, "exit" or "quit" to finish.')
    while True:
        try:
            match input(PROMPT):
                case command if command.lower() in COMMANDS:
                    match command.lower():
                        case "help":
                            print(f"Python {sys.version}")
                        case "exit" | "quit":
                            break
        except Exception:
            traceback.print_exc(file=sys.stdout)

if __name__ == "__main__":
    main()

The outer match statement has only one case clause, which matches a string as long as it’s in the list of recognized commands. On the other hand, the subject of the inner match statement is the matched command converted to lowercase so that you can handle input regardless of its original casing. The if statement after the pattern is an optional guard, which you’ll take a closer look at later.

The default Python REPL intercepts the KeyboardInterrupt exception raised in response to pressing Ctrl+C. Additionally, it lets you quickly close the current session by pressing Ctrl+D, which sends the end-of-file (EOF) control character. You can handle both situations as shown below:

import sys
import traceback

PROMPT = "\N{snake} "
COMMANDS = ("help", "exit", "quit")

def main():
    print('Type "help" for more information, "exit" or "quit" to finish.')
    while True:
        try:
            match input(PROMPT):
                case command if command.lower() in COMMANDS:
                    match command.lower():
                        case "help":
                            print(f"Python {sys.version}")
                        case "exit" | "quit":
                            break
        except KeyboardInterrupt:
            print("\nKeyboardInterrupt")
        except EOFError:
            print()
            exit()
        except Exception:
            traceback.print_exc(file=sys.stdout)

if __name__ == "__main__":
    main()

Okay. Your script is slowly shaping up into a decent Python REPL. But, since you haven’t executed any Python code yet, it’s time to fix that now. Along the way, you’ll learn how Python chooses a case clause to execute for a given subject.

Precedence of Structural Patterns

So far, you’ve mainly encountered mutually exclusive patterns that correspond to disjoint sets of subject values. As a result, you were free to arrange these patterns in any order without causing ambiguity in the matching process. However, Python also allows you to specify overlapping patterns that will simultaneously match the same subject. That’s where order starts to matter, as it can change the behavior of your program if you’re not careful.

Go ahead and add another case clause to your outer match statement, which will execute a Python statement:

import ast
import sys
import traceback

PROMPT = "\N{snake} "
COMMANDS = ("help", "exit", "quit")

def main():
    print('Type "help" for more information, "exit" or "quit" to finish.')
    while True:
        try:
            match input(PROMPT):
                case command if command.lower() in COMMANDS:
                    match command.lower():
                        case "help":
                            print(f"Python {sys.version}")
                        case "exit" | "quit":
                            break
                case statement if valid(statement):
                    exec(statement)
        except KeyboardInterrupt:
            print("\nKeyboardInterrupt")
        except EOFError:
            print()
            exit()
        except Exception:
            traceback.print_exc(file=sys.stdout)

def valid(code):
    try:
        ast.parse(code)
        return True
    except SyntaxError:
        return False

if __name__ == "__main__":
    main()

If the user input doesn’t match one of your predefined commands, then you assume it might represent a line of Python code. To be sure, you define a capture pattern, which binds the entered value to a variable named statement. Next, you pass that statement to a helper function called valid(), which you defined below, right after the main() function.

This function uses the ast module to parse the source code and determine if it’s valid. Finally, you call exec() to execute the provided code snippet upon a successful match.

When you give your REPL another spin, this is what you’ll get:

$ python repl.py
Type "help" for more information, "exit" or "quit" to finish.
🐍 print("Hello, World!")
Hello, World!
🐍 name = "John Doe"
🐍 print(f"My name's {name}.")
My name's John Doe.
🐍 2 + 2
🐍 exit

When you call the print() function, it works as expected, writing the provided Hello, World! text to the standard output stream. Similarly, defining a variable seems to be working fine, as you can retrieve its current value with an f-string literal. At the same time, the result of the arithmetic addition, two plus two, is nowhere to be seen. Can you guess why?

It’s because exec() doesn’t return any value. Although your code gets executed under the curtain, it has no visible side effects. Such code represents a special kind of statement known as an expression, which you can evaluate using the built-in eval() function. Unlike exec(), this function returns the evaluated object, which you can process further.

Because expressions are also statements, but not the other way around, you can’t append another case clause with a suitable pattern after the existing case that is meant for handling statements. If you did, the first pattern would always succeed regardless of whether the subject is a statement or an expression, preventing the subsequent cases from running. Therefore, you must place the case clause for expressions before the case clause for statements.

In addition to this, you have to modify your helper function so that it can discern between statements and expressions:

import ast
import sys
import traceback

PROMPT = "\N{snake} "
COMMANDS = ("help", "exit", "quit")

def main():
    print('Type "help" for more information, "exit" or "quit" to finish.')
    while True:
        try:
            match input(PROMPT):
                case command if command.lower() in COMMANDS:
                    match command.lower():
                        case "help":
                            print(f"Python {sys.version}")
                        case "exit" | "quit":
                            break
                case expression if valid(expression, "eval"):
                    _ = eval(expression)
                    if _ is not None:
                        print(_)
                case statement if valid(statement, "exec"):
                    exec(statement)
        except KeyboardInterrupt:
            print("\nKeyboardInterrupt")
        except EOFError:
            print()
            exit()
        except Exception:
            traceback.print_exc(file=sys.stdout)

def valid(code, mode):
    try:
        ast.parse(code, mode=mode)
        return True
    except SyntaxError:
        return False

if __name__ == "__main__":
    main()

The extra parameter, which you now must pass explicitly to your valid() function, lets you parse the code in either the "exec" or "eval" mode:

The mode argument specifies what kind of code must be compiled; it can be 'exec' if source consists of a sequence of statements, 'eval' if it consists of a single expression, […] (Source)

Also notice that you assign the result of eval() to an underscore (_) variable, which you print only when the associated expression evaluates to anything other than None. This is consistent with the standard REPL, which automatically stores the last evaluated expression in a special variable for your convenience:

$ python repl.py
Type "help" for more information, "exit" or "quit" to finish.
🐍 print(None)
None
🐍 (lambda: None)()
🐍 2 + 2
4
🐍 _ * 2
8
🐍 _ * 2
16

You can still execute statements as before, like calling the print() function, as well as evaluate expressions. If an expression evaluates to None, such as the lambda expression above, then you don’t show it. Additionally, the special variable (_) allows you to reuse the value of the last expression.

It was briefly mentioned before that the underscore is a soft keyword, which plays a role in pattern matching. Now, it’s time to delve deeper into its use.

Default Case and the Wildcard Pattern

Unlike many other programming languages, Python allows the case clauses in pattern matching to remain non-exhaustive. In other words, you don’t have to handle all possible cases in a match statement. It’s up to you whether you want to catch unmatched patterns in a default case or not. For example, if a user of your custom REPL types an unknown command that isn’t a valid statement or expression, then nothing gets executed:

$ python repl.py
Type "help" for more information, "exit" or "quit" to finish.
🐍 This is not a known command or valid Python.
🐍 exit

The REPL ignores syntactically incorrect Python and moves on because none of the patterns in your case clauses matches the subject. However, it’d be more considerate to the user to let them know about a syntax error in their input.

For this purpose, you can specify the catch-all case by using a wildcard pattern (_) that will always match unless one of your earlier patterns already matched the subject. Because it serves the purpose of a fallback case, it has to go last in the sequence of case clauses:

# ...

def main():
    print('Type "help" for more information, "exit" or "quit" to finish.')
    while True:
        try:
            match input(PROMPT):
                case command if command.lower() in COMMANDS:
                    match command.lower():
                        case "help":
                            print(f"Python {sys.version}")
                        case "exit" | "quit":
                            break
                case expression if valid(expression, "eval"):
                    _ = eval(expression)
                    if _ is not None:
                        print(_)
                case statement if valid(statement, "exec"):
                    exec(statement)
                case _:
                    print("Please type a command or valid Python")
        except KeyboardInterrupt:
            print("\nKeyboardInterrupt")
        except EOFError:
            print()
            exit()
        except Exception:
            traceback.print_exc(file=sys.stdout)

# ...

With this small change, you made your pattern matching exhaustive. In other words, you now cover all possible cases, even if there are infinitely many. This guarantees that at least one of the clauses will run, irrespective of the subject.

Remember that the underscore (_) behaves like a keyword within a structural pattern. Therefore, it never binds the subject to a name, so you won’t be able to refer to it inside or outside the respective case clause. That’s good news because the wildcard pattern won’t collide with your special variable bearing the same name, which your REPL manages.

Furthermore, because of the lack of name binding in the wildcard pattern, you can reuse the underscore several times as a subpattern to discard certain elements of other patterns. Take a look at this hypothetical example:

for user in fetch_users():
    match user:
        case User(_, _, age) if age < 18:
            print(f"Underage: {user}")
        case User(_, "Smith", _):
            print(f"Smith family member: {user}")

Here, the underscores are another incarnation of the wildcard pattern. As you can see, the wildcard pattern doesn’t always have to appear in the default catch-all case at the end of a match statement. Instead, it tells Python to ignore specific values without binding them to any variable while letting you reuse the underscore. That isn’t the case with regular capture patterns, which don’t allow repeated variables in their definition.

Alright. That wraps up this example. If you’d like to improve your Python REPL, then consider adding support for multiline code blocks. You can also integrate readline-like editing capabilities, command history, and contextual autocomplete triggered by pressing the Tab key. Below, you’ll find a sample implementation of these features:

import ast
import atexit
import readline
import rlcompleter
import sys
import traceback
from dataclasses import dataclass, field
from pathlib import Path
from typing import Literal

STANDARD_PROMPT = ">>> "
INDENTED_PROMPT = "... "
TAB_WIDTH = 4
TAB = TAB_WIDTH * " "
COMMANDS = ("help", "exit", "quit")
PYTHON_HISTORY = Path.home() / ".python_history"

@dataclass
class Console:
    indentation_level: int = 0

    def __post_init__(self) -> None:
        readline.parse_and_bind("tab: complete")
        readline.set_completer(rlcompleter.Completer().complete)
        if PYTHON_HISTORY.exists():
            readline.read_history_file(PYTHON_HISTORY)
        atexit.register(readline.write_history_file, PYTHON_HISTORY)

    @property
    def prompt(self) -> str:
        if self.indentation_level > 0:
            return INDENTED_PROMPT
        else:
            return STANDARD_PROMPT

    @property
    def indentation(self) -> str:
        return TAB * self.indentation_level

    def indent(self) -> None:
        self.indentation_level += 1

    def dedent(self) -> None:
        if self.indentation_level > 0:
            self.indentation_level -= 1

    def reindent(self, line: str) -> None:
        num_leading_spaces = len(line) - len(line.lstrip())
        new_indentation_level = num_leading_spaces // TAB_WIDTH
        if new_indentation_level < self.indentation_level:
            self.indentation_level = new_indentation_level

    def input(self) -> str:
        def hook():
            readline.insert_text(self.indentation)
            readline.redisplay()

        try:
            readline.set_pre_input_hook(hook)
            result = input(self.prompt)
            return result
        finally:
            readline.set_pre_input_hook()

@dataclass
class CodeBlock:
    lines: list[str] = field(default_factory=list)

    def execute(self) -> None:
        exec("\n".join(self.lines), globals())
        self.lines = []

def main() -> None:
    print('Type "help" for more information, "exit" or "quit" to finish.')
    console = Console()
    block = CodeBlock()
    while True:
        try:
            match console.input():
                case command if command.lower() in COMMANDS:
                    match command.lower():
                        case "help":
                            print(f"Python {sys.version}")
                        case "exit" | "quit":
                            break
                case line if line.endswith(":"):
                    block.lines.append(line)
                    console.reindent(line)
                    console.indent()
                case line if line.lstrip() == "":
                    console.reindent(line)
                    console.dedent()
                    if console.indentation_level == 0 and block.lines:
                        block.execute()
                case line if console.indentation_level > 0:
                    block.lines.append(line)
                case expression if valid(expression, "eval"):
                    _ = eval(expression)
                    if _ is not None:
                        print(_)
                case statement if valid(statement, "exec"):
                    exec(statement)
                case _:
                    print("Please type a command or valid Python")
        except KeyboardInterrupt:
            print("\nKeyboardInterrupt")
            console.indentation_level = 0
            block.lines = []
        except EOFError:
            print()
            sys.exit()
        except Exception:
            traceback.print_exc(file=sys.stdout)
            console.indentation_level = 0
            block.lines = []

def valid(code: str, mode: Literal["eval", "exec"]) -> bool:
    try:
        ast.parse(code, mode=mode)
        return True
    except SyntaxError:
        return False

if __name__ == "__main__":
    main()

Now you’re ready to dive deeper into various types of structural patterns in Python. You’ll start by taking a look at some basic patterns to whet your appetite.

Literal Pattern

The first type of structural pattern that you’ll look at is the literal pattern, which is arguably the most straightforward of them all. It generally lets you restrict the value of the subject instead of its type or structure. Consequently, literal patterns alone can be suitable for emulating the switch statement in Python if you don’t mind deviating from earlier recommendations.

For example, here’s a sample implementation of a custom interpreter of a certain esoteric programming language, which is based on literal patterns:

>>> import sys

>>> def interpret(code, num_bytes=2**10):
...     stack, brackets = [], {}
...     for i, instruction in enumerate(code):
...         match instruction:
...             case "[": stack.append(i)
...             case "]": brackets[i], brackets[j] = (j := stack.pop()), i
...     memory = bytearray(num_bytes)
...     pointer = ip = 0
...     while ip < len(code):
...         match code[ip]:
...             case ">": pointer += 1
...             case "<": pointer -= 1
...             case "+": memory[pointer] += 1
...             case "-": memory[pointer] -= 1
...             case ".": print(chr(memory[pointer]), end="")
...             case ",": memory[pointer] = ord(sys.stdin.buffer.read(1))
...             case "[" if memory[pointer] == 0: ip = brackets[ip]
...             case "]" if memory[pointer] != 0: ip = brackets[ip]
...         ip += 1
...
>>> interpret("""
...   +++++++++++[>++++++>+++++++++>++++++++>++++>+++>+<<<<<<-]>+++
...   +++.>++.+++++++..+++.>>.>-.<<-.<.+++.------.--------.>>>+.>-.
... """)
Hello, World!

All patterns in both match statements are analogous to string literals that correspond to different instructions, such as moving the pointer to the next memory cell (">") in this particular programming language. Python compares the subject against each of your patterns to determine which branch of code to execute. The subject must match a given pattern exactly to make it succeed.

Strings aren’t the only literals you can use in this kind of structural pattern. Python supports a few more data types, including numbers and Boolean values. Here’s a more detailed breakdown of the available literal patterns:

These are the only data types with corresponding literal patterns in Python. The counterparts of other kinds of literals, such as the list literal, are considered separate types of patterns, which you’ll get familiar with soon.

Notice that f-strings are missing from the list because they don’t represent exact values known upfront. Instead, f-strings typically involve string interpolation, which must be done at runtime. So, when you try to make a literal pattern out of an f-string, you’ll encounter a syntax error:

>>> command = "read"
>>> match input("Type the command: "):
...     case f"help {command}":
...         print("Showing help on the 'read' command")
...
  File "<stdin>", line 2
SyntaxError: patterns may only match literals and attribute lookups

Fortunately, this isn’t an issue, as you’ll discover other types of structural patterns that can fill this gap.

When you look closely at the table above, you’ll notice a slight inconsistency. While most literal patterns use the equality test operator (==) to compare the values of the subject and the pattern, there are a few notable exceptions. In particular, the three singletons, True, False, and None, use identity comparison (is) instead of value comparison to avoid surprising behavior, which could lead to subtle defects.

When you compare objects by value in Python, their data types are sometimes ignored. Take the following as an example:

>>> 1 == "1"
False

>>> 1 == 1.0 == 1.0 + 0.0j == True
True

In the first case, you’re trying to compare a number to a string, which fails because both objects have drastically different internal representations. However, in the second case, you’re dealing with four objects of compatible types that share the same value. For instance, even though the internal representation of a complex number, such as 1.0 + 0.0j, is different than that of an integer 1, they contain the same numeric value.

As a result of that, literal patterns may succeed even if they aren’t exactly of the same type as the subject:

>>> def is_adult(age):
...     match age:
...         case 18:
...             return True
...         case _:
...             return False
...
>>> is_adult(18)
True
>>> is_adult(18.0)
True
>>> is_adult(18.0 + 0.0j)
True

This function takes an age as an argument and checks if it’s eighteen, returning True if it is and False otherwise. Notice how calling the function with different numeric types still results in a match.

If you want to ensure strict type checking, then use a class pattern by explicitly wrapping your literal pattern in a relevant type constructor:

>>> def is_adult(age):
...     match age:
...         case int(18):
...             return True
...         case _:
...             return False
...
>>> is_adult(18)
True
>>> is_adult(18.0)
False
>>> is_adult(18.0 + 0.0j)
False

Now, only an integer matches the structural pattern even though the other two numbers carry the same value.

It could be argued that comparing numbers by value is a sensible thing to do. On the other hand, with True and 1 being considered equal in Python, this could lead to unexpected results. Therefore, literal patterns True, False, and None always compare the subject by identity:

>>> def get_http_status(is_admin):
...     match is_admin:
...         case True:
...             return "200 OK"
...         case False:
...             return "403 Forbidden"
...         case None:
...             return "302 Found"
...         case _:
...             return "400 Bad Request"
...

>>> for is_admin in 1, 1.0, 1.0 + 0.0j, True:
...     print(f"{is_admin!r:>6}:", get_http_status(is_admin))
...
     1: 400 Bad Request
   1.0: 400 Bad Request
(1+0j): 400 Bad Request
  True: 200 OK

The bool data type is a subclass of int in Python, making all four subject values in the for loop above equal. But, because Boolean literal patterns use identity checks, none of the provided numeric subjects matches the True pattern, causing the function to return the HTTP status 400.

Note that the reverse isn’t true! If a subject happens to be a Boolean value but your pattern is a numeric literal like 1.0, then the match will succeed on the grounds of value equality:

>>> age = 21
>>> match age > 18:
...     case 1.0:
...         print("You're an adult.")
...
You're an adult.

Here, the subject is a Boolean expression evaluating to True, which matches the literal pattern 1.0 since their values are equal.

So far in this section, you’ve seen literal patterns of the same type used exclusively, effectively working as an analog to the switch statement. However, you can mix and match different types of literal patterns in a single match statement if you want to:

>>> def describe(value):
...     match value:
...         case "\u03c0":
...             print("Greek letter Pi")
...         case 3:
...             print("A rough approximation of Pi")
...         case 3.14:
...             print("A slightly better approximation of Pi")
...

>>> describe("π")
Greek letter Pi

>>> describe(3)
A rough approximation of Pi

>>> describe(3.14)
A slightly better approximation of Pi

This function uses literal patterns of three distinct types: string, integer, and float. Such a construct more closely resembles the idea behind structural patterns since it matches the subject based on its type and value rather than just specific values.

Literal patterns are fairly intuitive and quick to start with, but they suffer from poor readability and fragility. Because literals aren’t always associated with human-readable names and can’t be reused, they essentially fit the definition of the magic number anti-pattern, including all the downsides that come with it. In the next section, you’ll learn about another structural pattern that addresses some of these issues.

Value Pattern

In principle, you can represent values in a programming language using literals, variables, constants, or expressions that need evaluation. You’ve seen literals in the previous section, and you’ll cover variables in the next one when you read about the capture pattern. At the same time, you know that structural patterns aren’t expressions in Python, so that leaves only constants.

That said, Python doesn’t allow for defining true constants in the traditional sense. Although several idioms for mimicking constants in Python have emerged over the years, they rely on naming conventions rather than enforced language rules. As a result, there’s no syntactical difference between variables and constants in Python:

PI = 3.14  # This is intended as a global constant. Please don't modify it!
pie = "apple"  # This is a short-lived variable, so it's okay to change it.

You often declare constants using uppercase letters as a visual cue to make them stand out, but otherwise, there’s no safety mechanism to prevent anyone from changing their values at runtime. Python programmers rely on mutual trust by respecting the conventions and unwritten rules.

Because of this syntactical limitation, you shouldn’t use previously declared variables or constants as structural patterns, as they won’t behave as you might expect them to. Recall the custom Python REPL that you built earlier. Say you wanted to follow good programming practices and keep the individual commands in separate constants to improve code readability and maintainability. You start by specifying the help command:

>>> HELP_COMMAND = "help"

>>> match input("Type your command: "):
...     case HELP_COMMAND:
...         print("Showing help.")
...
Type your command: exit
Showing help.

>>> HELP_COMMAND
'exit'

Although this piece of code looks syntactically correct, it doesn’t work as intended. Notice how your pattern succeeds even though you typed an unrecognized exit command, which isn’t supposed to match. To make matters worse, you’ve just overwritten HELP_COMMAND with the string "exit".

The root cause of the problem becomes clearer when you add a second case clause with another command:

>>> HELP_COMMAND = "help"
>>> EXIT_COMMAND = "exit"

>>> match input("Type your command: "):
...     case HELP_COMMAND:
...         print("Showing help.")
...     case EXIT_COMMAND:
...         exit()
...
  File "<stdin>", line 2
SyntaxError: name capture 'HELP_COMMAND' makes remaining patterns unreachable

There’s a syntax error now. Both patterns are examples of capture patterns, which will match any subject. Since the first pattern always matches, the second one has no chance of ever running. Additionally, the first pattern captures or binds the subject’s value to the specified name, effectively redeclaring your original constant.

You can work around this limitation by using guards, which you’ll dive into in more detail later:

>>> HELP_COMMAND = "help"
>>> EXIT_COMMAND = "exit"

>>> match input("Type your command: "):
...     case command if command == HELP_COMMAND:
...         print("Showing help.")
...     case command if command == EXIT_COMMAND:
...         exit()
...     case _:
...         print("Unknown command")
...
Type your command: quit
Unknown command

You still use capture patterns, but you augment them with conditional statements to ensure that the patterns only match when their respective guard condition is true.

This works fine but leads to overly verbose code. Fortunately, there’s a better way involving a value pattern, which lets you recognize variables that should be treated as constants. These typically belong to some namespace, such as a class, enum, or a Python module, which you can access with the dot operator:

>>> import enum
>>> import module  # Some user-defined module in the current directory

>>> class ClassCommand:
...     HELP = "help"
...
>>> class EnumCommand(enum.StrEnum):
...     EXIT = "exit"
...
>>> match input("Type your command: "):
...     case ClassCommand.HELP:
...         print("Showing help.")
...     case EnumCommand.EXIT:
...         exit()
...     case module.DebugPlugin.RELOAD:
...         print("Reloading the current session.")
...
Type your command: reload
Reloading the current session.

As long as you refer to a member by its fully qualified name, which includes at least one instance of the dot operator, then it’s clear that you’re defining a value pattern instead of a capture one. However, had you imported a member into the global namespace by using the from ... import ... syntax, you’d be back at square one with a capture pattern.

Remember that a value pattern looks like attribute access. If you tried calling a function or a method using its fully qualified name, then you’d no longer be specifying a value pattern:

>>> class Commands:
...     @staticmethod
...     def help(self):
...         return "help"
...
>>> match input("Type your command: "):
...     case Commands.help():
...         print("Showing help.")
...
Type your command: help
Traceback (most recent call last):
  File "<input>", line 2, in <module>
    case Commands.help():
         ^^^^^^^^^^^^^^^
TypeError: called match pattern must be a class

You might think that the above code would define a value pattern based on the value returned from the static method, .help(). However, the trailing pair of parentheses always indicates a class pattern, which expects a class constructor instead. That makes sense. After all, you’re defining a structural pattern rather than invoking a callable object!

Okay. You’ve seen literal patterns, value patterns, and a few examples of capture patterns. Now, it’s time to systematize what you know about capture patterns before moving on to more advanced patterns.

Capture Pattern

A capture pattern resembles the typical variable declaration. It must be a valid and preferably unique Python identifier that shouldn’t mask existing symbols in your enclosing scopes. It’ll always match the subject, binding its value to the designated name, which you can access as a variable in the current scope.

By default, a capture pattern defines its own local variable, which means that the captured name will continue to live outside your match block:

>>> match input("Type your command: "):
...     case command:
...         print(f"Calling the {command!r} command.")
...
Type your command: help
Calling the 'help' command.
>>> command
'help'

Notice how pattern matching defined a new variable, command, named after your capture pattern. This variable holds the value of the subject captured by your pattern.

Simultaneously, if a capture pattern doesn’t succeed—for example, because a previous pattern already matched the subject—then it won’t define any new variables. So, you won’t be able to refer to it afterward:

>>> match input("Type your command: "):
...     case "help":
...         print("Showing help.")
...     case command:
...         print(f"Calling the {command!r} command.")
...
Type your command: help
Showing help.
>>> command
Traceback (most recent call last):
  ...
NameError: name 'command' is not defined

You should be prepared for this scenario, for example, by defining the variable in each case clause with relevant values or initializing it beforehand.

A plain capture pattern will make the subsequent case clauses unreachable because it matches the subject unconditionally:

>>> match input("Type your command: "):
...     case command:
...         print(f"Calling the {command!r} command.")
...     case "help":
...         print("Showing help.")
  File "<input>", line 2
SyntaxError: name capture 'command' makes remaining patterns unreachable

To fix this, consider introducing guards to narrow down the set of values that would make your capture pattern match the subject. When you do, you can reuse the same name for capture patterns across multiple case clauses as long as the logical conditions remain unambiguous:

>>> match input("Type your command: "):
...     case command if command in ("help", "exit"):
...         print("Calling a predefined command.")
...     case command:
...         print(f"Calling the {command!r} command.")
...
Type your command: quit
Calling the 'quit' command.

Both capture patterns use the same variable name, command, but the first one is qualified with a conditional statement. The second pattern will succeed only when the logical expression next to the first pattern evaluates to False.

As a quick reminder, be sure to avoid capture patterns that share their name with a variable you defined previously:

>>> command = input("Type your command: ")
Type your command: exit
>>> command
'exit'
>>> match command.upper():
...     case command:
...         print(f"Calling the {command!r} command.")
...
Calling the 'EXIT' command.
>>> command
'EXIT'

Here, you store the raw user input in a variable named command, which initially holds the string "exit". Later, you use the same name as a capture pattern, which leads to overwriting your original variable with the string "EXIT" in all caps. Note that this only happens when the pattern succeeds.

Capture patterns are the cornerstone of destructuring. You’ll often use them as subpatterns to extract pieces of information from complex objects that you want to decompose. Here’s an example that illustrates the deconstruction of an object representing a common Git command:

>>> from dataclasses import dataclass
>>> from typing import Self

>>> @dataclass
... class Command:
...     name: str
...     options: tuple[str, ...]
...     subcommand: None | Self = None
...
>>> command = Command(
...     name="git",
...     options=(),
...     subcommand=Command(
...         name="commit",
...         options=("-a", "-m", "'Initial commit'"),
...     )
... )

>>> match command:
...     case Command("git", _, Command(subcommand, options)):
...         print(f"{subcommand=}\n{options=}")
...
subcommand='commit'
options=('-a', '-m', "'Initial commit'")

You define the Command data class and its concrete command instance, which describes the git commit subcommand. The highlighted line combines several patterns in one compound pattern comprised of the following:

• Literal pattern: "git"
• Wildcard pattern: _
• Class pattern: Command()
• Capture patterns: subcommand, options

When the entire pattern succeeds, then both of your capture patterns will define local variables that you can use to decide how you want to handle the command.

Suppose you wanted to specify a pattern that will only match when the main command and the subcommand are identical. Your first attempt at doing so may look like this:

>>> match command:
...     case Command(subcommand, _, Command(subcommand, options)):
...         print("The main command and subcommand are the same")
  File "<input>", line 2
SyntaxError: multiple assignments to name 'subcommand' in pattern

You declare two capture patterns with the same name, subcommand, in a single case clause. Unfortunately, this doesn’t work because structural patterns in Python can’t do runtime evaluation. To determine if two attributes are equal, you should define a guard with the desired condition next to your pattern:

>>> match command:
...     case Command(main, _, Command(subcommand, _)) if main == subcommand:
...         print("The main command and subcommand are the same")

Once a capture pattern binds some value to a name, you can’t reuse that name within the same pattern, or else you’ll get a syntax error. This doesn’t apply to the wildcard pattern (_), which doesn’t bind any names, letting you reuse it to discard multiple values.

Alright. You now have a few structural patterns under your belt. While they can help you in basic scenarios, you’ll need to expand your toolkit to tackle more demanding projects. Next up, you’ll delve into some advanced structural patterns.

Sequence Pattern

You’ll take a look at the sequence pattern first, which closely resembles iterable unpacking. With this kind of structural pattern, you can assign values from a list or tuple to multiple variables in a single line of code while controlling your execution flow.

Say you wanted to model the Git commands from the previous section as a sequence of strings comprising the subcommand as well as the optional parameters. Here’s a utility function that can parse user input using a regular expression, which turns a line of text into a list of substrings:

>>> import re

>>> def parse(command):
...     return re.split(r"\s+(?=(?:[^']*'[^']*')*[^']*$)", command)
...

>>> parse("git commit -a -m 'Initial commit'")
['git', 'commit', '-a', '-m', "'Initial commit'"]

You can ignore the regular expression above, which only serves as an example. The main point of this function is to split a string at every occurrence of one or more spaces (\s+) unless that space is enclosed within single quotes.

With this function in place, parsing commands and their arguments becomes straightforward when you use pattern matching:

>>> match parse(input("Type your command: ")):
...     case ["git"]:
...         print("Showing the list of available Git subcommands.")
...     case ["git", "--version"]:
...         print("Showing the version of your Git client.")
...     case [_, subcommand, *options]:
...         print(f"{subcommand=}, {options=}")
...
Type your command: git status --long --verbose
subcommand='status', options=['--long', '--verbose']

You can quickly recognize a sequence pattern by the presence of square brackets around the comma-delimited list of items. As with other types of compound patterns, you can nest subpatterns in a sequence pattern, including literal patterns, wildcard patterns, capture patterns, other sequence patterns, and more.

While using square brackets works best, there are three alternative notations for sequence patterns, which in most cases you can use interchangeably. They all mimic the iterable unpacking syntax:

1. Square brackets: ["git", "--version"]
2. Round brackets: ("git", "--version")
3. No brackets: "git", "--version"

There are some exceptions. To denote an empty sequence, you must use one of the two forms of brackets, as it’s not possible to express zero elements without them:

match subject:
    case []:
        print("This will match the subject if it's an empty sequence.")
    case ():
        print("This is equivalent to the above.")

Additionally, when the sequence contains only one item, then you can omit the brackets, but you also have to append a trailing comma, just like with the tuple notation:

match subject:
    case item,:
        print("This will extract the only element of a sequence subject.")
    case item:
        print("This will bind the entire subject to the capture pattern.")

Notice how the first pattern ends with a comma, whereas the second pattern doesn’t. This distinction is necessary to indicate whether you want to match a sequence with just one element—and extract it into a variable—or if you prefer to capture the whole subject regardless of whether it’s a sequence or not.

On the other hand, if you do want to surround the only item with brackets, then you have to use square brackets. If you used round brackets, then you’d be defining a regular capture pattern and not a sequence one:

match subject:
    case [item]:
        print("This is a sequence pattern.")
    case (item):
        print("This is a capture pattern. It'll match everything!")

In other words, the round brackets wrapping a single item are completely ignored. That’s intentional in order to keep the sequence pattern notation consistent with tuples.

So, which objects can become the subject of a sequence pattern? Despite some similarities to iterable unpacking, sequence patterns don’t play well with all iterables. They only match a small set of Python sequences, including the following built-in types and classes from the standard library:

• tuple()
• list()
• range()
• memoryview()
• array.array()
• collections.deque()
• collections.namedtuple()

You can also use a sequence pattern to match instances of user-defined derivatives of Sequence and MutableSequence abstract base classes. Additionally, sequence patterns will match objects that you built with a list comprehension.

At the same time, you’ll find str(), bytes(), and bytearray() among the unsupported sequence types. This may surprise you, given that all of them satisfy the sequence protocol, and you can unpack their instances into separate bytes or characters:

>>> first, *_, last = "¿Cómo estás hoy?"
>>> first
'¿'
>>> last
'?'

However, they’re also standalone objects, which you could consider scalars. Due to this dual nature, sequence patterns never match these few data types to avoid potential ambiguity:

>>> match "¿Cómo estás hoy?":
...     case first, *_, last:
...         print(f"{first=}, {last=}")
...     case default:
...         print("Not matched:", type(default))
...
Not matched: <class 'str'>

Even though the syntax of an unpacking assignment and destructuring are identical, they behave differently. The sequence pattern doesn’t succeed in this case because the subject is a string.

Notice how sequence patterns support extended unpacking through the use of the star operator (*). In the example above, you ignore elements located between the first and the last index by using a wildcard pattern (_). If you wanted to bind them to a variable, then you’d use a capture pattern instead:

>>> match list("¿Cómo estás hoy?"):
...     case first, *middle, last:
...         print(f"{first=}")
...         print(f"{middle=}")
...         print(f"{last=}")
...
first='¿'
middle=['C', 'ó', 'm', 'o', ' ', 'e', 's', 't', 'á', 's', ' ', 'h', 'o', 'y']
last='?'

The middle variable contains a list of characters that were captured. Note that you can have at most one starred expression in your sequence pattern, allowing you to capture multiple elements. Simultaneously, you don’t need any other capture patterns if you just want to capture all items of a sequence:

>>> match list("¿Cómo estás hoy?"):
...     case [*all_items]:
...         print(all_items)
...
['¿', 'C', 'ó', 'm', 'o', ' ', 'e', 's', 't', 'á', 's', ' ', 'h', 'o', 'y', '?']

This is different from a plain capture pattern, which would match any data type.

Going back to the wildcard pattern again, it can also help when you don’t know the exact size of your sequence:

match subject:
    case [first, second, *_]:
        print("This will match sequences of length two or more.")

Here, you bind the first two elements and ignore the rest as necessary. Otherwise, if your sequence pattern didn’t use the star-underscore syntax (*_) at the end, then it’d only match pairs while disregarding longer sequences:

>>> cursor_position = (765, 432, 0)
>>> match cursor_position:
...     case [x, y]:
...         print(f"{x=}, {y=}")
...     case _:
...         print("Cursor position is not a two-tuple.")
...
Cursor position is not a two-tuple.

The pattern [x, y] expects exactly two values in the sequence, but your cursor coordinates have three, so the pattern fails.

A sequence pattern will match any of the supported sequences. If you want to impose additional restrictions on the sequence type, then use a class pattern as you did before to ensure stricter type checking of literal patterns:

>>> def flip(pair):
...     match pair:
...         case list([x, y]):
...             return [y, x]
...         case tuple([x, y]):
...             return y, x
...         case _:
...             raise TypeError("Unsupported type")
...
>>> flip([1, 2])
[2, 1]
>>> flip((1, 2))
(2, 1)

Writing a concrete sequence type around the pattern requires additional effort but makes your code a bit more explicit.

Sequence patterns have a few quirks but are undoubtedly a powerful tool. Next up, you’ll learn about the mapping pattern, which is another advanced structural pattern.

Mapping Pattern

Dictionaries, along with other Python mappings, are among one of the most important data types, offering instant access to values based on unique keys. Python uses them everywhere, from tracking object attributes and implementing namespaces to organizing imported modules. You often use dictionaries in your own code to store and manage data.

Therefore, it’s essential for Python to support mapping patterns in structural pattern matching. They can be especially helpful in consuming REST APIs that serve JSON responses, which you can then deserialize to Python dictionaries.

Suppose you modeled your Git commands using dictionaries instead of data classes. You can quickly convert the git commit command, which you defined previously, to a dictionary with asdict():

>>> from dataclasses import asdict, dataclass
>>> from typing import Self

>>> @dataclass
... class Command:
...     name: str
...     options: tuple[str, ...]
...     subcommand: None | Self = None
...
>>> command = Command(
...     name="git",
...     options=(),
...     subcommand=Command(
...         name="commit",
...         options=("-a", "-m", "'Initial commit'"),
...     )
... )

>>> asdict(command)
{
    'name': 'git',
    'options': (),
    'subcommand': {
        'name': 'commit',
        'options': ('-a', '-m', "'Initial commit'"),
        'subcommand': None
    }
}

Instead of using a hierarchy of objects, you now represent the same command with a Python dictionary, which can become the subject of a match statement:

>>> match asdict(command):
...     case {"subcommand": {"options": options, "name": "commit"}}:
...         print(options)
...
('-a', '-m', "'Initial commit'")

A mapping pattern looks like your typical dictionary literal, leveraging curly brackets, commas, and colons to combine keys with values. Because mappings are unordered collections of key-value pairs, it doesn’t matter how you arrange your keys and values in the pattern. Here, you intercept any command whose subcommand is named "commit" while capturing its options.

>>> import math
>>> match dict():
...     case {3.14: "Pi"}:  # Literal pattern
...         ...
...     case {math.pi: "Pi"}:  # Value pattern
...         ...
...     case {pi: "Pi"}:  # Capture pattern
  File "<stdin>", line 6
    case {pi: "Pi"}:  # Capture pattern
            ^
SyntaxError: invalid syntax

A mapping pattern will match not only the built-in Python dict but also other kinds of mappings, including the ones from the collections module:

• collections.ChainMap
• collections.Counter
• collections.OrderedDict
• collections.UserDict
• collections.defaultdict

When you use an empty dictionary literal {}, then your pattern will match just about any mapping:

>>> from collections import (
...     ChainMap, Counter, OrderedDict, UserDict, defaultdict
... )
>>> mappings = (
...     d := dict(pi=3.14, e=2.72),
...     ChainMap(d),
...     Counter(d),
...     OrderedDict(d),
...     UserDict(d),
...     defaultdict(float, d),
... )
>>> for subject in mappings:
...     match subject:
...         case {}:
...             print("Matched:", type(subject))
...
Matched: <class 'dict'>
Matched: <class 'collections.ChainMap'>
Matched: <class 'collections.Counter'>
Matched: <class 'collections.OrderedDict'>
Matched: <class 'collections.UserDict'>
Matched: <class 'collections.defaultdict'>

Notice that your pattern matches these mappings even though they contain the key-value pairs pi=3.14 and e=2.72, which you haven’t specified in the pattern.

This is an important difference from sequence patterns. Sequence patterns require you to either list all expected items or use the star operator (*) to indicate a variable-length sequence. In contrast, mapping patterns ignore any extra keys that exist in the subject but that you didn’t explicitly include in your pattern.

Therefore, you don’t need to use a wildcard pattern to ignore the remaining key-value pairs. The **_ symbol would be redundant, so it’s disallowed. You can, however, use the standard dictionary unpacking to capture multiple key-value pairs into their own smaller dictionary:

>>> match asdict(command):
...     case {"subcommand": _, **rest}:
...         print(rest)
...
{'name': 'git', 'options': ()}

As with sequence patterns, the star pattern (**) can appear at most once. If you placed more than one, then it wouldn’t be clear which key-value pairs should be captured by each one.

Structural patterns are designed to avoid side effects as much as possible. To give you an example of a side effect, think of accessing a missing key in a defaultdict instance. This puts the default value under a new key, mutating your mapping:

>>> from collections import defaultdict
>>> histogram = defaultdict(int)
>>> for color in ("#000", "#4b7f9e", "#fff", "#4b7f9e"):
...     histogram[color] += 1
...
>>> dict(histogram)
{'#000': 1, '#4b7f9e': 2, '#fff': 1}

In this case, the int() function delivers a default value, which is equal to zero, for the initial color count in your histogram. When you read the current value of a color for the first time, Python calls the provided callback function and uses its result as the default value before letting you increment it by one.

To avoid adding new key-value pairs into such mappings, Python doesn’t use the square bracket syntax when matching a subject to one of your mapping patterns. Rather than calling .__getitem__(), which square brackets use under the hood, it invokes .get() on the subject:

>>> from collections import defaultdict
>>> histogram = defaultdict(int)
>>> histogram.get("#4b7f9e")  # Returns None without altering the histogram
>>> dict(histogram)
{}
>>> histogram["#4b7f9e"]  # Returns the default value, adding a new entry
0
>>> dict(histogram)
{'#4b7f9e': 0}

Calling histogram.get() bypasses the standard lookup path, so when your mapping is empty, you won’t put any new entries into it. On the other hand, using the square brackets syntax leads to modifying the histogram if the key doesn’t exist.

You’ve covered a lot of ground, but there’s one more advanced structural pattern to take a closer look at. In the next section, you’ll learn about the class pattern.

Class Pattern

You’ve already seen a few class patterns in this tutorial. When used in conjunction with literal patterns, they enabled a stricter type control at runtime, whereas capture patterns allowed you to extract attribute values from objects. If you’re interested in matching the subject solely by its type, then you can use plain class patterns. Here’s an example:

>>> from datetime import UTC, datetime

>>> def parse(value):
...     match value:
...         case datetime():
...             return value.astimezone(UTC)
...         case int() | float():
...             return datetime.fromtimestamp(value, UTC)
...         case str():
...             return datetime.fromisoformat(value).astimezone(UTC)
...         case _:
...             raise TypeError(f"Unsupported type: {type(value)}")
...

>>> parse(-14182967.876544)
datetime(1969, 7, 20, 20, 17, 12, 123456, tzinfo=datetime.timezone.utc)

>>> parse("1969-07-20T20:17:12.123456+00:00")
datetime(1969, 7, 20, 20, 17, 12, 123456, tzinfo=datetime.timezone.utc)

This function takes a value as an argument, which can be one of four supported data types, and returns a timezone-aware datetime instance. Depending on which type you pass as an actual parameter into the function, it determines the appropriate conversion method using pattern matching.

As you can see, instead of explicitly calling isinstance() on the subject, you can check if the subject is an instance of the given type by using a class pattern. This is more compact and gives you the option to destructure an object into its constituent parts.

You can generally use keyword arguments of the class constructor to extract attribute values:

>>> import datetime

>>> def aoc_status(date):
...     match date:
...         case datetime.date(year=_, month=12, day=1):
...             print("Advent of Code starts today!")
...         case datetime.date(year=_, month=12, day=day) if day <= 25:
...             print(f"{25 - day} days until the end of AoC.")
...         case _:
...             print("Sorry, no Advent of Code today.")
...

>>> aoc_status(datetime.date.today())
Sorry, no Advent of Code today.

>>> aoc_status(datetime.date(2024, 12, 1))
Advent of Code starts today!

>>> aoc_status(datetime.date(2024, 12, 2))
23 days until the end of AoC.

Your aoc_status() function checks if the given date coincides with the Advent of Code, which is an annual coding puzzle contest that takes place between the first and twenty-fifth of December each year.

In both cases, you pass keyword subpatterns to the datetime.date() class pattern. The first one includes a wildcard pattern to ignore the year, and two literal patterns to match a specific month and day. The second one additionally captures the day number as long as that day is on or before the twenty-fifth of December when the Advent of Code ends. Alternatively, you could omit the year attribute altogether in both class patterns.

match date:
    case datetime.date(year=_, month=same, day=same):
        ...

Sometimes, you can specify your patterns using positional subpatterns instead of keyword ones. Whether it’s possible depends on the data type that you refer to in your class pattern. In this instance, the datetime.date class doesn’t accept any positional subpatterns:

>>> match datetime.date.today():
...     case datetime.date(_, 12, 1):
...         pass
...
Traceback (most recent call last):
  File "<input>", line 2, in <module>
    case datetime.date(_, 12, 1):
         ^^^^^^^^^^^^^^^^^^^^^^^
TypeError: datetime.date() accepts 0 positional sub-patterns (3 given)

When you try to use three consecutive subpatterns without providing the associated argument names, then pattern matching fails.

Compiled languages with static type checking, which support pattern matching, would make this possible with the help of algebraic data types. Python’s dynamic nature throws a wrench in the works, making matching by positional arguments a bit trickier. The interpreter can’t always guarantee that the order of your positional subpatterns will correspond to the order of expected attributes defined in the class.

That said, you’ll find a few built-in and standard-library types that support matching by positional arguments. Data classes and named tuples are among them since they inherently impose order on their attributes:

>>> from typing import NamedTuple

>>> class Date(NamedTuple):
...     year: int
...     month: int
...     day: int
...
>>> match Date(1969, 7, 20):
...     case Date(_, 7, 20):
...         print("Celebrating another moon landing anniversary!")
...
Celebrating another moon landing anniversary!

Python can correctly tie the specified subpatterns to the positional arguments of the constructor thanks to the special .__match_args__ attribute that was generated automatically for you:

>>> Date.__match_args__
('year', 'month', 'day')

Such an ordered sequence of attribute names allows Python to correctly map positional subpatterns to their keyword counterparts, which are used under the surface.

Most classes, including datetime.date that you just used, don’t come with this special attribute, though:

>>> datetime.date.today().__match_args__
Traceback (most recent call last):
  ...
AttributeError: 'datetime.date' object has no attribute '__match_args__'

You must, therefore, rely on explicit keyword arguments or provide the special .__match_args__ attribute yourself in user-defined classes. You’ll see examples of this and learn how to customize pattern matching for instances of your classes in the next section.

While the majority of classes only support matching by keyword subpatterns, you can take advantage of a convenient shorthand notation for most built-in types. If there’s a version of the constructor that accepts a single value, then it’s possible to implicitly match the subject using a positional subpattern:

>>> def length(value):
...     match value:
...         case str(text):
...             return len(text)
...         case int(number):
...             return number.bit_length()
...
>>> length("255")
3
>>> length(255)
8

Neither str nor int provides the special .__match_args__ attribute, but they know how to properly interpret the only positional subpattern. This can simplify your code by relieving you from writing an AS pattern, such as str() as text, which you’ll learn about later.

Note that fields not automatically initialized in a data class are excluded from pattern matching:

>>> from dataclasses import dataclass, field
>>> from datetime import date

>>> @dataclass
... class Person:
...     dob: date
...     age: int = field(init=False)
...
...     def __post_init__(self):
...         self.age = date.today().year - self.dob.year
...
>>> person = Person(date(1982, 1, 31))
>>> match person:
...     case Person(_):
...         print(f"This person's {person.age} years old.")
...
This person's 42 years old.

You only use one wildcard pattern to match a person’s date of birth (.dob). The other attribute, .age, isn’t taken into consideration when matching because you haven’t specified it in the constructor. The second attribute was computed dynamically based on the current year and the person’s date of birth.

Matching instances of nominal subtypes as well as structural subtypes works as expected:

>>> from typing import NamedTuple, Protocol, runtime_checkable

>>> @runtime_checkable
... class Additive(Protocol):
...     def __add__(self, other):
...         ...
...
>>> class Vector(NamedTuple):
...     x: int
...     y: int
...
...     def __add__(self, other):
...         return Vector(self.x + other.x, self.y + other.y)
...
>>> match Vector(3, 4):
...     case Additive():
...         print("Matched an additive object.")
...
Matched an additive object.

Since class patterns call the isinstance() function on the subject, make sure that any protocol you match against was decorated with @runtime_checkable.

The syntax of class patterns, which you can use to destructure an object, elegantly mirrors the syntax of class instantiation. However, you may sometimes need to take additional steps if you want to make your custom classes play nicely with pattern matching.