95

I'm trying to understand the new structural pattern matching syntax in Python 3.10. I understand that it is possible to match on literal values like this:

def handle(retcode):
    match retcode:
        case 200:
            print('success')
        case 404:
            print('not found')
        case _:
            print('unknown')

handle(404)
# not found

However, if I refactor and move these values to module-level variables, it results in an error because the statements now represent structures or patterns rather than values:

SUCCESS = 200
NOT_FOUND = 404

def handle(retcode):
    match retcode:
        case SUCCESS:
            print('success')
        case NOT_FOUND:
            print('not found')
        case _:
            print('unknown')

handle(404)
#  File "<ipython-input-2-fa4ae710e263>", line 6
#    case SUCCESS:
#         ^
# SyntaxError: name capture 'SUCCESS' makes remaining patterns unreachable

Is there any way to use the match statement to match values that are stored within variables?

2
  • My reading of PEP-635 suggests you need a value pattern, which appears to be defined as a dotted name. I'm not sure why you would get a syntax error here, though, as SUCCESS should be interpreted as a capture pattern.
    – chepner
    Commented Feb 11, 2021 at 17:21
  • 4
    "an unqualified name (i.e. a bare name with no dots) will be always interpreted as a capture pattern"
    – jonrsharpe
    Commented Feb 11, 2021 at 18:06

6 Answers 6

74

If the constant you're testing against is a dotted name, then it should be treated as a constant instead of as the name of the variable to put the capture in (see PEP 636 # Matching against constants and enums):

class Codes:
    SUCCESS = 200
    NOT_FOUND = 404

def handle(retcode):
    match retcode:
        case Codes.SUCCESS:
            print('success')
        case Codes.NOT_FOUND:
            print('not found')
        case _:
            print('unknown')

Although, given how python is trying to implement pattern-matching, I think that for situations like this it's probably safer and clearer code to just use an if/elif/else tower when checking against constant values.

3
  • 5
    I think this is only less clear because no body is used to match statements yet. I suspect the implementation can perform pattern matching more efficiently than the linear search imposed by an if tower.
    – chepner
    Commented Feb 11, 2021 at 17:26
  • 5
    @chepner given the specification it can't be faster than the linear if tower (and that's how it's implemented currently). the cases must be evaluated in order due to precedence rules Commented Feb 12, 2021 at 1:32
  • 5
    Can you elaborate on "given how python is trying to implement pattern-matching"? What about the how would make it less safe or less clear than if/else?
    – theberzi
    Commented Feb 13, 2021 at 19:20
49

Hopefully I can help shed some light on why bare names work this way here.

First, as others have already noted, if you need to match values as part of your patterns, you can do so by:

  • Matching supported literals, like numbers, strings, booleans, and None
  • Matching qualified (dotted) names
  • Using additional tests in guards (which are separated from patterns by if)

I fear that we (the PEP authors) probably made a small error by including this toy snippet in an early tutorial... it's since gone a bit viral. Our goal was to lead with the simplest possible example of pattern matching, but we instead seem to have also created a confusing first impression for many (especially when repeated without context).

The most overlooked word in the title of these PEPs is "structural". If you're not matching the structure of the subject, structural pattern matching probably isn't the right tool for the job.

The design of this feature was driven by destructuring (like iterable unpacking on the LHS of assignments, but generalized for all objects), which is why we made it very easy to perform the core functionality of extracting out parts of an object and binding them to names. We also decided that it would also be useful to allow programmers to match on values, so we added those (with the condition that when the values are named, they must be qualified with a dot, in order to distinguish them from the more common extractions).

Python's pattern matching was never really designed with the intent of powering C-style switch statements like this; that's been proposed for Python (and rejected) twice before, so we chose to go in a different direction. Besides, there is already one obvious way to switch on a single value, which is simpler, shorter, and works on every version of Python: a good-ol' if/elif/else ladder!

SUCCESS = 200
NOT_FOUND = 404

def handle(retcode):
    if retcode == SUCCESS:
        print('success')
    elif retcode == NOT_FOUND:
        print('not found')
    else:
        print('unknown')

handle(404)

(If you're really concerned about performance or need an expression, dispatching from a dictionary is also a fine alternative.)

3
  • 8
    This answer clarified a lot to me. I don't know if PEPs are amendable once final, but I think a clearer point on "why this is not a switch/case statement and should not be used as one" could avoid a lot of confusion. At least the "what's new in Python" docs can be amended still for sure :)
    – gerrit
    Commented Mar 3, 2021 at 9:44
  • 2
    one option would be to have a syntax like case =SUCCESS: or similar, where the = denotes that the numeric value of SUCCESS should be used for pattern matching (or maybe case .SUCCESS to indicate that SUCCESS should be treated as a "dotted" variable).
    – Linus
    Commented Dec 11, 2022 at 11:29
  • 4
    Adding on to gerrit's statement, even in the official Python docs, it says match is for pattern matching, not structural pattern matching docs.python.org/3/reference/…. Commented Jan 2, 2023 at 5:53
25

Aside from using literal values, the Value Patterns section of PEP 635 mentions the use of dotted names or the use of guards. See below for comparison:

Literal values

def handle(code):
    match code:
        case 200:
            print('success')
        case 404:
            print('not found')
        case _:
            print('unknown')

References:

Dotted names

Any dotted name (i.e. attribute access) is interpreted as a value pattern.

class StatusCodes:
    OK = 200
    NOT_FOUND = 404

def handle(code):
    match code:
        case StatusCodes.OK:
            print('success')
        case StatusCodes.NOT_FOUND:
            print('not found')
        case _:
            print('unknown')

References:

Guards

[A] guard is an arbitrary expression attached to a pattern and that must evaluate to a "truthy" value for the pattern to succeed.

SUCCESS = 200
NOT_FOUND = 404

def handle(code):
    match code:
        case status if status == SUCCESS:
            print('success')
        case status if status == NOT_FOUND:
            print('not found')
        case _:
            print('unknown')

References:

9

Python's match is much more than a simple switch statement. If you use bare what you consider "variable names", they are actually going to be Capture Patterns. as per definition in PEP no. 634

Besides the fact that you should probably not use match for your use case, you have to use qualified (dotted) names in one of the following ways:

#1 Flat Object

statuses = object()
statuses.success = 200
status.not_found = 404

def handle(retcode):
    match retcode:
        case statuses.success: print("Success")
        case statuses.not_found: print("Not found")

#2 Object Oriented Programming

class StatusValues:
    success = 200
    not_found = 404

def handle(retcode):
    match retcode:
        case StatusValues.success: print("Success")
        case StatusValues.not_found: print("Not found")

#3 Simple qualified locals()/globals() access

I've developed the match-ref library which allows you to access any local or global variable in- or outside of any function, simply using the ref. prefix.

from matchref import ref
import random

SUCCESS = 200
NOT_FOUND = 404

def handle(retcode):
    random_code = random.randint(600,699)

    match retcode:
        case ref.SUCCESS: print("Success")
        case ref.NOT_FOUND: print("Not found")
        case ref.random_code: print("OK, you win!")

As you can see, ref automatically resolved variables from your local and global namespaces (in this order). There's no additional setup necessary.

If you don't want to use 3rd-party libraries, you can see a slightly similar no-libraries version below.

#4 Qualified locals()/globals() access without 3rd-party libs

locals() and globals() are built-in functions in Python which return a dict containing all your variable names mapped to their respective values. You need to be able to access the dict's values using dotted syntax, since match also does not support dictionary access syntax. You can therefore write this simple helper class:

class GetAttributeDict(dict):
    def __getattr__(self, name):
        return self[name]

and use it like so:

import random

SUCCESS = 200
NOT_FOUND = 404

def handle(retcode):
    random_code = random.randint(600, 699)
    globs = GetAttributeDict(globals())
    locs = GetAttributeDict(locals())

    match retcode:
        case globs.SUCCESS: print("Success")
        case globs.NOT_FOUND: print("Not found")
        case locs.random_code: print("OK , you win!")

#5 Module Access

Given that you seem to intend to re-use your status codes (because otherwise you could inline them in your case s), you might consider using separate modules for this.

constants.py:

SUCCESS = 200
NOT_FOUND = 404

main.py

import constants

match retcode:
    case constants.SUCCESS: ...
    ...

Again, you might want to reconsider if you want to use match at all.

1
  • 2
    The example code in #1 doesn't work because object() instances don't allow assigning custom attributes.
    – creanion
    Commented Jul 25, 2023 at 21:18
0

Is there any way to use the match statement to match values that are stored within variables?

You can do this in other languages with immutable data types.

The match statement in python rebinds the values to the variables when possible, so they will match.

To avoid this, use literals or dotted structures. Sometimes it is just easier to use guards or an if statement.

-3

python > 3.10 lets you handle case patterns more efficiently.

| and if statements can be used as well.

using |

match name: 
    case "example_111" | "example_222": 
        return f"Hello {name}" 
    case _: 
        return "Bye"

using if statement

def get_product_info(make, in_dollar): 

    match make:

        case "product_111" if in_dollar: 
            return "10000 $"

        case "product_222" if not in_dollar:
            return "10000*73 INR"

        case _: 
            return "error"

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.