[Python-checkins] bpo-43977: Update pattern matching language reference docs (GH-25917) (GH-26117)
willingc
webhook-mailer at python.org
Fri May 14 01:55:47 EDT 2021
https://github.com/python/cpython/commit/e7d25d3f3b335eb46d102137b447325f54750e31
commit: e7d25d3f3b335eb46d102137b447325f54750e31
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: willingc <carolcode at willingconsulting.com>
date: 2021-05-13T22:55:41-07:00
summary:
bpo-43977: Update pattern matching language reference docs (GH-25917) (GH-26117)
* Update patma language reference with new changes to sequence and mapping
* update 3.10 whatsnew too
(cherry picked from commit 53c91ac5253bf1cb3cb20e1345e798a53f4c3517)
Co-authored-by: Ken Jin <28750310+Fidget-Spinner at users.noreply.github.com>
Co-authored-by: Ken Jin <28750310+Fidget-Spinner at users.noreply.github.com>
files:
M Doc/reference/compound_stmts.rst
M Doc/whatsnew/3.10.rst
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 77400a8d8504f3..0274095feffdef 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -822,7 +822,7 @@ and binds no name. Syntax:
``_`` is a :ref:`soft keyword <soft-keywords>` within any pattern,
but only within patterns. It is an identifier, as usual, even within
-``match`` headers, ``guards``, and ``case`` blocks.
+``match`` subject expressions, ``guard``\ s, and ``case`` blocks.
In simple terms, ``_`` will always succeed.
@@ -900,8 +900,8 @@ sequence pattern.
The following is the logical flow for matching a sequence pattern against a
subject value:
-#. If the subject value is not an instance of a
- :class:`collections.abc.Sequence` the sequence pattern fails.
+#. If the subject value is not a sequence [#]_, the sequence pattern
+ fails.
#. If the subject value is an instance of ``str``, ``bytes`` or ``bytearray``
the sequence pattern fails.
@@ -943,7 +943,7 @@ subject value:
In simple terms ``[P1, P2, P3,`` ... ``, P<N>]`` matches only if all the following
happens:
-* ``isinstance(<subject>, collections.abc.Sequence)``
+* check ``<subject>`` is a sequence
* ``len(subject) == <N>``
* ``P1`` matches ``<subject>[0]`` (note that this match can also bind names)
* ``P2`` matches ``<subject>[1]`` (note that this match can also bind names)
@@ -975,8 +975,7 @@ runtime error and will raise :exc:`ValueError`.)
The following is the logical flow for matching a mapping pattern against a
subject value:
-#. If the subject value is not an instance of :class:`collections.abc.Mapping`,
- the mapping pattern fails.
+#. If the subject value is not a mapping [#]_,the mapping pattern fails.
#. If every key given in the mapping pattern is present in the subject mapping,
and the pattern for each key matches the corresponding item of the subject
@@ -993,7 +992,7 @@ subject value:
In simple terms ``{KEY1: P1, KEY2: P2, ... }`` matches only if all the following
happens:
-* ``isinstance(<subject>, collections.abc.Mapping)``
+* check ``<subject>`` is a mapping
* ``KEY1 in <subject>``
* ``P1`` matches ``<subject>[KEY1]``
* ... and so on for the corresponding KEY/pattern pair.
@@ -1526,6 +1525,35 @@ body of a coroutine function.
there is a :keyword:`finally` clause which happens to raise another
exception. That new exception causes the old one to be lost.
+.. [#] In pattern matching, a sequence is defined as one of the following:
+
+ * a class that inherits from :class:`collections.abc.Sequence`
+ * a Python class that has been registered as :class:`collections.abc.Sequence`
+ * a builtin class that has its (CPython) :data:`Py_TPFLAGS_SEQUENCE` bit set
+ * a class that inherits from any of the above
+
+ The following standard library classes are sequences:
+
+ * :class:`array.array`
+ * :class:`collections.deque`
+ * :class:`list`
+ * :class:`memoryview`
+ * :class:`range`
+ * :class:`tuple`
+
+ .. note:: Subject values of type ``str``, ``bytes``, and ``bytearray``
+ do not match sequence patterns.
+
+.. [#] In pattern matching, a mapping is defined as one of the following:
+
+ * a class that inherits from :class:`collections.abc.Mapping`
+ * a Python class that has been registered as :class:`collections.abc.Mapping`
+ * a builtin class that has its (CPython) :data:`Py_TPFLAGS_MAPPING` bit set
+ * a class that inherits from any of the above
+
+ The standard library classes :class:`dict` and :class:`types.MappingProxyType`
+ are mappings.
+
.. [#] A string literal appearing as the first statement in the function body is
transformed into the function's ``__doc__`` attribute and therefore the
function's :term:`docstring`.
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index 9394ee7d6223ba..c15bb326938097 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -589,7 +589,7 @@ Several other key features:
- Like unpacking assignments, tuple and list patterns have exactly the
same meaning and actually match arbitrary sequences. Technically,
- the subject must be an instance of ``collections.abc.Sequence``.
+ the subject must be a sequence.
Therefore, an important exception is that patterns don't match iterators.
Also, to prevent a common mistake, sequence patterns don't match strings.
More information about the Python-checkins
mailing list