pattern_matching.py

"""
Structural pattern matching allows you to match complex data structures
against patterns and extract values in a clean, readable way. This feature
is similar to switch-case statements in other languages but much more powerful.

Pattern matching was introduced in Python 3.10 through PEP 634, PEP 635,
and PEP 636. It uses the 'match' and 'case' keywords.
"""

from typing import Any


def classify_number(value: object) -> str:
    """Classify a number using pattern matching with literals.

    This demonstrates matching against specific literal values.
    """
    match value:
        case 0:
            return "zero"
        case 1:
            return "one"
        case 2:
            return "two"
        case _:
            # The underscore _ is a wildcard that matches anything
            return "other"


def classify_http_status(status: object) -> str:
    """Classify HTTP status codes using pattern matching.

    This shows how pattern matching can make code more readable
    than a series of if-elif-else statements.
    """
    match status:
        case 200:
            return "OK"
        case 201:
            return "Created"
        case 400:
            return "Bad Request"
        case 401:
            return "Unauthorized"
        case 404:
            return "Not Found"
        case 500:
            return "Internal Server Error"
        case _:
            return "Unknown Status"


def process_point(point: object) -> str:
    """Process a point tuple using pattern matching with sequences.

    This demonstrates pattern matching against tuple structures
    and extracting values from them.
    """
    match point:
        case (0, 0):
            return "Origin"
        case (0, y):
            # Match any point on the y-axis, capture y coordinate
            return f"Y-axis at y={y}"
        case (x, 0):
            # Match any point on the x-axis, capture x coordinate
            return f"X-axis at x={x}"
        case (x, y):
            # Match any other point, capture both coordinates
            return f"Point at ({x}, {y})"
        case _:
            return "Not a valid 2D point"


def analyze_sequence(data: object) -> str:
    """Analyze sequences using pattern matching.

    This shows how to match lists with specific structures
    and extract elements.
    """
    match data:
        case []:
            return "Empty list"
        case [x]:
            # Match a list with exactly one element
            return f"Single element: {x}"
        case [x, y]:
            # Match a list with exactly two elements
            return f"Pair: {x}, {y}"
        case [first, *rest]:
            # Match a list with at least one element
            # The *rest captures remaining elements
            return f"First: {first}, Rest: {rest}"
        case _:
            return "Not a list"  # pragma: no cover


def process_command(command: Any) -> str:
    """Process commands using pattern matching with guards.

    Guards are if conditions that provide additional filtering
    after a pattern match.
    """
    match command:
        case ["quit"]:
            return "Quitting"
        case ["go", direction] if direction in ["north", "south", "east", "west"]:
            # Guard clause: only match if direction is valid
            return f"Going {direction}"
        case ["go", direction]:
            # This matches any direction that failed the guard above
            return f"Invalid direction: {direction}"
        case ["take", item]:
            return f"Taking {item}"
        case ["take", item, quantity] if quantity > 0:
            return f"Taking {quantity} {item}"
        case ["take", item, quantity]:
            return f"Invalid quantity: {quantity}"
        case _:
            return "Unknown command"


class Point:
    """A simple 2D point class for pattern matching examples."""

    def __init__(self, x: int, y: int) -> None:
        self.x = x
        self.y = y


class Circle:
    """A circle with center and radius for pattern matching examples."""

    def __init__(self, center: Point, radius: int) -> None:
        self.center = center
        self.radius = radius


def describe_shape(shape: object) -> str:
    """Describe shapes using pattern matching with class patterns.

    This demonstrates matching against class instances and
    extracting their attributes.
    """
    match shape:
        case Point(x=0, y=0):
            # Match a Point at the origin
            return "Point at origin"
        case Point(x=0, y=y):
            # Match a Point on the y-axis
            return f"Point on Y-axis at {y}"
        case Point(x=x, y=0):
            # Match a Point on the x-axis
            return f"Point on X-axis at {x}"
        case Point(x=x, y=y) if x == y:
            # Match a Point on the diagonal line y=x
            return f"Point on diagonal at ({x}, {y})"
        case Point(x=x, y=y):
            # Match any other Point
            return f"Point at ({x}, {y})"
        case Circle(center=Point(x=0, y=0), radius=r):
            # Match a Circle centered at origin
            return f"Circle at origin with radius {r}"
        case Circle(center=Point(x=x, y=y), radius=r):
            # Match any other Circle
            return f"Circle at ({x}, {y}) with radius {r}"
        case _:
            return "Unknown shape"


def analyze_nested(data: object) -> str:
    """Analyze nested structures using pattern matching."""
    match data:
        case [["pair", x, y], ["pair", a, b]]:
            # Match nested structure
            return f"Two pairs: ({x},{y}) and ({a},{b})"
        case [["single", val]]:
            return f"Single value: {val}"
        case _:
            return "Unknown structure"


def check_value(val: object) -> str:
    """Check value using OR patterns."""
    match val:
        case 0 | 1 | 2:
            # Match any of these values
            return "small"
        case 3 | 4 | 5:
            return "medium"
        case _:
            return "large"


def process_range(data: Any) -> str:
    """Process range data with AS patterns."""
    match data:
        case [x, y] as pair if x < y:
            # Capture the entire matched value with 'as'
            return f"Valid range: {pair}"
        case [x, y]:
            return f"Invalid range: [{x}, {y}]"
        case _:
            return "Not a pair"


def process_json_data(data: object) -> str:
    """Process JSON-like dictionary data with pattern matching.

    This shows how to match against dictionary structures.
    """
    match data:
        case {"type": "user", "name": name, "age": age}:
            return f"User {name} is {age} years old"
        case {"type": "user", "name": name}:
            # Match user without age
            return f"User {name} with unknown age"
        case {"type": "product", "name": name, "price": price} if price > 0:
            return f"Product {name} costs ${price}"
        case {"type": "product", "name": name, "price": price}:
            return f"Product {name} has invalid price: {price}"
        case {"type": type_name}:
            # Match any dict with a type key
            return f"Unknown type: {type_name}"
        case _:
            return "Invalid data"


def verify_literal_and_sequence_patterns() -> None:
    """Verify literal values, status codes, tuples, and sequence matching."""
    # Test literal pattern matching
    assert classify_number(0) == "zero"
    assert classify_number(1) == "one"
    assert classify_number(2) == "two"
    assert classify_number(5) == "other"
    assert classify_number(100) == "other"

    # Test HTTP status classification
    assert classify_http_status(200) == "OK"
    assert classify_http_status(404) == "Not Found"
    assert classify_http_status(999) == "Unknown Status"
    assert classify_http_status(201) == "Created"
    assert classify_http_status(400) == "Bad Request"
    assert classify_http_status(401) == "Unauthorized"
    assert classify_http_status(500) == "Internal Server Error"

    # Test sequence pattern matching with tuples
    assert process_point((0, 0)) == "Origin"
    assert process_point((0, 5)) == "Y-axis at y=5"
    assert process_point((3, 0)) == "X-axis at x=3"
    assert process_point((4, 7)) == "Point at (4, 7)"
    assert process_point("invalid") == "Not a valid 2D point"

    # Test sequence pattern matching with lists
    assert analyze_sequence([]) == "Empty list"
    assert analyze_sequence([42]) == "Single element: 42"
    assert analyze_sequence([1, 2]) == "Pair: 1, 2"
    assert analyze_sequence([1, 2, 3, 4]) == "First: 1, Rest: [2, 3, 4]"
    assert analyze_sequence("not a list") == "Not a list"


def verify_guard_and_class_patterns() -> None:
    """Verify guard expressions and class-based object decomposition."""
    # Test pattern matching with guards
    assert process_command(["quit"]) == "Quitting"
    assert process_command(["go", "north"]) == "Going north"
    assert process_command(["go", "west"]) == "Going west"
    assert process_command(["go", "up"]) == "Invalid direction: up"
    assert process_command(["take", "key"]) == "Taking key"
    assert process_command(["take", "coin", 5]) == "Taking 5 coin"
    assert process_command(["take", "coin", 0]) == "Invalid quantity: 0"
    assert process_command(["take", "coin", -1]) == "Invalid quantity: -1"
    assert process_command(["jump"]) == "Unknown command"

    # Test class pattern matching
    p1 = Point(0, 0)
    assert describe_shape(p1) == "Point at origin"

    p2 = Point(0, 5)
    assert describe_shape(p2) == "Point on Y-axis at 5"

    p3 = Point(3, 0)
    assert describe_shape(p3) == "Point on X-axis at 3"

    p4 = Point(5, 5)
    assert describe_shape(p4) == "Point on diagonal at (5, 5)"

    p5 = Point(3, 7)
    assert describe_shape(p5) == "Point at (3, 7)"

    c1 = Circle(Point(0, 0), 10)
    assert describe_shape(c1) == "Circle at origin with radius 10"

    c2 = Circle(Point(5, 5), 3)
    assert describe_shape(c2) == "Circle at (5, 5) with radius 3"

    # Test unknown shape
    assert describe_shape("unknown") == "Unknown shape"


def verify_mapping_and_advanced_patterns() -> None:
    """Verify dictionary structural patterns, OR patterns, AS patterns, and nesting."""
    # Test dictionary pattern matching
    user1 = {"type": "user", "name": "Alice", "age": 30}
    assert process_json_data(user1) == "User Alice is 30 years old"

    user2 = {"type": "user", "name": "Bob"}
    assert process_json_data(user2) == "User Bob with unknown age"

    product1 = {"type": "product", "name": "Laptop", "price": 999}
    assert process_json_data(product1) == "Product Laptop costs $999"

    product2 = {"type": "product", "name": "Free Sample", "price": 0}
    assert process_json_data(product2) == "Product Free Sample has invalid price: 0"

    unknown = {"type": "order"}
    assert process_json_data(unknown) == "Unknown type: order"

    invalid = {"data": "something"}
    assert process_json_data(invalid) == "Invalid data"

    # Pattern matching with OR patterns
    assert check_value(0) == "small"
    assert check_value(2) == "small"
    assert check_value(3) == "medium"
    assert check_value(10) == "large"

    # Pattern matching with AS patterns (walrus-like capture)
    assert process_range([1, 5]) == "Valid range: [1, 5]"
    assert process_range([5, 1]) == "Invalid range: [5, 1]"
    assert process_range("not a pair") == "Not a pair"

    # Nested pattern matching
    assert analyze_nested([["pair", 1, 2], ["pair", 3, 4]]) == "Two pairs: (1,2) and (3,4)"
    assert analyze_nested([["single", 42]]) == "Single value: 42"
    assert analyze_nested("invalid") == "Unknown structure"


def main() -> None:
    # 1. Literal and sequence pattern matching
    verify_literal_and_sequence_patterns()

    # 2. Guard conditions and class pattern matching
    verify_guard_and_class_patterns()

    # 3. Dictionary patterns, OR patterns, AS patterns, and nested structures
    verify_mapping_and_advanced_patterns()

    # Pattern matching is particularly useful for parsing and handling
    # structured data like API responses, configuration files, or
    # abstract syntax trees in compilers/interpreters


if __name__ == "__main__":
    main()