bpo-42128: Add documentation for pattern matching (PEP 634) #24664

dmoisset · 2021-02-27T23:52:51Z

This covers documentation for the new match statement in 3.10, as requested by the SC in https://mail.python.org/archives/list/[email protected]/message/SQC2FTLFV5A7DV7RCEAR2I2IKJKGK7W3/

The documentation includes:

A large language reference update include syntax and behaviour of the match statement, largely based on the relevant sections of PEP-634 in the compound statements section.
A significant new section in the "control flow" chapter of the tutorial based on the Appendix A of PEP-636
An update to the "data model" reference chapter describing the new special attribute __match_args__
A new section in the "lexical analysis" chapter describing the use of soft keywords.
An update to the FAQ entry about "Why isn't there a switch or case statement in Python?"

https://bugs.python.org/issue42128

The tutorial is a slightly modified version of PEP-636 Appendix A

…r soft keywords

Brought up in https://bugs.python.org/msg387769

This reverts commit 6320747.

Co-Authored-By: Daniel F Moisset <[email protected]> Co-Authored-By: Guido van Rossum <[email protected]> Co-Authored-By: Brandt Bucher <[email protected]>

…DOs left) one table idea was inspired by Raymond's awesome tweet here https://twitter.com/raymondh/status/1361780586570948609 Co-Authored-By: Raymond Hettinger <[email protected]>

Co-authored-by: Daniel F Moisset <[email protected]>

Some minor typos, and copy/paste fixes

dmoisset · 2021-02-28T00:16:59Z

This is currently a Draft PR because I plan to make some minor adjustments, but it should be "complete" and reviewable at this point. The planned changes are likely to be some removals/rearranging of content in the "Doc/reference/compound_stmts.rst" file

gvanrossum · 2021-02-28T01:25:54Z

@dmoisset @Fidget-Spinner I assume that the two of you have co-authored this? Once you two agree that this is ready to be merged I will just merge it sight unseen -- I don't have time this weekend to do a full review, and I think it's important that we have docs to go with the code that @brandtbucher just landed. Note that the 3.10a6 release goes out Monday.

Fidget-Spinner · 2021-02-28T01:43:56Z

@dmoisset @Fidget-Spinner I assume that the two of you have co-authored this? Once you two agree that this is ready to be merged I will just merge it sight unseen

Apart from the compound statements reference, I'm very happy with the changes (huge thanks to Daniel for writing the majority of the other parts!).

We're currently trying to fine tune the compound statements reference because its quite long. If we can't make it in time for Monday, I'm OK with merging it as-is: we can always make more PRs to amend it later and the online docs auto rebuilds everyday anyways.

Btw, please apply the skip news label if you feel it fits that :). Thanks!

Doc/reference/lexical_analysis.rst

Doc/reference/datamodel.rst

Co-authored-by: Ken Jin <[email protected]>

This avoid some possible confusion present in the previous language, where it wasn't explicit that bindings happened before the guard was valuated

dmoisset · 2021-02-28T23:46:54Z

@dmoisset @Fidget-Spinner I assume that the two of you have co-authored this? Once you two agree that this is ready to be merged I will just merge it sight unseen -- I don't have time this weekend to do a full review, and I think it's important that we have docs to go with the code that @brandtbucher just landed. Note that the 3.10a6 release goes out Monday.

Your assumption is correct. I flagged this as ready to merge (I hope @Fidget-Spinner agrees, I've ended up butchering the table but keeping the content... for people who wants a high-level overview, they can look at the tutorial or the PEP rather than the reference). I'm happy to refine if problems are found in review later on.

gvanrossum

Thanks for this extensive work! I'll merge my two suggestions and then land it later tonight.

gvanrossum · 2021-03-01T00:33:48Z

Doc/faq/design.rst

-consensus (yet) on whether and how to do range tests.  See :pep:`275` for
-complete details and the current status.
+For literal values, or constants within a namespace, you can also use a
+``match ... case`` statement.


I expect it would be better to rewrite or remove this section, but not now. IMO "match" is the missing switch/case statement.

Or update the question to be: Is there a switch or case statement in Python?

Doc/reference/datamodel.rst

Doc/tutorial/controlflow.rst

gvanrossum · 2021-03-01T00:51:17Z

Doc/tutorial/controlflow.rst

   ...

+
+.. _tut-match:


Note that we now have two slightly diverging versions of the same introduction to match statements in the docs (three if you count Appendix A of PEP 636) -- the other is in what's new in 3.10. We don't have to fix this now but I think it would be good if the texts didn't arbitrarily differ from each other. Either the same text should be included in both places (possibly with a different intro and outro), or what's new should be much shorter and just point here. Again, doesn't need to be addressed today, but something to keep in mind. /CC @willingc

It makes good sense to bring the two closer together. I would err on the side of clarity over length in the What's New as it's what most folks will read before or after the PEP tutorial.

willingc

Thanks @dmoisset. After the alpha goes out we can take a look at both this PR and the What's New again.

willingc · 2021-03-01T01:47:30Z

Doc/faq/design.rst

-consensus (yet) on whether and how to do range tests.  See :pep:`275` for
-complete details and the current status.
+For literal values, or constants within a namespace, you can also use a
+``match ... case`` statement.


Or update the question to be: Is there a switch or case statement in Python?

willingc · 2021-03-01T01:48:37Z

Doc/reference/lexical_analysis.rst

+Some identifiers are only reserved under specific contexts. These are known as
+*soft keywords*.  The identifiers ``match``, ``case`` and ``_`` can
+syntactically act as keywords in contexts related to the pattern matching
+statement, but this distinction is done at the parser level, not when


Good description.

Doc/reference/lexical_analysis.rst

willingc · 2021-03-01T01:54:31Z

Doc/tutorial/controlflow.rst

   ...

+
+.. _tut-match:


It makes good sense to bring the two closer together. I would err on the side of clarity over length in the What's New as it's what most folks will read before or after the PEP tutorial.

Co-authored-by: Carol Willing <[email protected]>

gvanrossum · 2021-03-01T03:30:55Z

I will land this tonight once the tests pass.

bedevere-bot · 2021-03-01T04:08:40Z

@gvanrossum: Please replace # with GH- in the commit message next time. Thanks!

dmoisset and others added 21 commits February 27, 2021 23:33

Add section on soft keywords "match" and "case"

f8ef095

Add tutorial on pattern matching

2a1b2e1

The tutorial is a slightly modified version of PEP-636 Appendix A

move index and link down to correct (original) location, add index fo…

83495ea

…r soft keywords

Add "_" as a soft keyword

4fda91c

Add __match_args__ to the data model

f07fe3e

Add versionadded to datamodel

72ce7cc

Rename __match_args__ section link

faa0450

object.__match_args__ -> class.__match_args__

0392e9c

Refer to match wherever the C switch statement was compared with Python.

e9a33ed

Brought up in https://bugs.python.org/msg387769

Revert "object.__match_args__ -> class.__match_args__"

734dfea

This reverts commit 6320747.

Refer to the PEP tutorial from the tutorial

cd736dd

Add half of PEP 634 (lots of TODOs left)

bdcf259

Co-Authored-By: Daniel F Moisset <[email protected]> Co-Authored-By: Guido van Rossum <[email protected]> Co-Authored-By: Brandt Bucher <[email protected]>

use better wording and add lots of lists and tables (still lots of TO…

0e2d768

…DOs left) one table idea was inspired by Raymond's awesome tweet here https://twitter.com/raymondh/status/1361780586570948609 Co-Authored-By: Raymond Hettinger <[email protected]>

done!

2790c6e

Apply suggested changes from code review by Daniel (part 1)

82aa7dc

Co-authored-by: Daniel F Moisset <[email protected]>

Apply final suggestions

ab3ca5a

Add link, make grammar and links consistent with rest of docs

26ef46d

touch up table

f13eb7f

Add the datamodel __match_args__ links in

43e9419

Apply suggestions from code review

3bb4f3f

Some minor typos, and copy/paste fixes

Fix documentation build errors

0b3d46a

the-knights-who-say-ni added the CLA signed label Feb 27, 2021

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Feb 27, 2021

blurb-it bot and others added 2 commits February 27, 2021 23:56

📜🤖 Added by blurb_it.

d0ce4d8

Clean linter issues

3d8cbd6

dmoisset mentioned this pull request Feb 28, 2021

Update compound statement reference dmoisset/cpython#3

Closed

Fidget-Spinner reviewed Feb 28, 2021

View reviewed changes

Doc/reference/lexical_analysis.rst Outdated Show resolved Hide resolved

Doc/reference/datamodel.rst Outdated Show resolved Hide resolved

Doc/reference/datamodel.rst Outdated Show resolved Hide resolved

*TypeError* -> :exc:TypeError in Doc/reference/datamodel.rst

afa3ca0

gvanrossum added the skip news label Feb 28, 2021

Fidget-Spinner and others added 7 commits February 28, 2021 10:07

Delete news file: shares same news as Brandt's PR

b9d1321

update link in compound statements

1f4d697

Better detail on what a soft keyword actually is

a55a396

Co-authored-by: Ken Jin <[email protected]>

Rework the sequence of steps in the overview

68e0251

This avoid some possible confusion present in the previous language, where it wasn't explicit that bindings happened before the guard was valuated

Add some comments to the example

7a2cb66

Made the irrefutable definition slightly more stricter

66f3435

Move table rows as apragraphs into the description of each pattern

e783adb

dmoisset marked this pull request as ready for review February 28, 2021 23:44

gvanrossum reviewed Mar 1, 2021

View reviewed changes

Apply my two specific suggestions from code review

f9e1193

willingc reviewed Mar 1, 2021

View reviewed changes

Final suggestion by Carol

6fafe4b

Co-authored-by: Carol Willing <[email protected]>

delete redundant paragraph since table is gone

365912c

gvanrossum merged commit a22bca6 into python:master Mar 1, 2021

bedevere-bot removed the awaiting review label Mar 1, 2021

Uh oh!

bpo-42128: Add documentation for pattern matching (PEP 634) #24664

bpo-42128: Add documentation for pattern matching (PEP 634) #24664

Uh oh!

Conversation

dmoisset commented Feb 27, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dmoisset commented Feb 28, 2021

Uh oh!

gvanrossum commented Feb 28, 2021

Uh oh!

Fidget-Spinner commented Feb 28, 2021

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dmoisset commented Feb 28, 2021

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

gvanrossum Mar 1, 2021

Choose a reason for hiding this comment

Uh oh!

willingc Mar 1, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gvanrossum Mar 1, 2021

Choose a reason for hiding this comment

Uh oh!

willingc Mar 1, 2021

Choose a reason for hiding this comment

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

willingc Mar 1, 2021

Choose a reason for hiding this comment

Uh oh!

willingc Mar 1, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

willingc Mar 1, 2021

Choose a reason for hiding this comment

Uh oh!

gvanrossum commented Mar 1, 2021

Uh oh!

bedevere-bot commented Mar 1, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

dmoisset commented Feb 27, 2021 •

edited

Loading