bpo-43977: Update pattern matching language reference docs (GH-25917)

* Update patma language reference with new changes to sequence and mapping

* update 3.10 whatsnew too

diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 77400a8d8504f3e3e8ee871d32a8bcd1b955a587..0274095feffdefd8e3774c27fbaa00ed7b534590 100644 (file)
--- 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 9394ee7d6223ba4f64623b8cfbc9bb6df9740c04..c15bb32693809762e2c14c6656187c0b787e4412 100644 (file)
--- 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.