Mapping Pattern

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.

​

Syntax

subject = {"literal_key": "value", "extra_key": "extra_value"}

match subject:
    case {"literal_key": value_pattern, **rest_binding}:
        pass

​

Core Mechanics

1. Type Validation: The pattern checks if the subject’s class has the Py_TPFLAGS_MAPPING flag set at the C level. This includes built-in types like dict and classes that explicitly inherit from collections.abc.Mapping. Classes registered merely as virtual subclasses via collections.abc.Mapping.register() will fail mapping pattern matching because they lack this C-level flag, even though isinstance(subject, Mapping) evaluates to True.
2. Key Presence: The pattern checks if all keys defined in the case statement exist in the subject.
3. Value Destructuring: If the keys exist, the pattern evaluates the corresponding values against the provided value_pattern.
4. Partial Matching: Unlike sequence patterns, mapping patterns are partial by default. If the subject contains keys not specified in the pattern, the match will still succeed.

​

Syntax Variations and Visualization

subject = {"status": 200, "data": {"items": [1, 2]}, "timestamp": 1630000000}

match subject:
    case {"status": 200, "data": payload}:
        # Matches if subject is a mapping containing "status" == 200 
        # and a "data" key. The value of "data" is bound to 'payload'.
        print(payload)  # Output: {'items': [1, 2]}

subject = {"user": {"id": 42, "credentials": {"role": "admin"}}, "active": True}

match subject:
    case {"user": {"id": int(uid), "credentials": {"role": "admin"}}}:
        # Matches if subject["user"]["id"] is an integer (bound to uid)
        # and subject["user"]["credentials"]["role"] is exactly "admin".
        print(uid)  # Output: 42

subject = {"route": "/home", "page": 1, "sort": "asc"}

match subject:
    case {"route": "/home", **query_params}:
        # Matches if "route" is "/home". 
        # All other keys in the mapping are packed into the 'query_params' dict.
        print(query_params)  # Output: {'page': 1, 'sort': 'asc'}

​

Technical Constraints

• Key Restrictions: Keys within the pattern must be literal patterns (e.g., strings, numbers, booleans, None) or value patterns (e.g., Enum members accessed via dotted names). You cannot use bare variables to dynamically match keys, as bare variables are treated as capture patterns.

class Config:
    NAME_KEY = "name"

subject = {"name": "Alice"}
dynamic_key = "name"

# INVALID: Cannot use a bare variable as a key pattern.
# This raises a SyntaxError at compile time.
# match subject:
#     case {dynamic_key: value}: 
#         pass

# VALID: Using a dotted name constant
match subject:
    case {Config.NAME_KEY: value}:
        print(value)  # Output: Alice

# VALID: Using a literal string
match subject:
    case {"name": value}:
        print(value)  # Output: Alice

• Duplicate Keys: Defining duplicate keys within a single mapping pattern raises a SyntaxError at compile time.
• Single Unpacking: Only one ** binding is permitted per mapping pattern, and it must be the final item in the pattern definition.
• No **_ Wildcard: While **rest is valid for capturing remaining items, using **_ to explicitly ignore remaining items is a SyntaxError. Because mapping patterns are partial by default, **_ is redundant.