diff options
| -rw-r--r-- | Doc/reference/compound_stmts.rst | 42 | ||||
| -rw-r--r-- | Doc/whatsnew/3.10.rst | 2 |
2 files changed, 36 insertions, 8 deletions
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 77400a8..0274095 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 9394ee7..c15bb32 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. |