Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Nested Pattern Matching

Learn how to use nested pattern matching in Python's match/case to destructure complex data structures with concise, readable code.

~5 min readPython
#structural pattern matching#match/case#nested patterns#Python 3.10
Illustration of nested pattern matching in Python, showing a hierarchical data structure being destructured by a match statement.

Nested patterns in Python's match/case let you match against complex data structures without writing a series of isinstance checks and manual unpacking. Instead, you describe the shape you expect, and Python binds the values you need directly in the pattern. This article explains how nested patterns work, where they simplify code, and what to watch out for when using them in production.

What Nested Patterns Do in match/case

Python's match statement, introduced in 3.10, supports several pattern types: literal patterns, capture patterns, wildcard patterns, sequence patterns, mapping patterns, and class patterns. Nested patterns are simply patterns that appear inside another pattern. For example, a sequence pattern can contain a class pattern, and a class pattern can contain a mapping pattern. This lets you match a whole object graph in one statement.

Consider a simple configuration object:

python
from dataclasses import dataclass @dataclass class Server: host: str port: int

Without nested patterns, you might write:

python
def get_port(config): if isinstance(config, Server): return config.port return None

With a nested pattern, you can combine the type check and attribute extraction:

python
def get_port(config): match config: case Server(port=port): return port case _: return None

The Server(port=port) pattern matches any Server instance and binds its port attribute to the variable port. The pattern is nested because the class pattern is the outer pattern and the capture pattern port is nested inside it.

Sequence Patterns Inside Class Patterns

Nested patterns become more powerful when you combine different pattern types. Suppose you have a Point class and a Polygon class that contains a list of points:

python
@dataclass class Point: x: float y: float @dataclass class Polygon: points: list[Point]

You can match a polygon and extract the first point's coordinates in one step:

python
def first_point(shape): match shape: case Polygon(points=[Point(x=x, y=y), *_]): return (x, y) case _: return None

The outer pattern is a class pattern for Polygon. Inside its points attribute, a sequence pattern matches a list whose first element is a Point with x and y captured. The *_ wildcard matches the rest of the list. This single pattern replaces multiple isinstance checks and indexing operations.

Mapping Patterns and Nested Keys

Mapping patterns match dictionaries by specifying keys. Nested mapping patterns let you reach into nested dictionaries without chaining .get() calls. For example, a request payload might look like this:

python
payload = { "user": { "name": "alice", "roles": ["admin", "editor"] } }

To extract the user's name and first role, you can write:

python
def extract_user(data): match data: case {"user": {"name": name, "roles": [first_role, *_]}}: return (name, first_role) case _: return None

The outer mapping pattern requires the key "user". Its value is another mapping pattern that requires "name" and "roles". The "roles" value is a sequence pattern that captures the first element. If any key is missing or the shape doesn't match, the case is skipped.

Combining Patterns with OR and Guards

Nested patterns can be combined with OR patterns (|) and guards (if) to express more complex conditions. For instance, you might want to match a point that lies on either axis:

python
def axis(point): match point: case Point(x=0) | Point(y=0): return "on axis" case _: return "off axis"

The OR pattern matches if either alternative matches. Because both alternatives bind the same set of names (none), the combined pattern is valid. If the point is at the origin, it matches through either alternative.

Guards can refine nested patterns. Suppose you want to match a polygon with exactly three points:

python
def triangle(shape): match shape: case Polygon(points=[Point(), Point(), Point()]) if len(shape.points) == 3: return "triangle" case _: return "not triangle"

The guard runs after the pattern matches, so you can check properties that aren't directly captured. Note that the pattern itself already requires three points, so the guard is redundant here, but it illustrates how guards work with nested patterns.

Common Mistakes with Nested Patterns

Nested patterns are concise, but they have subtle pitfalls. One common mistake is using a capture pattern in a position where you intended a literal. For example, case Point(x=0, y=0) matches a point at the origin, but case Point(x=x, y=y) captures any point. The capture pattern binds x and y in the current scope, so it overwrites any existing values with those names.

Another mistake is forgetting that sequence patterns match any sequence, not just lists. A tuple of points will also match the pattern [Point(), Point()]. If you need to distinguish between a list and a tuple, add a guard such as if isinstance(shape.points, list) or check the type explicitly.

Mapping patterns match when the specified keys are present; extra keys do not prevent a match. To require an exact set of keys, you need a guard or a custom matcher.

Finally, nested patterns can become deeply nested and hard to read. When a pattern spans multiple lines, consider breaking it into smaller named patterns or using a helper function to keep the match statement readable.

Performance and Maintainability

The match statement is compiled into efficient bytecode that avoids repeated attribute lookups and isinstance checks. Matching proceeds outer-first: Python checks the outer pattern first and only descends into inner patterns when the outer shape matches. This means a deeply nested pattern that fails early doesn't pay the cost of checking the inner structure.

That said, very large data structures can still incur a cost proportional to the depth of the pattern. For a one-off script, this is rarely a concern. For hot paths, you should profile rather than assume. The main benefit of nested patterns is maintainability: they reduce the number of branches and make the expected shape explicit. Code that uses nested patterns is often easier to modify when the data structure changes, because the pattern is localized.

When to Use Nested Patterns vs. Manual Unpacking

Nested patterns shine when you need to validate and extract from a known structure in a single step. Use them when the shape is stable and you want to avoid repetitive boilerplate. They are especially useful for parsing JSON-like data, handling command-line arguments, or implementing state machines.

Manual unpacking with isinstance, get, and indexing is still appropriate when the structure is highly dynamic or when you need to perform additional logic that doesn't fit a pattern. For example, if you need to mutate the data while inspecting it, a pattern match is not the right tool. Also, if you are targeting Python versions before 3.10, nested patterns are unavailable, so manual unpacking remains necessary.

When you do use nested patterns, keep them shallow. A pattern that nests more than three levels deep is usually a sign that the data structure itself is too complex and could benefit from refactoring. Prefer named patterns or sub-patterns to improve readability.

Nested patterns are a powerful addition to Python's control flow. They let you express complex destructuring in a declarative way, reducing the chance of off-by-one errors and missing edge cases. By understanding how they compose and where they fall short, you can use them effectively without turning your code into a maze of brackets and underscores.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.