How to use match case in Python

Python's match-case statement offers a powerful way to handle complex conditional logic. It provides a more readable and structured alternative to long if-elif-else chains for modern developers.

You'll explore fundamental techniques, practical tips, and real-world applications. This article also covers debugging advice to help you master the match-case statement for cleaner, more efficient code.

Basic usage of match case

day = "Monday"
match day:
case "Monday":
print("Start of the work week")
case "Friday":
print("End of the work week")
case _:
print("Some other day")--OUTPUT--Start of the work week

The match statement evaluates the subject, which is the day variable. Each subsequent case statement then compares its pattern to the variable's value. When a match is found, like case "Monday", its code block runs, and the entire statement is exited.

Notice the final case _. This is a wildcard pattern that acts as a catch-all. It’s crucial for handling any values that don't fit the specific cases you've defined, preventing your program from failing silently if an unexpected value appears.

Pattern matching fundamentals

The match statement's power extends beyond simple value checks, letting you group cases, capture values, and add conditional if guards for more complex logic.

Matching multiple values with case

day = "Saturday"
match day:
case "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday":
print("Weekday")
case "Saturday" | "Sunday":
print("Weekend")--OUTPUT--Weekend

You can combine several patterns into a single case by using the | operator, which functions like an "or". It’s a clean way to group related conditions without writing a separate case for each value.

• The pattern "Saturday" | "Sunday" will match if the day variable is either "Saturday" or "Sunday".
• This approach simplifies your logic, making it more readable than long if statements with multiple or conditions.

Extracting values with pattern matching

command = ("move", 10, 20)
match command:
case ("move", x, y):
print(f"Moving to position ({x}, {y})")
case ("quit",):
print("Quitting the program")
case _:
print("Unknown command")--OUTPUT--Moving to position (10, 20)

Pattern matching can also deconstruct data structures like tuples. The pattern case ("move", x, y) doesn't just check for equality; it verifies the structure of the command tuple. It checks that the first element is "move" and that two other elements follow.

• When a match occurs, the values from the tuple are captured and assigned to the variables in the pattern. Here, x becomes 10 and y becomes 20.

This allows you to extract and use parts of your data directly within the case block, offering a much cleaner alternative to manual indexing.

Using wildcards and if guards

point = (10, 20)
match point:
case (x, y) if x == y:
print(f"Point ({x}, {y}) is on the diagonal")
case (0, y):
print(f"Point is on the y-axis at y={y}")
case (x, 0):
print(f"Point is on the x-axis at x={x}")
case (x, y):
print(f"Point is at coordinates ({x}, {y})")--OUTPUT--Point is at coordinates (10, 20)

You can attach an if guard to a case for more refined logic. The pattern case (x, y) if x == y: demonstrates this well—it only matches when the tuple's elements are equal, letting you check conditions beyond just the data's structure.

• The order of your cases is crucial. Python stops at the first successful match, so you should place more specific patterns like case (0, y) before general ones.
• The final case (x, y) acts as a catch-all, capturing any two-element tuple that didn't fit the more specialized conditions above it.

Advanced pattern matching techniques

With the fundamentals covered, you can now apply match-case to more intricate scenarios involving sequences, mappings, class patterns, and even the := walrus operator.

Matching with sequences and unpacking

values = [1, 2, 3, 4, 5]
match values:
case [first, second, *rest]:
print(f"First: {first}, Second: {second}, Rest: {rest}")
case [single]:
print(f"Only one item: {single}")
case []:
print("Empty list")--OUTPUT--First: 1, Second: 2, Rest: [3, 4, 5]

You can use match-case to unpack sequences like lists, which is especially handy for handling items of varying lengths. The star operator, *, is the key here. It lets you capture multiple items from a sequence into a new list.

• The pattern case [first, second, *rest] matches any list with at least two elements. It assigns the first two items to first and second, while *rest gathers all remaining elements.
• This makes it easy to process the start of a sequence while keeping the rest intact for later use, without manual slicing.

Matching with mappings and class patterns

data = {"name": "Alice", "age": 30}
match data:
case {"name": str(name), "age": int(age)} if age >= 18:
print(f"{name} is an adult")
case {"name": str(name)}:
print(f"{name}'s age is unknown or they're a minor")
case _:
print("Unknown data format")--OUTPUT--Alice is an adult

The match-case statement is also powerful for handling dictionaries, or mappings. You can check for specific keys, validate value types, and capture data all in one go.

• The pattern {"name": str(name), "age": int(age)} confirms the dictionary has both keys and captures their values into the name and age variables.
• The attached if guard lets you run checks on the captured values, like ensuring age >= 18, making your logic more precise.

Using the := walrus operator in pattern matching

command = "SUM 10 20 30"
match command.split():
case ["SUM", *values] if all(v.isdigit() for v in values) and (nums := [int(v) for v in values]):
print(f"Sum of {nums} is {sum(nums)}")
case ["AVERAGE", *values] if (nums := [float(v) for v in values if v.replace('.', '', 1).isdigit()]):
print(f"Average of {nums} is {sum(nums)/len(nums)}")--OUTPUT--Sum of [10, 20, 30] is 60

The walrus operator, :=, streamlines your if guards by letting you assign a value to a variable within the expression itself. This is especially useful for validating and transforming data in a single step, which avoids redundant operations.

• In the case ["SUM", *values] pattern, the expression nums := [int(v) for v in values] both creates a list of integers and assigns it to the nums variable.
• Because this assignment happens inside the guard, you can immediately use the new nums variable in the main body of the case block without recalculating it.

Move faster with Replit

Replit is an AI-powered development platform that transforms natural language into working applications. Describe what you want to build, and Replit Agent creates it—complete with databases, APIs, and deployment.

For the match-case patterns we've explored, Replit Agent can turn them into production-ready tools:

• Build a command-line interpreter that parses user inputs like move x y or quit.
• Create a data validation service that processes JSON payloads, checking for required keys and value types.
• Deploy a string-based calculator that accepts commands like SUM 10 20 30 and performs the correct operation.

Describe your app idea, and Replit Agent writes the code, tests it, and fixes issues automatically. Try Replit Agent to bring your concepts to life.

Common errors and challenges

Navigating match-case is mostly straightforward, but a few common errors can lead to unexpected behavior in your code.

• Forgetting the case _ wildcard: If you omit the catch-all case _ pattern, your program will raise a MatchError whenever it encounters a value that doesn't fit any of your specific cases. This can easily crash your script, so it's best to include it to handle unexpected inputs gracefully.
• Incorrectly ordering case patterns: The match statement stops checking as soon as it finds a match. A common mistake is placing a general pattern before a more specific one. For instance, if case (x, y) comes before case (0, y), the second, more specific pattern will never be reached. Always order your cases from most specific to most general.
• Failing to validate types: Pattern matching checks the structure of your data, but it doesn't automatically check the types of the values within it. If you don't explicitly use class patterns like int(age), you might capture a string where you expect an integer, leading to runtime errors later when you try to use the variable.

Forgetting the case _ wildcard for handling unexpected values

Forgetting the case _ wildcard is a common pitfall. Without this catch-all pattern, your program can't handle unexpected values. It will raise a MatchError and crash. The following code demonstrates what happens when an unhandled value appears.

status_code = 500 # Server error
match status_code:
case 200:
print("Success")
case 301:
print("Permanent redirect")
case 404:
print("Not found")

Since the status_code is 500, it doesn't match any specific cases. With no wildcard to catch it, the program raises a MatchError. The corrected version below shows how to handle these situations gracefully.

status_code = 500 # Server error
match status_code:
case 200:
print("Success")
case 301:
print("Permanent redirect")
case 404:
print("Not found")
case _:
print(f"Unhandled status code: {status_code}")

The corrected code adds a case _ wildcard, which acts as a safety net. It catches any status_code that isn't explicitly handled, like 500, preventing a MatchError and allowing the program to continue running. You should always include this catch-all pattern when dealing with unpredictable data, such as API responses or user input, to make your code more robust.

Incorrectly ordering case patterns from general to specific

The order of your case patterns is critical because Python stops at the first match. Placing a general pattern, like [*items], before a more specific one, such as [1, 2, 3], means the specific case will never be evaluated. The following code demonstrates this issue.

value = [1, 2, 3]
match value:
case [*items]:
print(f"List with {len(items)} items")
case [1, 2, 3]:
print("Exact match: [1, 2, 3]")
case [1, *rest]:
print(f"List starting with 1, rest: {rest}")

The broad case [*items] pattern matches the list first, so the more specific case [1, 2, 3] is never reached. Python stops evaluating at the first successful match. The corrected code below shows the proper ordering.

value = [1, 2, 3]
match value:
case [1, 2, 3]:
print("Exact match: [1, 2, 3]")
case [1, *rest]:
print(f"List starting with 1, rest: {rest}")
case [*items]:
print(f"List with {len(items)} items")

The corrected code works by placing the most specific pattern, [1, 2, 3], at the top. Since Python evaluates cases in order and stops at the first match, general patterns must always come last.

• This prevents a broad pattern like [*items] from "swallowing" a more detailed one.
• Always check your case order when patterns might overlap, especially with sequences of varying lengths or structures.

Failing to validate types in pattern matching

Pattern matching is great at checking structure, but it doesn't automatically validate data types. This can cause a TypeError when you try to perform an operation, like adding two strings when you expected numbers. The following code demonstrates this common pitfall.

data = {"id": "1234", "count": "42"}
match data:
case {"id": id, "count": count}:
result = id + count # Will fail if expecting numbers
print(f"Total: {result}")

The pattern captures id and count as strings, so the + operator concatenates them into "123442" instead of adding them. The corrected code below shows how to validate the types directly within the pattern.

data = {"id": "1234", "count": "42"}
match data:
case {"id": str(id_str), "count": str(count_str)}:
result = int(id_str) + int(count_str)
print(f"Total: {result}")

The corrected code captures the dictionary values as strings, like str(id_str), and then explicitly converts them to integers using int() before performing the addition. This ensures you're working with numbers, not strings, which prevents unexpected concatenation.

• You should always be mindful of this when your patterns handle data from sources like JSON or user input, where values are often strings by default.

Real-world applications

Now that you can sidestep common errors, you're ready to apply match-case to complex, real-world tasks like parsing API data and command-line inputs.

Processing API responses with match case

The match-case statement excels at deconstructing API responses, which often return different data structures for success and error states.

api_response = {"status": "success", "data": {"users": ["Alice", "Bob"]}}

match api_response:
case {"status": "success", "data": data}:
print(f"Successfully retrieved data: {data}")
case {"status": "error", "message": msg}:
print(f"Error occurred: {msg}")
case {"status": status}:
print(f"Unknown status: {status}")
case _:
print("Invalid response format")

This example shows how you can use match-case to safely parse dictionaries that might have different keys. The code inspects the api_response dictionary, trying to match its structure against a series of ordered patterns.

• The first case looks for a successful response by matching {"status": "success"} and captures the value of the "data" key.
• If that fails, it checks for an error structure containing a "message" key.
• The final case _ acts as a safety net, catching any response that doesn't fit the expected formats.

Building a command-line interface parser with match case

Similarly, match-case excels at parsing command-line inputs, where you can easily unpack a list of arguments to identify specific commands.

command = ["git", "commit", "-m", "Initial commit"]

match command:
case ["git", "push", *args]:
print(f"Pushing to remote repository with args: {args}")
case ["git", "commit", "-m", message]:
print(f"Committing changes with message: {message}")
case ["git", "status"]:
print("Checking repository status")
case ["git", cmd, *_]:
print(f"Git command not implemented: {cmd}")
case [cmd, *args]:
print(f"Unknown command: {cmd} with args: {args}")

This code deconstructs a list of strings that represents a command-line instruction. Instead of manually checking list indices, you declare the exact structure you expect to find. The pattern ["git", "commit", "-m", message] both validates the command's format and extracts the commit message into the message variable in a single, readable step.

• This approach effectively unpacks the list, assigning specific parts to variables for immediate use.
• Wildcards like *args and *_ add flexibility, capturing any number of remaining arguments for different commands.

Get started with Replit

Turn your match-case skills into a real tool. Tell Replit Agent to "build a command-line calculator that parses string inputs" or "create a tool that validates JSON user data based on key-value pairs".

Replit Agent writes the code, tests for errors, and deploys the app, handling the entire development lifecycle for you. Start building with Replit.