mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-03 08:34:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

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

Browse source 
* 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...
This commit is contained in:
Petr Viktorin 2023-10-13 14:51:48 +02:00 • committed by GitHub
parent 11bbe6c6e1
commit 2ab34f0e42
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 31 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

6
Doc/c-api/structures.rst
View file

@ -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

39
Doc/c-api/type.rst
View file

@ -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`:
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_dict`
* :c:member:`~PyTypeObject.tp_mro`
* :c:member:`~PyTypeObject.tp_cache`
* :c:member:`~PyTypeObject.tp_subclasses`
* :c:member:`~PyTypeObject.tp_weaklist`
* :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.