8000 bpo-42128: Add what's new section for PEP 634 (pattern matching) by gvanrossum · Pull Request #24588 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

8000 bpo-42128: Add what's new section for PEP 634 (pattern matching) #24588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

bpo-42128: Add what's new section for PEP 634 (pattern matching) #24588

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 157 additions & 0 deletions Doc/whatsnew/3.10.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,163 @@ Check :pep:`617` for more details.
(Contributed by Guido van Rossum, Pablo Galindo and Lysandros Nikolaou
in :issue:`12782` and :issue:`40334`.)

PEP 634: Structural Pattern Matching
------------------------------------

Pattern matching for objects (sequences, mappings, primitive data types
as well as class instances) has been added in the form of a *match
statement*. Here's a quick tutorial (more docs are forthcoming):

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::

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"

Note the last block: the "variable name" ``_`` acts as a *wildcard* and
never fails to match.

You can combine several literals in a single pattern using ``|`` ("or")::

case 401 | 403 | 404:
return "Not allowed"
Comment on lines +139 to +158
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example has some problems, as mentioned in https://bugs.python.org/issue42128#msg387371:

I've seen too many knee-jerk reactions over the past weeks along the lines of "the new switch feature can't handle named constants!".

Interestingly I haven't seen such reactions, I've just seen a lot of (mostly) positive responses to my tweet linking to this same tutorial: https://twitter.com/gvanrossum/status/1361124478671933443. (Admittedly, there were negative reactions too, including "the worst pep of the python history." But I didn't see anything about named constants.)


Patterns can look like unpacking assignments, and can be used to bind
variables::

# 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")

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 (``point``). The fourth
pattern captures two values, which makes it conceptually similar to
the unpacking assignment ``(x, y) = point``.

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::

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")

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 ``__match_args__`` special
attribute in your classes. If it's set to ("x", "y"), the following patterns are all
equivalent (and all bind the ``y`` attribute to the ``var`` variable)::

Point(1, var)
Point(1, y=var)
Point(x=1, y=var)
Point(y=var, x=1)

Patterns can be arbitrarily nested. For example, if we have a short
list of points, we could match it like this::

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")

We can add an ``if`` clause to a pattern, known as a "guard". If the
guard is false, ``match`` goes on to try the next case block. Note
that value capture happens before the guard is evaluated::

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")

Several other key features:

- 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
``collections.abc.Sequence``.)

- Sequence patterns support wildcards: ``[x, y, *rest]`` and ``(x, y,
*rest)`` work similar to wildcards in unpacking assignments. The
name after ``*`` may also be ``_``, so ``(x, y, *_)`` matches a sequence
of at least two items without binding the remaining items.

- Mapping patterns: ``{"bandwidth": b, "latency": l}`` captures the
``"bandwidth"`` and ``"latency"`` values from a dict. Unlike sequence
patterns, extra keys are ignored. A wildcard ``**rest`` is also
supported. (But ``**_`` would be redundant, so it not allowed.)

- Subpatterns may be captured using the ``as`` keyword::

case (Point(x1, y1), Point(x2, y2) as p2): ...

- Most literals are compared by equality, however the singletons ``True``,
``False`` and ``None`` are compared by identity.

- Patterns may use named constants. These must be dotted names
to prevent them from being interpreted as capture variable::

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 :(")

For the full specification see :pep:`634`. Motivation and rationale
are in :pep:`635`, and a longer tutorial is in :pep:`636`.

PEP 563: Postponed Evaluation of Annotations Becomes Default
------------------------------------------------------------
Expand Down
0