Python Mapping Pattern: Match Dictionaries

python mapping pattern requires a clear understanding of the core syntax, runtime behavior, and practical implementation patterns demonstrated in the examples below.

Python's mapping pattern is a feature of structural pattern matching introduced in Python 3.10. It lets you match dictionaries by their keys inside a match statement, providing a concise way to extract values while verifying the structure of the input. This article focuses on the mapping pattern in particular, showing how it works, where it shines, and what pitfalls to avoid.

Mapping Pattern Syntax

The mapping pattern uses a dictionary-like literal inside a case block. Keys can be literals or capture patterns. A simple example:

match command:
    case {"action": "start"}:
        print("Starting")
    case {"action": "stop"}:
        print("Stopping")

Here, command is expected to be a dictionary. The pattern checks that the key "action" exists and that its value equals "start" or "stop". If the dictionary has extra keys, the pattern still matches; only the specified keys are checked. This is different from a literal dictionary equality check.

Capturing Values

You can capture values from the dictionary using capture patterns, which are simply variable names. For example:

match config:
    case {"host": host, "port": port}:
        print(f"Connecting to {host}:{port}")

This matches any dictionary that contains both "host" and "port" keys, and binds their values to host and port. If a key is missing, the case does not match. The order of keys in the pattern does not matter; Python checks for presence and value, not order.

Using Wildcards and Rest

Often you want to match only a subset of keys and ignore the rest. You can use **_rest to capture all remaining items into a dictionary:

match event:
    case {"type": "click", **details}:
        print(f"Click at {details.get('x')}, {details.get('y')}")

Here, details will contain all keys except "type". This is useful when you need to pass through extra metadata without naming every possible key. You can also use a bare ** to ignore the rest entirely, but note that **_ is a common convention to indicate an intentionally unused rest variable.

Nested Mapping Patterns

Mapping patterns can be nested inside other patterns, including other mapping patterns. This allows you to match deeply structured dictionaries in one go:

match response:
    case {"status": 200, "body": {"user": {"name": name}}}:
        print(f"User: {name}")
    case {"status": 404}:
        print("Not found")

Nested patterns are evaluated recursively. If any level fails to match, the whole case is skipped. This reduces the need for multiple if checks and makes the intent explicit.

Guards and Conditions

You can combine a mapping pattern with a guard (if) to add extra conditions that cannot be expressed purely by the pattern. For example:

match request:
    case {"method": "GET", "path": path} if path.startswith("/api"):
        print("API GET request")

The guard runs only after the pattern matches. It can reference captured variables. This is useful for validating relationships between values or applying custom logic.

Common Pitfalls and Edge Cases

Mapping patterns work with any object that supports the mapping protocol, not just dict. However, they do not match on the exact type; they only require that the object can be queried for keys. This means that custom mapping classes will work, but the pattern will not distinguish between a dict and a defaultdict.

Another pitfall is that duplicate keys in the pattern are not allowed. For instance, case {"a": x, "a": y}: raises a SyntaxError. Also, if you use a capture pattern for a key, the key must be a literal or a value pattern; you cannot use a variable as a key to be looked up dynamically.

When matching, the order of key checks is not guaranteed. If two keys have the same value pattern, the first match in the pattern's definition order is used, but this is rarely a concern because keys are unique.

Performance and Maintainability Considerations

Mapping patterns are evaluated at runtime, and each key check is a dictionary lookup. For most use cases, the overhead is negligible compared to the clarity gained. However, if you are matching a very large dictionary or have many cases, consider whether a simple if chain might be faster. The pattern matching engine is optimized, but it still performs multiple lookups.

Maintainability is where mapping patterns truly shine. They keep related checks and extractions in one place, reducing the risk of forgetting a key or misaligning conditions. When the structure of the input is stable, a mapping pattern is more readable than a series of if statements. When the structure is highly dynamic or unknown, a mapping pattern may become brittle; in those cases, a more explicit approach might be better.

A practical decision rule: use a mapping pattern when you know the expected keys and want to extract them cleanly. If you need to handle arbitrary keys or perform complex transformations, a regular loop or dictionary method may be simpler.

Mapping patterns are a powerful addition to Python's pattern matching toolkit. They make dictionary destructuring explicit and safe, reducing boilerplate and improving code clarity. By understanding the syntax and limitations, you can use them effectively in your own code.