Skip to content

gh-124153: Add Py_tp_token support to xxlimited module #141644

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
gpshead wants to merge 1 commit into
base: main
Choose a base branch
from
+31 −4
Draft

gh-124153: Add Py_tp_token support to xxlimited module #141644

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Add Py_tp_token support to xxlimited module 
Implement the TODO at line 99-100 to add Py_tp_token slot support,
demonstrating Python 3.14 type checking best practices for Limited
C API extension modules.

Changes to Modules/xxlimited.c:
- Update Limited API version from 3.13 (0x030d0000) to 3.14 (0x030e0000)
- Add Py_tp_token slot with Py_TP_USE_SPEC to Xxo_Type_slots

Changes to Doc/howto/isolating-extensions.rst:
- Add new "Type Checking with Heap Types" section documenting Py_tp_token
- Reference xxlimited.c as example and link to gh-124153

This addresses the type-checking problem for heap types described in
PEP 630 and aligns with the documentation modernization effort
(gh-134160). The xxlimited module now serves as a complete example
of modern isolated extension module development.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
  • Loading branch information
@gpshead @claude
gpshead and claude committed Nov 17, 2025
commit 93b525f453a5a5795c032c0fb0f3588820bbb26c
28 changes: 28 additions & 0 deletions Doc/howto/isolating-extensions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,34 @@ safe access from C) and the module's ``__dict__`` (for access from
Python code).


Type Checking with Heap Types
------------------------------

.. versionadded:: 3.14

Heap types defined with :c:func:`PyType_FromModuleAndSpec` can use the
:c:data:`Py_tp_token` slot to enable type checking across module boundaries
and inheritance hierarchies.

Setting ``Py_tp_token`` to :c:data:`Py_TP_USE_SPEC` uses the
:c:type:`PyType_Spec`'s address as a unique identifier. This allows
:c:func:`PyType_GetBaseByToken` to search the :term:`method resolution order`
for types with compatible memory layouts::

static PyType_Slot MyType_slots[] = {
{Py_tp_token, Py_TP_USE_SPEC},
// ... other slots
};

This addresses the type-checking problem for heap types described in
:pep:`630#type-checking`. See the
`xxlimited module <https://github.com/python/cpython/blob/main/Modules/xxlimited.c>`__
for a complete example.

For details, see :c:data:`Py_tp_token` and :c:func:`PyType_GetBaseByToken`
(added in :gh:`124153`).


Garbage-Collection Protocol
---------------------------

Expand Down
7 changes: 3 additions & 4 deletions Modules/xxlimited.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,10 +64,10 @@
pass
*/

// Need limited C API version 3.13 for Py_mod_gil
// Need limited C API version 3.14 for Py_tp_token
#include "pyconfig.h" // Py_GIL_DISABLED
#ifndef Py_GIL_DISABLED
# define Py_LIMITED_API 0x030d0000
# define Py_LIMITED_API 0x030e0000
Copy link
Copy Markdown
Member

@encukou encukou Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about copying the original to xxlimited_3_13.c, so we have an example for older stable ABI?

#endif

#include "Python.h"
Expand Down Expand Up @@ -96,8 +96,6 @@ typedef struct {
} XxoObject;

#define XxoObject_CAST(op) ((XxoObject *)(op))
// TODO: full support for type-checking was added in 3.14 (Py_tp_token)
// #define XxoObject_Check(v) Py_IS_TYPE(v, Xxo_Type)

static XxoObject *
newXxoObject(PyObject *module)
Expand Down Expand Up @@ -298,6 +296,7 @@ static PyGetSetDef Xxo_getsetlist[] = {


static PyType_Slot Xxo_Type_slots[] = {
{Py_tp_token, Py_TP_USE_SPEC},
{Py_tp_doc, (char *)Xxo_doc},
{Py_tp_traverse, Xxo_traverse},
{Py_tp_clear, Xxo_clear},
Expand Down
Loading