> ## 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.
# 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.
```python theme={"dark"}
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).
```python theme={"dark"}
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`.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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)
```
Tired of Poor Python Skills? Fix That With Deep Grasping!
Learn More
