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

brandtbucher · web-flow · commit 9387fac100db · 2021-05-02T15:35:00.000-07:00
diff --git 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
@@ -0,0 +1,2 @@
+Document the new :const:`Py_TPFLAGS_MAPPING` and
+:const:`Py_TPFLAGS_SEQUENCE` type flags.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Document the new :const:`Py_TPFLAGS_MAPPING` and
	`2`	+:const:`Py_TPFLAGS_SEQUENCE` type flags.