[Python-checkins] bpo-43977: Update pattern matching language reference docs (GH-25917) (GH-26117)

[willingc]

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.