> ## 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 Capture Pattern
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:**
```python theme={"dark"}
match subject:
case identifier:
pass
```
**Sub-pattern Capture (using `as`):**
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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`.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```python theme={"dark"}
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.
```
Tired of Poor Python Skills? Fix That With Deep Grasping!
Learn More
