Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python OR Pattern: Combining Match Cases

Combine multiple cases in Python's match statement with the OR pattern using the | operator. Learn syntax, capture rules, guards, and common pitfalls.

~3 min readPython
#Python#pattern matching#match statement#OR operator
Illustration of Python OR pattern combining two match cases with a vertical bar symbol

Python's match statement supports OR patterns through the | operator. An OR pattern combines several patterns into one case, so different values can share the same body. This feature is part of structural pattern matching, introduced in Python 3.10.

python
match command: case 'start' | 'run': launch() case 'stop' | 'halt': shutdown()

Here, 'start' and 'run' both trigger launch(), while 'stop' and 'halt' trigger shutdown().

Basic Syntax of the OR Pattern

The OR pattern uses | between two or more alternatives. The whole group is treated as a single case. The subject is matched against each alternative in order, and the first successful match determines the outcome.

python
match value: case 0 | 1: print('binary digit') case 2 | 4 | 6 | 8: print('even digit') case _: print('other')

You can chain more than two alternatives.

Matching Literal Values with OR

The most common use is combining literal values: strings, numbers, booleans, or None.

python
def handle_status(status): match status: case 200 | 201 | 204: print('success') case 400 | 404 | 500: print('error') case _: print('unknown')

Each alternative must be a valid pattern. A bare name is not a literal comparison; it is a capture pattern. To match a variable's value, use a guard or a value pattern that uses a dotted name, such as Config.start.

Combining Class Patterns

OR patterns also work with class patterns, letting you combine different types or attribute values in one case.

python
class Point: def __init__(self, x, y): self.x = x self.y = y match obj: case Point(x=0, y=0) | Point(x=0, y=1): print('origin or adjacent') case Point(x=0, y=_): print('on y-axis') case _: print('other')

When you combine class patterns, all alternatives must bind the same set of names. If one alternative binds x and another binds y, Python rejects the pattern because the body could not rely on a consistent binding.

Using OR with Capture Patterns and Guards

A capture pattern binds the matched value to a name. When you use capture patterns in an OR pattern, each alternative must bind the same names.

python
match value: case [x] | [x, _]: print(f'one or two elements, first is {x}')

Both alternatives bind x, so the body can use it. _ is a wildcard and does not bind a name.

Guards are evaluated after the pattern itself matches. Use or and parentheses for boolean logic in a guard, not |:

python
match point: case (x, y) if (x > 0) or (y > 0): print('at least one coordinate is positive')

The expression x > 0 | y > 0 would not mean what you expect. Because | binds more tightly than comparison operators, Python parses it as x > (0 | y) > 0, not (x > 0) or (y > 0).

Common Pitfalls and Limitations

A bare name in a pattern is a capture pattern, not a value lookup. A single case allowed: would always match and bind the subject to allowed; it would not compare against the variable's value. Combining it with a literal is also invalid, not a comparison with allowed:

python
allowed = 'start' match command: case allowed | 'run': launch()

The OR pattern's alternatives bind different names (allowed binds, 'run' does not), so Python rejects it. To compare against a variable, use a guard:

python
allowed = 'start' match command: case value if value == allowed or value == 'run': launch()

Or, when the value is a class attribute, use a value pattern:

python
class Allowed: start = 'start' match command: case Allowed.start | 'run': launch()

Similarly, OR patterns must bind consistent names. case [x | y] is invalid because the two alternatives bind different names; use a guard or restructure the logic if you need to distinguish those cases.

Maintainability and Alternative Approaches

OR patterns let you avoid repeating the same body for several values. With a small number of alternatives, the pattern is easy to read. If the set of values is large or changes frequently, a dictionary mapping may be easier to maintain:

python
handlers = { 200: handle_success, 201: handle_success, 204: handle_success, 400: handle_error, }

Use OR patterns when the alternatives are few and the action is identical; use a mapping or separate cases when the logic becomes dynamic or each alternative needs different handling.

When to Prefer Separate Cases Over OR Patterns

Separate case clauses are clearer when alternatives need different guards or bind different names.

python
match value: case 0: print('zero') case 1: print('one') case _: print('other')

If the actions are identical and the alternatives are simple, OR patterns are more concise. If the actions differ, or an OR pattern would need inconsistent variable bindings, use separate cases.

Finally, remember that | inside a pattern is the OR-pattern separator, while | inside a guard expression is bitwise OR. For boolean conditions in guards, use or with parentheses.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.