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.

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:
from dataclasses import dataclass
@dataclass
class Server:
host: str
port: intWithout nested patterns, you might write:
def get_port(config):
if isinstance(config, Server):
return config.port
return NoneWith a nested pattern, you can combine the type check and attribute extraction:
def get_port(config):
match config:
case Server(port=port):
return port
case _:
return NoneThe 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:
@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:
def first_point(shape):
match shape:
case Polygon(points=[Point(x=x, y=y), *_]):
return (x, y)
case _:
return NoneThe 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:
payload = {
"user": {
"name": "alice",
"roles": ["admin", "editor"]
}
}To extract the user's name and first role, you can write:
def extract_user(data):
match data:
case {"user": {"name": name, "roles": [first_role, *_]}}:
return (name, first_role)
case _:
return NoneThe 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:
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:
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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.