Python Class Pattern

A class pattern is a structural pattern matching construct in Python (introduced in Python 3.10) used within match/case statements to verify an object’s type and deconstruct its attributes. It evaluates to True if the subject is an instance of the specified class and all nested sub-patterns successfully match or bind to the object’s attributes.

match subject:
    case ClassName(positional_pattern, keyword_attribute=keyword_pattern):
        pass

Technical Mechanics

The matching engine processes a class pattern in three distinct phases:

Type Verification: The engine performs an implicit isinstance(subject, ClassName) check. If this evaluates to False, the pattern fails immediately.
Positional Argument Matching: If positional sub-patterns are provided, the engine maps them to the subject’s attributes using the __match_args__ class attribute.
Keyword Argument Matching: If keyword sub-patterns are provided, the engine extracts the attribute by name using getattr(subject, "keyword_attribute") and matches it against the provided sub-pattern.

Keyword Matching

Keyword patterns extract attributes by name. The pattern succeeds only if the attribute exists and matches the specified sub-pattern (which can be a literal, a variable binding, or another nested pattern).

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

subject = Point(0, 10)

match subject:
    # Matches: subject is a Point, subject.x == 0, binds subject.y to 'y_val'
    case Point(x=0, y=y_val):
        print(y_val) 
    
    # Matches ANY instance of Point (parentheses are required)
    case Point():
        pass

Positional Matching and `__match_args__`

To use positional arguments in a class pattern, the target class must define the __match_args__ special attribute. This attribute is a tuple of strings dictating the order in which positional patterns map to class attributes. If __match_args__ is not defined, attempting to use positional patterns will raise a TypeError.

class Vector:
    __match_args__ = ("i", "j")
    
    def __init__(self, i, j):
        self.i = i
        self.j = j

subject = Vector(5, 10)

match subject:
    # Maps 5 to 'i' and 10 to 'j' based on __match_args__
    case Vector(5, j_val):
        print(j_val)

Note: Python’s @dataclass and collections.namedtuple automatically generate the __match_args__ attribute based on their field definitions.

Built-in Type Exceptions

Eleven built-in types exhibit specialized behavior in class patterns: bool, bytearray, bytes, dict, float, frozenset, int, list, set, str, and tuple. When matching against these types, a single positional argument does not look for an attribute via __match_args__. Instead, it matches the sub-pattern against the entire subject itself.

subject = 42

match subject:
    # Matches because isinstance(subject, int) is True, 
    # and the subject itself is bound to 'value'
    case int(value):
        print(value)

Nested Deconstruction

Class patterns can be arbitrarily nested, allowing the matching engine to traverse deep object graphs in a single declarative statement.

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

class Line:
    __match_args__ = ("start", "end")
    def __init__(self, start, end):
        self.start = start
        self.end = end

subject = Line(Point(0, 0), Point(10, 10))

match subject:
    # Verifies Line, verifies start is Point with x=0, binds end.y to end_y
    case Line(Point(x=0), Point(y=end_y)):
        print(end_y)