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

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 5e731bd5a6cbdb102b0d8c2652f036cc2d369458..82f2ab53451166c731b23ecb214cd180cc4e0e0b 100644 (file)
--- 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 (file)
index 0000000..20b5fd7
--- /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.