Exploring Python's New Structural Pattern Matching: Use Cases and Best Practices

Core Concepts with Small Examples

Let's start small and build up.

Literal and Capture Patterns

def describe_value(v):
    match v:
        case 0:
            return "zero"
        case "":          # literal empty string
            return "empty string"
        case int() as n:  # matches ints and captures as n
            return f"integer {n}"
        case x:
            return f"other: {x}"

Line-by-line:

• match v: — starts a match block.
• case 0: — literal match for integer zero.
• case "" — literal match for empty string.
• case int() as n: — class pattern matching ints; n captures the int value.
• case x: — catch-all capture binding the whole value to x.

• Be careful: case int() matches any int; ordering matters (put more specific literals before broad class patterns).

Sequence Patterns

Mapping Patterns

def handle_message(msg):
    match msg:
        case {"type": "add", "a": a, "b": b}:
            return a + b
        case {"type": "greet", "name": name}:
            return f"Hello, {name}"
        case {"type": t}:
            return f"Unknown message type {t}"
        case _:
            return "Invalid message"

Explain:

• Matches dict-like objects. Unmatched keys are allowed unless you use extra checks.
• Useful for basic JSON-like dispatching.

Step-by-Step Real-World Examples

Now we'll tackle realistic patterns: command routing, parsing AST-like data, and a small evaluator.

Example 1 — Command Router for JSON-like Commands

Scenario: You receive JSON commands over a socket. Pattern matching makes the router clean.

Explain:

• The AST uses tuple shapes like ("add", left, right).
• Recursive evaluation shows how pattern matching reads the shape naturally.
• Use of recursion can be sped up with functools.lru_cache if nodes are hashable identifiers or if you memoize by node IDs.

• If many repeated sub-expressions exist, memoize results via node IDs or convert the AST to objects with stable identifiers.

Example 3 — Matching Dataclass/Custom Class Patterns

When matching custom types, structure patterns work well with dataclasses or classes that define __match_args__.

from dataclasses import dataclass
@dataclass
class Point:
    x: int
    y: int
def classify_point(p):
    match p:
        case Point(0, 0):
            return "origin"
        case Point(x, 0):
            return f"on x-axis at {x}"
        case Point(0, y):
            return f"on y-axis at {y}"
        case Point(x, y) if x == y:
            return "on diagonal"
        case Point(x, y):
            return "somewhere else"

Line-by-line:

• Dataclasses automatically support class pattern matching by using their positional fields.
• Guards (if x == y) provide extra checks after matching structure.

• Custom classes without dataclass can define __match_args__ to control positional matching.

Combining itertools with Pattern Matching

The itertools module helps generate iterables efficiently; pair it with pattern matching for elegant solutions.

Example: find pairs of items that match a pattern.

from itertools import combinations
def find_pairs(items):
    # items is a list of (type, value) tuples
    result = []
    for a, b in combinations(items, 2):
        match (a, b):
            case (("color", "red"), ("value", val)):
                result.append(("red-value", val))
            case (("name", n1), ("name", n2)) if n1 != n2:
                result.append(("distinct_names", n1, n2))
            case _:
                continue
    return result

Explain:

• itertools.combinations(items, 2) efficiently iterates unique pairs.
• match (a, b) uses tuple sequence pattern matching to decode pair contents.
• This approach avoids nested loops with manual unpacking and conditional checks.

• itertools works lazily; prefer it when working with large data streams.

Best Practices

• Use Python 3.10+ and test compatibility: include runtime checks if targeting multiple Python versions.
• Order matters: put specific patterns before general ones (e.g., literal before class patterns).
• Prefer explicit error handling for unexpected shapes: avoid silent fall-throughs.
• Keep matching logic pure where possible—use functions that return values rather than side effects.
• Use dataclasses or NamedTuple to make class pattern matching clear and robust.
• Use guards sparingly—keep them as helpers, not as primary logic.
• Consider memoization (functools.lru_cache) for expensive recursive match-based functions.
• Combine itertools for generating candidate structures to match when processing streams or combinatorial data.

Common Pitfalls and How to Avoid Them

• Confusing capture names with constants: unquoted names in patterns are captures; use literal patterns for constants by quoting or using value patterns like case 0 or case "x". For matching against a constant variable, use case varname: won’t work as literal—use case const_value: only for class patterns or use a guard (e.g., case x if x == CONST).
• Matching mutable types: sequence patterns expect sequence behavior—not arbitrary iterables. If your input could be any iterable, convert or check type.
• Performance: many deep nested matches have overhead—benchmark if performance is critical. Avoid heavy matching in tight loops; consider preprocessing or memoization.
• Overly clever patterns: clarity beats concision. If a pattern becomes hard to understand, break it into clearer functions.

Advanced Tips and Extensions

• __match_args__ and custom classes: define __match_args__ = ("x", "y") to control which attributes are used for positional matching.
• Dataclass + pattern matching: dataclasses are ideal; use frozen=True for hashability if you plan to use instances as cache keys.
• Use OR patterns: case ("add", a, b) | ("sum", a, b): to handle synonyms.
• AS patterns: case point as p if isinstance(p, Point): captures whole object while also checking structure.
• Integrate with functools.partial or singledispatch for routing patterns to handlers. Pattern matching can replace some use-cases for singledispatch by centralizing dispatch logic.

Testing Pattern Matching with Pytest

Example: We will write pytest tests for the evaluate AST evaluator from earlier.

Create a test module test_evaluator.py:

# test_evaluator.py
import pytest
from mymodule import evaluate  # assume evaluator is in mymodule.py
@pytest.mark.parametrize("node,expected", [
    (("num", 1), 1),
    (("add", ("num", 2), ("num", 3)), 5),
    (("mul", ("num", 2), ("add", ("num", 3), ("num", 4))), 14),
    (("neg", ("num", 5)), -5),
])
def test_evaluate(node, expected):
    assert evaluate(node) == expected
def test_invalid_node():
    with pytest.raises(ValueError):
        evaluate(("unknown",))

Explain:

• Use parametrization to cover multiple cases concisely.
• Test error conditions explicitly (with pytest.raises) for unknown patterns.
• For more complex match-based logic, add tests for guards, OR variants, and unexpected types.

• Cover representative shapes, nested structures, and edge cases.
• When using functools.lru_cache, tests should be written to ensure cache doesn't hide bugs; use cache clearing (expensive_compute.cache_clear()) in fixtures if needed.

Performance Considerations

• Pattern matching is implemented in the interpreter; performance is generally comparable to equivalent if/elif structures. However:

• Memory considerations: lru_cache can hold references—be mindful of cache size.

Diagram (Described)

Imagine a flowchart:

• Start -> Receive data -> Pattern match dispatch: