Guards and Or-Patterns

## The syntax Python's `match` statement, added in 3.10 by PEP 634, matches a subject against a series of `case` clauses. Each `case` carries a **pattern**, and may optionally end with a **guard**: the keyword `if` followed by any expression. ```python match point: case (x, y) if x == y: print("on the diagonal") case (x, y): print("off the diagonal") ``` The guard is not part of the pattern. It is a plain expression evaluated for truthiness, exactly like the condition of an ordinary `if` statement. ## The order of operations For each `case`, in source order, the interpreter does two things: 1. **Try the pattern.** If it does not match, the guard is never evaluated at all and matching moves to the next `case`. 2. **If the pattern matched, evaluate the guard.** By this point every capture name in the pattern has been bound, so the guard can read them. A truthy result commits to that case's body and the whole `match` ends there; a falsy result rejects this case and matching continues with the next one. That ordering is the single most important fact about guards, and it is what makes them useful. A pattern can only test *shape* and equality against constants; it cannot express `x > y`, `len(s) > 8`, or `value in allowed`. The guard runs late enough that the destructured pieces already exist as names, so relational and computed conditions become easy: ```python match command.split(): case [verb, arg] if verb in {"open", "close"}: ... ``` ## What a guard may contain Anything a normal expression may contain: function calls, comprehensions, chained comparisons, a walrus assignment. Two consequences follow. First, **a guard can have side effects**, and because matching walks the cases in order, a guard belonging to an earlier case runs even though that case ultimately loses. If two overlapping cases both call the same expensive helper in their guards, that helper runs twice for one subject. Keep guards cheap and pure where you can. Second, **names bound by a pattern stay bound even when its guard rejects the case**. Pattern matching binds as it goes and does not roll back, so after a failed guard the captured names are still visible in the enclosing scope — with values from a case that did not win. Never read a capture name outside the body of the case that bound it. ## What a guard can see The guard is evaluated in the ordinary scope of the surrounding code, so it can read anything a normal expression could: locals, globals, closure variables, `self`, and — crucially — the names this pattern has just bound. What it cannot do is *introduce* a pattern binding. A guard is a filter, not a matcher: it decides yes or no about a case whose destructuring has already happened. If you find yourself wanting a guard to reach further into the subject, the right move is usually a richer pattern rather than a longer guard. ## Guards on other pattern kinds A guard may follow any pattern, including the wildcard. `case _ if retries > 3:` is a legal, conditional catch-all — and note that it is no longer irrefutable, so a later `case` after it is still reachable. A guard may also follow an or-pattern; there is one guard per `case`, evaluated once after whichever alternative matched, not once per alternative. Combined with an `as` pattern, `case ("GET" | "HEAD") as verb if verb in allowed:` reads naturally: alternatives match, `verb` binds, guard decides. ## Guards versus an `if` in the body You can always push the condition into the body instead: ```python case (x, y): if x == y: ... ``` The behaviour differs in an important way. A guard that fails **falls through to the remaining cases**; an `if` inside the body does not — the `match` has already committed to that case, and the other cases are dead. Use a guard when a failed condition should let a later, more general case handle the subject; use a body `if` when the case is definitely the right handler and the condition is only an internal detail. ## Style Guards are best kept to a short, obviously-pure boolean expression over names the pattern just bound. Long guards are a signal that the discrimination belongs in the pattern (or that the code wants a plain `if`/`elif` chain instead of a `match`). None of this changed between 3.10 and 3.14: guards behave the same on every version that has `match`.