CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 636 – Structural Pattern Matching: Tutorial | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0636/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 636 – Structural Pattern Matching: Tutorial | peps.python.org'> <meta property="og:description" content="This PEP is a tutorial for the pattern matching introduced by PEP 634."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0636/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP is a tutorial for the pattern matching introduced by PEP 634."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 636</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 636 – Structural Pattern Matching: Tutorial</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Daniel F Moisset <dfmoisset at gmail.com></dd> <dt class="field-even">Sponsor:</dt> <dd class="field-even">Guido van Rossum <guido at python.org></dd> <dt class="field-odd">BDFL-Delegate:</dt> <dd class="field-odd"></dd> <dt class="field-even">Discussions-To:</dt> <dd class="field-even"><a class="reference external" href="https://mail.python.org/archives/list/python-dev@python.org/">Python-Dev list</a></dd> <dt class="field-odd">Status:</dt> <dd class="field-odd"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-even">Type:</dt> <dd class="field-even"><abbr title="Non-normative PEP containing background, guidelines or other information relevant to the Python ecosystem">Informational</abbr></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">12-Sep-2020</dd> <dt class="field-even">Python-Version:</dt> <dd class="field-even">3.10</dd> <dt class="field-odd">Post-History:</dt> <dd class="field-odd">22-Oct-2020, 08-Feb-2021</dd> <dt class="field-even">Resolution:</dt> <dd class="field-even"><a class="reference external" href="https://mail.python.org/archives/list/python-committers@python.org/message/SQC2FTLFV5A7DV7RCEAR2I2IKJKGK7W3">Python-Committers message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#tutorial">Tutorial</a><ul> <li><a class="reference internal" href="#matching-sequences">Matching sequences</a></li> <li><a class="reference internal" href="#matching-multiple-patterns">Matching multiple patterns</a></li> <li><a class="reference internal" href="#matching-specific-values">Matching specific values</a></li> <li><a class="reference internal" href="#matching-multiple-values">Matching multiple values</a></li> <li><a class="reference internal" href="#adding-a-wildcard">Adding a wildcard</a></li> <li><a class="reference internal" href="#composing-patterns">Composing patterns</a></li> <li><a class="reference internal" href="#or-patterns">Or patterns</a></li> <li><a class="reference internal" href="#capturing-matched-sub-patterns">Capturing matched sub-patterns</a></li> <li><a class="reference internal" href="#adding-conditions-to-patterns">Adding conditions to patterns</a></li> <li><a class="reference internal" href="#adding-a-ui-matching-objects">Adding a UI: Matching objects</a></li> <li><a class="reference internal" href="#matching-positional-attributes">Matching positional attributes</a></li> <li><a class="reference internal" href="#matching-against-constants-and-enums">Matching against constants and enums</a></li> <li><a class="reference internal" href="#going-to-the-cloud-mappings">Going to the cloud: Mappings</a></li> <li><a class="reference internal" href="#matching-builtin-classes">Matching builtin classes</a></li> </ul> </li> <li><a class="reference internal" href="#appendix-a-quick-intro">Appendix A – Quick Intro</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP is a tutorial for the pattern matching introduced by <a class="pep reference internal" href="../pep-0634/" title="PEP 634 – Structural Pattern Matching: Specification">PEP 634</a>. <a class="pep reference internal" href="../pep-0622/" title="PEP 622 – Structural Pattern Matching">PEP 622</a> proposed syntax for pattern matching, which received detailed discussion both from the community and the Steering Council. A frequent concern was about how easy it would be to explain (and learn) this feature. This PEP addresses that concern providing the kind of document which developers could use to learn about pattern matching in Python. This is considered supporting material for <a class="pep reference internal" href="../pep-0634/" title="PEP 634 – Structural Pattern Matching: Specification">PEP 634</a> (the technical specification for pattern matching) and <a class="pep reference internal" href="../pep-0635/" title="PEP 635 – Structural Pattern Matching: Motivation and Rationale">PEP 635</a> (the motivation and rationale for having pattern matching and design considerations). For readers who are looking more for a quick review than for a tutorial, see <a class="reference internal" href="#pep-636-appendix-a">Appendix A</a>. </section> <section id="tutorial"> <h2><a class="toc-backref" href="#tutorial" role="doc-backlink">Tutorial</a></h2> As an example to motivate this tutorial, you will be writing a text adventure. That is a form of interactive fiction where the user enters text commands to interact with a fictional world and receives text descriptions of what happens. Commands will be simplified forms of natural language like <code class="docutils literal notranslate">get sword</code>, <code class="docutils literal notranslate">attack dragon</code>, <code class="docutils literal notranslate">go north</code>, <code class="docutils literal notranslate">enter shop</code> or <code class="docutils literal notranslate">buy cheese</code>. <section id="matching-sequences"> <h3><a class="toc-backref" href="#matching-sequences" role="doc-backlink">Matching sequences</a></h3> Your main loop will need to get input from the user and split it into words, let’s say a list of strings like this: <div class="highlight-default notranslate"><div class="highlight"><pre>command = input("What are you doing next? ") # analyze the result of command.split() </pre></div> </div> The next step is to interpret the words. Most of our commands will have two words: an action and an object. So you may be tempted to do the following: <div class="highlight-default notranslate"><div class="highlight"><pre>[action, obj] = command.split() ... # interpret action, obj </pre></div> </div> The problem with that line of code is that it’s missing something: what if the user types more or fewer than 2 words? To prevent this problem you can either check the length of the list of words, or capture the <code class="docutils literal notranslate">ValueError</code> that the statement above would raise. You can use a matching statement instead: <div class="highlight-default notranslate"><div class="highlight"><pre>match command.split(): case [action, obj]: ... # interpret action, obj </pre></div> </div> The match statement evaluates the “subject” (the value after the <code class="docutils literal notranslate">match</code> keyword), and checks it against the pattern (the code next to <code class="docutils literal notranslate">case</code>). A pattern is able to do two different things: <ul class="simple"> <li>Verify that the subject has certain structure. In your case, the <code class="docutils literal notranslate">[action, obj]</code> pattern matches any sequence of exactly two elements. This is called matching</li> <li>It will bind some names in the pattern to component elements of your subject. In this case, if the list has two elements, it will bind <code class="docutils literal notranslate">action = subject[0]</code> and <code class="docutils literal notranslate">obj = subject[1]</code>.</li> </ul> If there’s a match, the statements inside the case block will be executed with the bound variables. If there’s no match, nothing happens and the statement after <code class="docutils literal notranslate">match</code> is executed next. Note that, in a similar way to unpacking assignments, you can use either parenthesis, brackets, or just comma separation as synonyms. So you could write <code class="docutils literal notranslate">case action, obj</code> or <code class="docutils literal notranslate">case (action, obj)</code> with the same meaning. All forms will match any sequence (for example lists or tuples). </section> <section id="matching-multiple-patterns"> <h3><a class="toc-backref" href="#matching-multiple-patterns" role="doc-backlink">Matching multiple patterns</a></h3> Even if most commands have the action/object form, you might want to have user commands of different lengths. For example, you might want to add single verbs with no object like <code class="docutils literal notranslate">look</code> or <code class="docutils literal notranslate">quit</code>. A match statement can (and is likely to) have more than one <code class="docutils literal notranslate">case</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>match command.split(): case [action]: ... # interpret single-verb action case [action, obj]: ... # interpret action, obj </pre></div> </div> The match statement will check patterns from top to bottom. If the pattern doesn’t match the subject, the next pattern will be tried. However, once the first matching pattern is found, the body of that case is executed, and all further cases are ignored. This is similar to the way that an <code class="docutils literal notranslate">if/elif/elif/...</code> statement works. </section> <section id="matching-specific-values"> <h3><a class="toc-backref" href="#matching-specific-values" role="doc-backlink">Matching specific values</a></h3> Your code still needs to look at the specific actions and conditionally execute different logic depending on the specific action (e.g., <code class="docutils literal notranslate">quit</code>, <code class="docutils literal notranslate">attack</code>, or <code class="docutils literal notranslate">buy</code>). You could do that using a chain of <code class="docutils literal notranslate">if/elif/elif/...</code>, or using a dictionary of functions, but here we’ll leverage pattern matching to solve that task. Instead of a variable, you can use literal values in patterns (like <code class="docutils literal notranslate">"quit"</code>, <code class="docutils literal notranslate">42</code>, or <code class="docutils literal notranslate">None</code>). This allows you to write: <div class="highlight-default notranslate"><div class="highlight"><pre>match command.split(): case ["quit"]: print("Goodbye!") quit_game() case ["look"]: current_room.describe() case ["get", obj]: character.get(obj, current_room) case ["go", direction]: current_room = current_room.neighbor(direction) # The rest of your commands go here </pre></div> </div> A pattern like <code class="docutils literal notranslate">["get", obj]</code> will match only 2-element sequences that have a first element equal to <code class="docutils literal notranslate">"get"</code>. It will also bind <code class="docutils literal notranslate">obj = subject[1]</code>. As you can see in the <code class="docutils literal notranslate">go</code> case, we also can use different variable names in different patterns. Literal values are compared with the <code class="docutils literal notranslate">==</code> operator except for the constants <code class="docutils literal notranslate">True</code>, <code class="docutils literal notranslate">False</code> and <code class="docutils literal notranslate">None</code> which are compared with the <code class="docutils literal notranslate">is</code> operator. </section> <section id="matching-multiple-values"> <h3><a class="toc-backref" href="#matching-multiple-values" role="doc-backlink">Matching multiple values</a></h3> A player may be able to drop multiple items by using a series of commands <code class="docutils literal notranslate">drop key</code>, <code class="docutils literal notranslate">drop sword</code>, <code class="docutils literal notranslate">drop cheese</code>. This interface might be cumbersome, and you might like to allow dropping multiple items in a single command, like <code class="docutils literal notranslate">drop key sword cheese</code>. In this case you don’t know beforehand how many words will be in the command, but you can use extended unpacking in patterns in the same way that they are allowed in assignments: <div class="highlight-default notranslate"><div class="highlight"><pre>match command.split(): case ["drop", *objects]: for obj in objects: character.drop(obj, current_room) # The rest of your commands go here </pre></div> </div> This will match any sequences having “drop” as its first elements. All remaining elements will be captured in a <code class="docutils literal notranslate">list</code> object which will be bound to the <code class="docutils literal notranslate">objects</code> variable. This syntax has similar restrictions as sequence unpacking: you can not have more than one starred name in a pattern. </section> <section id="adding-a-wildcard"> <h3><a class="toc-backref" href="#adding-a-wildcard" role="doc-backlink">Adding a wildcard</a></h3> You may want to print an error message saying that the command wasn’t recognized when all the patterns fail. You could use the feature we just learned and write <code class="docutils literal notranslate">case [*ignored_words]</code> as your last pattern. There’s however a much simpler way: <div class="highlight-default notranslate"><div class="highlight"><pre>match command.split(): case ["quit"]: ... # Code omitted for brevity case ["go", direction]: ... case ["drop", *objects]: ... ... # Other cases case _: print(f"Sorry, I couldn't understand {command!r}") </pre></div> </div> This special pattern which is written <code class="docutils literal notranslate">_</code> (and called wildcard) always matches but it doesn’t bind any variables. Note that this will match any object, not just sequences. As such, it only makes sense to have it by itself as the last pattern (to prevent errors, Python will stop you from using it before). </section> <section id="composing-patterns"> <h3><a class="toc-backref" href="#composing-patterns" role="doc-backlink">Composing patterns</a></h3> This is a good moment to step back from the examples and understand how the patterns that you have been using are built. Patterns can be nested within each other, and we have been doing that implicitly in the examples above. There are some “simple” patterns (“simple” here meaning that they do not contain other patterns) that we’ve seen: <ul class="simple"> <li>Capture patterns (stand-alone names like <code class="docutils literal notranslate">direction</code>, <code class="docutils literal notranslate">action</code>, <code class="docutils literal notranslate">objects</code>). We never discussed these separately, but used them as part of other patterns.</li> <li>Literal patterns (string literals, number literals, <code class="docutils literal notranslate">True</code>, <code class="docutils literal notranslate">False</code>, and <code class="docutils literal notranslate">None</code>)</li> <li>The wildcard pattern <code class="docutils literal notranslate">_</code></li> </ul> Until now, the only non-simple pattern we have experimented with is the sequence pattern. Each element in a sequence pattern can in fact be any other pattern. This means that you could write a pattern like <code class="docutils literal notranslate">["first", (left, right), _, *rest]</code>. This will match subjects which are a sequence of at least three elements, where the first one is equal to <code class="docutils literal notranslate">"first"</code> and the second one is in turn a sequence of two elements. It will also bind <code class="docutils literal notranslate">left=subject[1][0]</code>, <code class="docutils literal notranslate">right=subject[1][1]</code>, and <code class="docutils literal notranslate">rest = subject[3:]</code> </section> <section id="or-patterns"> <h3><a class="toc-backref" href="#or-patterns" role="doc-backlink">Or patterns</a></h3> Going back to the adventure game example, you may find that you’d like to have several patterns resulting in the same outcome. For example, you might want the commands <code class="docutils literal notranslate">north</code> and <code class="docutils literal notranslate">go north</code> to be equivalent. You may also desire to have aliases for <code class="docutils literal notranslate">get X</code>, <code class="docutils literal notranslate">pick up X</code> and <code class="docutils literal notranslate">pick X up</code> for any X. The <code class="docutils literal notranslate">|</code> symbol in patterns combines them as alternatives. You could for example write: <div class="highlight-default notranslate"><div class="highlight"><pre>match command.split(): ... # Other cases case ["north"] | ["go", "north"]: current_room = current_room.neighbor("north") case ["get", obj] | ["pick", "up", obj] | ["pick", obj, "up"]: ... # Code for picking up the given object </pre></div> </div> This is called an or pattern and will produce the expected result. Patterns are tried from left to right; this may be relevant to know what is bound if more than one alternative matches. An important restriction when writing or patterns is that all alternatives should bind the same variables. So a pattern <code class="docutils literal notranslate">[1, x] | [2, y]</code> is not allowed because it would make unclear which variable would be bound after a successful match. <code class="docutils literal notranslate">[1, x] | [2, x]</code> is perfectly fine and will always bind <code class="docutils literal notranslate">x</code> if successful. </section> <section id="capturing-matched-sub-patterns"> <h3><a class="toc-backref" href="#capturing-matched-sub-patterns" role="doc-backlink">Capturing matched sub-patterns</a></h3> The first version of our “go” command was written with a <code class="docutils literal notranslate">["go", direction]</code> pattern. The change we did in our last version using the pattern <code class="docutils literal notranslate">["north"] | ["go", "north"]</code> has some benefits but also some drawbacks in comparison: the latest version allows the alias, but also has the direction hardcoded, which will force us to actually have separate patterns for north/south/east/west. This leads to some code duplication, but at the same time we get better input validation, and we will not be getting into that branch if the command entered by the user is <code class="docutils literal notranslate">"go figure!"</code> instead of a direction. We could try to get the best of both worlds doing the following (I’ll omit the aliased version without “go” for brevity): <div class="highlight-default notranslate"><div class="highlight"><pre>match command.split(): case ["go", ("north" | "south" | "east" | "west")]: current_room = current_room.neighbor(...) # how do I know which direction to go? </pre></div> </div> This code is a single branch, and it verifies that the word after “go” is really a direction. But the code moving the player around needs to know which one was chosen and has no way to do so. What we need is a pattern that behaves like the or pattern but at the same time does a capture. We can do so with an as pattern: <div class="highlight-default notranslate"><div class="highlight"><pre>match command.split(): case ["go", ("north" | "south" | "east" | "west") as direction]: current_room = current_room.neighbor(direction) </pre></div> </div> The as-pattern matches whatever pattern is on its left-hand side, but also binds the value to a name. </section> <section id="adding-conditions-to-patterns"> <h3><a class="toc-backref" href="#adding-conditions-to-patterns" role="doc-backlink">Adding conditions to patterns</a></h3> The patterns we have explored above can do some powerful data filtering, but sometimes you may wish for the full power of a boolean expression. Let’s say that you would actually like to allow a “go” command only in a restricted set of directions based on the possible exits from the current_room. We can achieve that by adding a guard to our case. Guards consist of the <code class="docutils literal notranslate">if</code> keyword followed by any expression: <div class="highlight-default notranslate"><div class="highlight"><pre>match command.split(): case ["go", direction] if direction in current_room.exits: current_room = current_room.neighbor(direction) case ["go", _]: print("Sorry, you can't go that way") </pre></div> </div> The guard is not part of the pattern, it’s part of the case. It’s only checked if the pattern matches, and after all the pattern variables have been bound (that’s why the condition can use the <code class="docutils literal notranslate">direction</code> variable in the example above). If the pattern matches and the condition is truthy, the body of the case executes normally. If the pattern matches but the condition is falsy, the match statement proceeds to check the next case as if the pattern hadn’t matched (with the possible side-effect of having already bound some variables). </section> <section id="adding-a-ui-matching-objects"> <h3><a class="toc-backref" href="#adding-a-ui-matching-objects" role="doc-backlink">Adding a UI: Matching objects</a></h3> Your adventure is becoming a success and you have been asked to implement a graphical interface. Your UI toolkit of choice allows you to write an event loop where you can get a new event object by calling <code class="docutils literal notranslate">event.get()</code>. The resulting object can have different type and attributes according to the user action, for example: <ul class="simple"> <li>A <code class="docutils literal notranslate">KeyPress</code> object is generated when the user presses a key. It has a <code class="docutils literal notranslate">key_name</code> attribute with the name of the key pressed, and some other attributes regarding modifiers.</li> <li>A <code class="docutils literal notranslate">Click</code> object is generated when the user clicks the mouse. It has an attribute <code class="docutils literal notranslate">position</code> with the coordinates of the pointer.</li> <li>A <code class="docutils literal notranslate">Quit</code> object is generated when the user clicks on the close button for the game window.</li> </ul> Rather than writing multiple <code class="docutils literal notranslate">isinstance()</code> checks, you can use patterns to recognize different kinds of objects, and also apply patterns to its attributes: <div class="highlight-default notranslate"><div class="highlight"><pre>match event.get(): case Click(position=(x, y)): handle_click_at(x, y) case KeyPress(key_name="Q") | Quit(): game.quit() case KeyPress(key_name="up arrow"): game.go_north() ... case KeyPress(): pass # Ignore other keystrokes case other_event: raise ValueError(f"Unrecognized event: {other_event}") </pre></div> </div> A pattern like <code class="docutils literal notranslate">Click(position=(x, y))</code> only matches if the type of the event is a subclass of the <code class="docutils literal notranslate">Click</code> class. It will also require that the event has a <code class="docutils literal notranslate">position</code> attribute that matches the <code class="docutils literal notranslate">(x, y)</code> pattern. If there’s a match, the locals <code class="docutils literal notranslate">x</code> and <code class="docutils literal notranslate">y</code> will get the expected values. A pattern like <code class="docutils literal notranslate">KeyPress()</code>, with no arguments will match any object which is an instance of the <code class="docutils literal notranslate">KeyPress</code> class. Only the attributes you specify in the pattern are matched, and any other attributes are ignored. </section> <section id="matching-positional-attributes"> <h3><a class="toc-backref" href="#matching-positional-attributes" role="doc-backlink">Matching positional attributes</a></h3> The previous section described how to match named attributes when doing an object match. For some objects it could be convenient to describe the matched arguments by position (especially if there are only a few attributes and they have a “standard” ordering). If the classes that you are using are named tuples or dataclasses, you can do that by following the same order that you’d use when constructing an object. For example, if the UI framework above defines their class like this: <div class="highlight-default notranslate"><div class="highlight"><pre>from dataclasses import dataclass @dataclass class Click: position: tuple button: Button </pre></div> </div> then you can rewrite your match statement above as: <div class="highlight-default notranslate"><div class="highlight"><pre>match event.get(): case Click((x, y)): handle_click_at(x, y) </pre></div> </div> The <code class="docutils literal notranslate">(x, y)</code> pattern will be automatically matched against the <code class="docutils literal notranslate">position</code> attribute, because the first argument in the pattern corresponds to the first attribute in your dataclass definition. Other classes don’t have a natural ordering of their attributes so you’re required to use explicit names in your pattern to match with their attributes. However, it’s possible to manually specify the ordering of the attributes allowing positional matching, like in this alternative definition: <div class="highlight-default notranslate"><div class="highlight"><pre>class Click: __match_args__ = ("position", "button") def __init__(self, pos, btn): self.position = pos self.button = btn ... </pre></div> </div> The <code class="docutils literal notranslate">__match_args__</code> special attribute defines an explicit order for your attributes that can be used in patterns like <code class="docutils literal notranslate">case Click((x,y))</code>. </section> <section id="matching-against-constants-and-enums"> <h3><a class="toc-backref" href="#matching-against-constants-and-enums" role="doc-backlink">Matching against constants and enums</a></h3> Your pattern above treats all mouse buttons the same, and you have decided that you want to accept left-clicks, and ignore other buttons. While doing so, you notice that the <code class="docutils literal notranslate">button</code> attribute is typed as a <code class="docutils literal notranslate">Button</code> which is an enumeration built with <code class="docutils literal notranslate">enum.Enum</code>. You can in fact match against enumeration values like this: <div class="highlight-default notranslate"><div class="highlight"><pre>match event.get(): case Click((x, y), button=Button.LEFT): # This is a left click handle_click_at(x, y) case Click(): pass # ignore other clicks </pre></div> </div> This will work with any dotted name (like <code class="docutils literal notranslate">math.pi</code>). However an unqualified name (i.e. a bare name with no dots) will be always interpreted as a capture pattern, so avoid that ambiguity by always using qualified constants in patterns. </section> <section id="going-to-the-cloud-mappings"> <h3><a class="toc-backref" href="#going-to-the-cloud-mappings" role="doc-backlink">Going to the cloud: Mappings</a></h3> You have decided to make an online version of your game. All of your logic will be in a server, and the UI in a client which will communicate using JSON messages. Via the <code class="docutils literal notranslate">json</code> module, those will be mapped to Python dictionaries, lists and other builtin objects. Our client will receive a list of dictionaries (parsed from JSON) of actions to take, each element looking for example like these: <ul class="simple"> <li><code class="docutils literal notranslate">{"text": "The shop keeper says 'Ah! We have Camembert, yes sir'", "color": "blue"}</code></li> <li>If the client should make a pause <code class="docutils literal notranslate">{"sleep": 3}</code></li> <li>To play a sound <code class="docutils literal notranslate">{"sound": "filename.ogg", "format": "ogg"}</code></li> </ul> Until now, our patterns have processed sequences, but there are patterns to match mappings based on their present keys. In this case you could use: <div class="highlight-default notranslate"><div class="highlight"><pre>for action in actions: match action: case {"text": message, "color": c}: ui.set_text_color(c) ui.display(message) case {"sleep": duration}: ui.wait(duration) case {"sound": url, "format": "ogg"}: ui.play(url) case {"sound": _, "format": _}: warning("Unsupported audio format") </pre></div> </div> The keys in your mapping pattern need to be literals, but the values can be any pattern. As in sequence patterns, all subpatterns have to match for the general pattern to match. You can use <code class="docutils literal notranslate">**rest</code> within a mapping pattern to capture additional keys in the subject. Note that if you omit this, extra keys in the subject will be ignored while matching, i.e. the message <code class="docutils literal notranslate">{"text": "foo", "color": "red", "style": "bold"}</code> will match the first pattern in the example above. </section> <section id="matching-builtin-classes"> <h3><a class="toc-backref" href="#matching-builtin-classes" role="doc-backlink">Matching builtin classes</a></h3> The code above could use some validation. Given that messages came from an external source, the types of the field could be wrong, leading to bugs or security issues. Any class is a valid match target, and that includes built-in classes like <code class="docutils literal notranslate">bool</code> <code class="docutils literal notranslate">str</code> or <code class="docutils literal notranslate">int</code>. That allows us to combine the code above with a class pattern. So instead of writing <code class="docutils literal notranslate">{"text": message, "color": c}</code> we can use <code class="docutils literal notranslate">{"text": str() as message, "color": str() as c}</code> to ensure that <code class="docutils literal notranslate">message</code> and <code class="docutils literal notranslate">c</code> are both strings. For many builtin classes (see <a class="pep reference internal" href="../pep-0634/" title="PEP 634 – Structural Pattern Matching: Specification">PEP 634</a> for the whole list), you can use a positional parameter as a shorthand, writing <code class="docutils literal notranslate">str(c)</code> rather than <code class="docutils literal notranslate">str() as c</code>. The fully rewritten version looks like this: <div class="highlight-default notranslate"><div class="highlight"><pre>for action in actions: match action: case {"text": str(message), "color": str(c)}: ui.set_text_color(c) ui.display(message) case {"sleep": float(duration)}: ui.wait(duration) case {"sound": str(url), "format": "ogg"}: ui.play(url) case {"sound": _, "format": _}: warning("Unsupported audio format") </pre></div> </div> </section> </section> <section id="appendix-a-quick-intro"> <h2><a class="toc-backref" href="#appendix-a-quick-intro" role="doc-backlink">Appendix A – Quick Intro</a></h2> A match statement takes an expression and compares its value to successive patterns given as one or more case blocks. This is superficially similar to a switch statement in C, Java or JavaScript (and many other languages), but much more powerful. The simplest form compares a subject value against one or more literals: <div class="highlight-default notranslate"><div class="highlight"><pre>def http_error(status): match status: case 400: return "Bad request" case 404: return "Not found" case 418: return "I'm a teapot" case _: return "Something's wrong with the Internet" </pre></div> </div> Note the last block: the “variable name” <code class="docutils literal notranslate">_</code> acts as a wildcard and never fails to match. You can combine several literals in a single pattern using <code class="docutils literal notranslate">|</code> (“or”): <div class="highlight-default notranslate"><div class="highlight"><pre>case 401 | 403 | 404: return "Not allowed" </pre></div> </div> Patterns can look like unpacking assignments, and can be used to bind variables: <div class="highlight-default notranslate"><div class="highlight"><pre># point is an (x, y) tuple match point: case (0, 0): print("Origin") case (0, y): print(f"Y={y}") case (x, 0): print(f"X={x}") case (x, y): print(f"X={x}, Y={y}") case _: raise ValueError("Not a point") </pre></div> </div> Study that one carefully! The first pattern has two literals, and can be thought of as an extension of the literal pattern shown above. But the next two patterns combine a literal and a variable, and the variable binds a value from the subject (<code class="docutils literal notranslate">point</code>). The fourth pattern captures two values, which makes it conceptually similar to the unpacking assignment <code class="docutils literal notranslate">(x, y) = point</code>. If you are using classes to structure your data you can use the class name followed by an argument list resembling a constructor, but with the ability to capture attributes into variables: <div class="highlight-default notranslate"><div class="highlight"><pre>from dataclasses import dataclass @dataclass class Point: x: int y: int def where_is(point): match point: case Point(x=0, y=0): print("Origin") case Point(x=0, y=y): print(f"Y={y}") case Point(x=x, y=0): print(f"X={x}") case Point(): print("Somewhere else") case _: print("Not a point") </pre></div> </div> You can use positional parameters with some builtin classes that provide an ordering for their attributes (e.g. dataclasses). You can also define a specific position for attributes in patterns by setting the <code class="docutils literal notranslate">__match_args__</code> special attribute in your classes. If it’s set to (“x”, “y”), the following patterns are all equivalent (and all bind the <code class="docutils literal notranslate">y</code> attribute to the <code class="docutils literal notranslate">var</code> variable): <div class="highlight-default notranslate"><div class="highlight"><pre>Point(1, var) Point(1, y=var) Point(x=1, y=var) Point(y=var, x=1) </pre></div> </div> Patterns can be arbitrarily nested. For example, if we have a short list of points, we could match it like this: <div class="highlight-default notranslate"><div class="highlight"><pre>match points: case []: print("No points") case [Point(0, 0)]: print("The origin") case [Point(x, y)]: print(f"Single point {x}, {y}") case [Point(0, y1), Point(0, y2)]: print(f"Two on the Y axis at {y1}, {y2}") case _: print("Something else") </pre></div> </div> We can add an <code class="docutils literal notranslate">if</code> clause to a pattern, known as a “guard”. If the guard is false, <code class="docutils literal notranslate">match</code> goes on to try the next case block. Note that value capture happens before the guard is evaluated: <div class="highlight-default notranslate"><div class="highlight"><pre>match point: case Point(x, y) if x == y: print(f"Y=X at {x}") case Point(x, y): print(f"Not on the diagonal") </pre></div> </div> Several other key features: <ul> <li>Like unpacking assignments, tuple and list patterns have exactly the same meaning and actually match arbitrary sequences. An important exception is that they don’t match iterators or strings. (Technically, the subject must be an instance of <code class="docutils literal notranslate">collections.abc.Sequence</code>.)</li> <li>Sequence patterns support wildcards: <code class="docutils literal notranslate">[x, y, *rest]</code> and <code class="docutils literal notranslate">(x, y, *rest)</code> work similar to wildcards in unpacking assignments. The name after <code class="docutils literal notranslate">*</code> may also be <code class="docutils literal notranslate">_</code>, so <code class="docutils literal notranslate">(x, y, *_)</code> matches a sequence of at least two items without binding the remaining items.</li> <li>Mapping patterns: <code class="docutils literal notranslate">{"bandwidth": b, "latency": l}</code> captures the <code class="docutils literal notranslate">"bandwidth"</code> and <code class="docutils literal notranslate">"latency"</code> values from a dict. Unlike sequence patterns, extra keys are ignored. A wildcard <code class="docutils literal notranslate">**rest</code> is also supported. (But <code class="docutils literal notranslate">**_</code> would be redundant, so it is not allowed.)</li> <li>Subpatterns may be captured using the <code class="docutils literal notranslate">as</code> keyword:<div class="highlight-default notranslate"><div class="highlight"><pre>case (Point(x1, y1), Point(x2, y2) as p2): ... </pre></div> </div> </li> <li>Most literals are compared by equality, however the singletons <code class="docutils literal notranslate">True</code>, <code class="docutils literal notranslate">False</code> and <code class="docutils literal notranslate">None</code> are compared by identity.</li> <li>Patterns may use named constants. These must be dotted names to prevent them from being interpreted as capture variable:<div class="highlight-default notranslate"><div class="highlight"><pre>from enum import Enum class Color(Enum): RED = 0 GREEN = 1 BLUE = 2 match color: case Color.RED: print("I see red!") case Color.GREEN: print("Grass is green") case Color.BLUE: print("I'm feeling the blues :(") </pre></div> </div> </li> </ul> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0636.rst">https://github.com/python/peps/blob/main/peps/pep-0636.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0636.rst">2023-09-09 17:39:29 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#tutorial">Tutorial</a><ul> <li><a class="reference internal" href="#matching-sequences">Matching sequences</a></li> <li><a class="reference internal" href="#matching-multiple-patterns">Matching multiple patterns</a></li> <li><a class="reference internal" href="#matching-specific-values">Matching specific values</a></li> <li><a class="reference internal" href="#matching-multiple-values">Matching multiple values</a></li> <li><a class="reference internal" href="#adding-a-wildcard">Adding a wildcard</a></li> <li><a class="reference internal" href="#composing-patterns">Composing patterns</a></li> <li><a class="reference internal" href="#or-patterns">Or patterns</a></li> <li><a class="reference internal" href="#capturing-matched-sub-patterns">Capturing matched sub-patterns</a></li> <li><a class="reference internal" href="#adding-conditions-to-patterns">Adding conditions to patterns</a></li> <li><a class="reference internal" href="#adding-a-ui-matching-objects">Adding a UI: Matching objects</a></li> <li><a class="reference internal" href="#matching-positional-attributes">Matching positional attributes</a></li> <li><a class="reference internal" href="#matching-against-constants-and-enums">Matching against constants and enums</a></li> <li><a class="reference internal" href="#going-to-the-cloud-mappings">Going to the cloud: Mappings</a></li> <li><a class="reference internal" href="#matching-builtin-classes">Matching builtin classes</a></li> </ul> </li> <li><a class="reference internal" href="#appendix-a-quick-intro">Appendix A – Quick Intro</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0636.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>