Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
  1. Type Verification: The engine performs an implicit isinstance(subject, ClassName) check. If this evaluates to False, the pattern fails immediately.
  2. Positional Argument Matching: If positional sub-patterns are provided, the engine maps them to the subject’s attributes using the __match_args__ class attribute.
  3. 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)
Master Python with Deep Grasping Methodology!Learn More