From 3a0b4b0eeeb0995259059ebfaa90d2e284fbb272 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 13 Oct 2023 09:45:45 +0200 Subject: [PATCH 1/2] 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 --- Doc/c-api/structures.rst | 6 ++++- Doc/c-api/type.rst | 50 +++++++++++++++++++++++++++++----------- 2 files changed, 41 insertions(+), 15 deletions(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 747cfa62294c21..25cb4ed40f63e7 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 0f58326f6c06b7..ccfd21186d147c 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 `) + + 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 `. + See :ref:`PyMemberDef documentation ` + 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 `) + (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. @@ -491,6 +504,15 @@ The following functions and structs are used to create :c:member:`~PyBufferProcs.bf_releasebuffer` are now available under the :ref:`limited API `. + .. versionchanged:: 3.12 + Uses of :c:member:`~PyTypeObject.tp_weaklistoffset` and + :c:member:`~PyTypeObject.tp_dictoffset` should now be avoided in favor + of the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` and + :c:macro:`Py_TPFLAGS_MANAGED_DICT` flags, if at all possible. + For cases where it's not possible (e.g. to support older versions + of Python), use the previous approach documented in + :ref:`PyMemberDef `. + .. c:member:: void *pfunc The desired value of the slot. In most cases, this is a pointer From dacc9957d89d4fec3c09aa87765fdef81445c46a Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 13 Oct 2023 12:37:05 +0200 Subject: [PATCH 2/2] Remove an older draft... --- Doc/c-api/type.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index ccfd21186d147c..5aaa8147dd3176 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -504,15 +504,6 @@ The following functions and structs are used to create :c:member:`~PyBufferProcs.bf_releasebuffer` are now available under the :ref:`limited API `. - .. versionchanged:: 3.12 - Uses of :c:member:`~PyTypeObject.tp_weaklistoffset` and - :c:member:`~PyTypeObject.tp_dictoffset` should now be avoided in favor - of the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` and - :c:macro:`Py_TPFLAGS_MANAGED_DICT` flags, if at all possible. - For cases where it's not possible (e.g. to support older versions - of Python), use the previous approach documented in - :ref:`PyMemberDef `. - .. c:member:: void *pfunc The desired value of the slot. In most cases, this is a pointer