[Python-checkins] bpo-43977: Document the new pattern matching type flags (GH-25734)

[brandtbucher]

https://github.com/python/cpython/commit/9387fac100db359cbb6ec2a76f8a5eba8f9d7b65
commit: 9387fac100db359cbb6ec2a76f8a5eba8f9d7b65
branch: master
author: Brandt Bucher <brandt at python.org>
committer: brandtbucher <brandtbucher at gmail.com>
date: 2021-05-02T15:35:00-07:00
summary:

bpo-43977: Document the new pattern matching type flags (GH-25734)

files:
A Misc/NEWS.d/next/Documentation/2021-04-29-15-06-03.bpo-43977.K5aSl1.rst
M Doc/c-api/typeobj.rst

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 5e731bd5a6cbd..82f2ab5345116 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1219,6 +1219,50 @@ and :c:type:`PyType_Type` effectively act as defaults.)
       .. versionadded:: 3.10
 
 
+   .. data:: Py_TPFLAGS_MAPPING
+
+      This bit indicates that instances of the class may match mapping patterns
+      when used as the subject of a :keyword:`match` block. It is automatically
+      set when registering or subclassing :class:`collections.abc.Mapping`, and
+      unset when registering :class:`collections.abc.Sequence`.
+
+      .. note::
+
+         :const:`Py_TPFLAGS_MAPPING` and :const:`Py_TPFLAGS_SEQUENCE` are
+         mutually exclusive; it is an error enable both flags simultaneously.
+
+      **Inheritance:**
+
+      This flag is inherited by types that do not already set
+      :const:`Py_TPFLAGS_SEQUENCE`.
+
+      .. seealso:: :pep:`634` -- Structural Pattern Matching: Specification
+
+      .. versionadded:: 3.10
+
+
+   .. data:: Py_TPFLAGS_SEQUENCE
+
+      This bit indicates that instances of the class may match sequence patterns
+      when used as the subject of a :keyword:`match` block. It is automatically
+      set when registering or subclassing :class:`collections.abc.Sequence`, and
+      unset when registering :class:`collections.abc.Mapping`.
+
+      .. note::
+
+         :const:`Py_TPFLAGS_MAPPING` and :const:`Py_TPFLAGS_SEQUENCE` are
+         mutually exclusive; it is an error enable both flags simultaneously.
+
+      **Inheritance:**
+
+      This flag is inherited by types that do not already set
+      :const:`Py_TPFLAGS_MAPPING`.
+
+      .. seealso:: :pep:`634` -- Structural Pattern Matching: Specification
+
+      .. versionadded:: 3.10
+
+
 .. c:member:: const char* PyTypeObject.tp_doc
 
    An optional pointer to a NUL-terminated C string giving the docstring for this
diff --git a/Misc/NEWS.d/next/Documentation/2021-04-29-15-06-03.bpo-43977.K5aSl1.rst b/Misc/NEWS.d/next/Documentation/2021-04-29-15-06-03.bpo-43977.K5aSl1.rst
new file mode 100644
index 0000000000000..20b5fd7ab86fa
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-04-29-15-06-03.bpo-43977.K5aSl1.rst
@@ -0,0 +1,2 @@
+Document the new :const:`Py_TPFLAGS_MAPPING` and
+:const:`Py_TPFLAGS_SEQUENCE` type flags.