Skip to main content
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:
Sub-pattern Capture (using as):

​
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.
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.
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.
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.
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.
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.
Tired of Poor Python Skills? Fix That With Deep Grasping!Learn More