From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Fri, 13 Oct 2023 12:59:55 +0000 (+0200)
Subject: [3.12] gh-110803: Reorganize docs for what PyType_Slot doesn't cover (GH-110813)... 
X-Git-Tag: v3.12.1~301
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f2e353b9d85384f1e6320e8bd3e300a22994535a;p=thirdparty%2FPython%2Fcpython.git

[3.12] gh-110803: Reorganize docs for what PyType_Slot doesn't cover (GH-110813) (#110823)

gh-110803: Reorganize docs for what PyType_Slot doesn't cover (GH-110813)

* gh-110803: Reorganize docs for what PyType_Slot doesn't cover

- Cover the offset fields first
- Mention the old alternative for MANAGED flags, which is needed
  to support older Pythons
- De-emphasize the internal flags: use an inline list.
- Add a note to PyMemberDef saying what to do with it

* Remove an older draft...
(cherry picked from commit 2ab34f0e425d90d0a153104ef2f4343dce2a414d)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
---

diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index 747cfa62294c..25cb4ed40f63 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -406,7 +406,11 @@ Accessing attributes of extension types
 .. c:type:: PyMemberDef
 
    Structure which describes an attribute of a type which corresponds to a C
-   struct member.  Its fields are, in order:
+   struct member.
+   When defining a class, put a NULL-terminated array of these
+   structures in the :c:member:`~PyTypeObject.tp_members` slot.
+
+   Its fields are, in order:
 
    .. c:member:: const char* name
 
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index 0f58326f6c06..5aaa8147dd31 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -461,21 +461,34 @@ The following functions and structs are used to create
       * ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add`
       * ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length`
 
-      The following fields cannot be set at all using :c:type:`PyType_Spec` and
-      :c:type:`PyType_Slot`:
-
-      * :c:member:`~PyTypeObject.tp_dict`
-      * :c:member:`~PyTypeObject.tp_mro`
-      * :c:member:`~PyTypeObject.tp_cache`
-      * :c:member:`~PyTypeObject.tp_subclasses`
-      * :c:member:`~PyTypeObject.tp_weaklist`
+      The following “offset” fields cannot be set using :c:type:`PyType_Slot`:
+
+         * :c:member:`~PyTypeObject.tp_weaklistoffset`
+           (use :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead if possible)
+         * :c:member:`~PyTypeObject.tp_dictoffset`
+           (use :c:macro:`Py_TPFLAGS_MANAGED_DICT` instead if possible)
+         * :c:member:`~PyTypeObject.tp_vectorcall_offset`
+           (use ``"__vectorcalloffset__"`` in
+           :ref:`PyMemberDef <pymemberdef-offsets>`)
+
+         If it is not possible to switch to a ``MANAGED`` flag (for example,
+         for vectorcall or to support Python older than 3.12), specify the
+         offset in :c:member:`Py_tp_members <PyTypeObject.tp_members>`.
+         See :ref:`PyMemberDef documentation <pymemberdef-offsets>`
+         for details.
+
+      The following fields cannot be set at all when creating a heap type:
+
       * :c:member:`~PyTypeObject.tp_vectorcall`
-      * :c:member:`~PyTypeObject.tp_weaklistoffset`
-        (use :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead)
-      * :c:member:`~PyTypeObject.tp_dictoffset`
-        (use :c:macro:`Py_TPFLAGS_MANAGED_DICT` instead)
-      * :c:member:`~PyTypeObject.tp_vectorcall_offset`
-        (see :ref:`PyMemberDef <pymemberdef-offsets>`)
+        (use :c:member:`~PyTypeObject.tp_new` and/or
+        :c:member:`~PyTypeObject.tp_init`)
+
+      * Internal fields:
+        :c:member:`~PyTypeObject.tp_dict`,
+        :c:member:`~PyTypeObject.tp_mro`,
+        :c:member:`~PyTypeObject.tp_cache`,
+        :c:member:`~PyTypeObject.tp_subclasses`, and
+        :c:member:`~PyTypeObject.tp_weaklist`.
 
       Setting :c:data:`Py_tp_bases` or :c:data:`Py_tp_base` may be
       problematic on some platforms.