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 capture pattern is a structural pattern matching construct in Python that binds a matched subject, or a specific sub-component of that subject, to a variable name. When a capture pattern succeeds, it assigns the matched value to the specified bare identifier, making that value accessible within the enclosing scope of the match statement.

​
Syntax

A capture pattern can be used as a standalone identifier or combined with other patterns using the as keyword. Standalone Capture: 
match subject:
    case identifier:
        pass
Sub-pattern Capture (using as): 
match subject:
    case [1, 2] as identifier:
        pass

​
Technical Mechanics

Bare Identifiers vs. Value Patterns A fundamental rule of Python pattern matching is the distinction between bare names and dotted names. A bare identifier (e.g., case CONSTANT:) is always treated as a capture pattern; it will capture the subject and overwrite (rebind) any existing variable with that name in the local scope. Because match blocks do not create a new local scope, the original value is permanently replaced. To compare a subject against an existing value without capturing it, a dotted name (e.g., case config.CONSTANT:) must be used. Dotted names are evaluated as value patterns, not capture patterns. 
match subject:
    case config.CONSTANT:
        # Compares the subject to the value of config.CONSTANT; does not capture
        pass
    case CONSTANT:
        # Captures the subject, overwriting any existing 'CONSTANT' variable
        pass
Success, Irrefutability, and Guards Patterns in Python do not evaluate to boolean values; they either succeed or fail to match. A standalone capture pattern always succeeds. Because it acts as an unconditional catch-all, a bare capture pattern without a guard is an irrefutable pattern. The Python interpreter enforces that an irrefutable case block must be the final clause in a match statement; placing any case clauses after it results in a SyntaxError. However, if the case clause includes a guard, the block becomes refutable. A refutable capture pattern can legally be followed by other case clauses. 
match subject:
    case x if x > 0:
        # Refutable due to the guard; subsequent cases are allowed
        pass
    case x:
        # Irrefutable; must be the final case clause
        pass
Binding Restrictions A capture pattern cannot bind the same variable name more than once within a single pattern. Attempting to capture multiple elements into the same identifier raises a SyntaxError. 
match subject:
    case [x, y]:
        # Valid: binds two distinct identifiers
        pass
    # case [x, x]: 
        # Invalid: raises SyntaxError (multiple assignments to name 'x')
Capture Patterns in OR Patterns (|) When capture patterns are used within an OR pattern, Python requires that every alternative in the OR pattern binds the exact same set of variable names. If an identifier is captured in one alternative, it must be captured in all of them. 
match subject:
    case [1, x] | [x, 2]:
        # Valid: 'x' is bound regardless of which alternative succeeds
        pass
    # case 1 | x:
        # Invalid: raises SyntaxError ('x' is not bound if the subject is 1)
The as Keyword When a pattern requires type checking or specific structural validation before capturing, the as keyword binds the successfully validated node to a name. This enforces a structural match while simultaneously capturing the exact value that satisfied the sub-pattern. 
match subject:
    case [str(), int() as status_code]:
        # 'status_code' captures the second element only if it is an integer 
        # and the first element is a string.
        pass
The Wildcard Exception The underscore _ is a special identifier in structural pattern matching. While it always succeeds like a standalone capture pattern, it is technically a wildcard pattern. It matches any subject but explicitly does not bind the value to the name _. Scoping Rules and Guard Evaluation Variables bound via capture patterns do not have block-level scope. Following standard Python scoping rules, an identifier bound in a case clause leaks into the enclosing scope of the match statement. The Python interpreter handles bindings internally during structural evaluation. If a pattern fails structurally at any point, no variables from that pattern are bound to the local scope. The entire structural pattern must succeed for the bindings to be committed. However, variable binding occurs before a guard (if condition) is evaluated. If a pattern successfully matches structurally and binds variables, but the guard evaluates to False, the case block will not execute, yet the bound variables are still initialized and leak into the enclosing scope. 
subject = [1, 2]
match subject:
    case [x, y] if x > 5:
        pass
    case _:
        pass


# x is now bound to 1 and y is bound to 2 in the enclosing scope.

# The structural match [x, y] succeeded, committing the bindings, 

# even though the guard (x > 5) subsequently failed.
Master Python with Deep Grasping Methodology!Learn More