GeezerVison

Wouldn't it be better to mark this as Py_MOD_GIL_USED in the meantime, or are you trying to avoid the warning?

AFAIK, the situation is unchanged since Py_MOD_GIL_NOT_USED was added everywhere in #116882.

I think the intention is/was to make everything thread-safe before some stage of free-threading implementation?

I think we added that everywhere under the assumption that everything was already thread-safe, and anything that should be reported to us as a bug. I'm not sure that applies with our own test suite.

This is not really a test suite, it supposed to be an example/template showing how to use the Limited API.
The limited API was never compatible with free-threading (yet), so I don't think there's a bug?

There's an earlier PR, #110764, which did this (Py_NOGIL was later renamed to Py_GIL_DISABLED):

+#ifndef Py_NOGIL
 #define Py_LIMITED_API 0x030d0000
+#endif

... but that seems to defeat the point of this module :/

Maybe we should have not built these modules at all in free-threading builds, and skip the relevant tests?
Doing that now seems like wasted effort though, when mutexes/critical sections are a genuine TODO item for the limited API.

If it's a template, I'm a little concerned that people will see this and think "oh, this module is thread-safe", when it's really not. The comment helps, but I don't know what percentage of people will ignore it.

Before PyCriticalSection is added to the Stable ABI, we can use PyThread_acquire_lock for per-instance locking. (It's also a nice example of a non-PyObject resource that needs freeing.)

@colesbury, regarding your post on Discourse:

I think that’s just PyType_GetBaseByToken and PyType_GetModuleByToken. It seems pretty rare to need to call them from a tp_traverse handler. If really necessary, I think you can work around that in extensions by calling other APIs.

How would you implement the traverse function here?

Xxo is a subclassable type, and it should work on ABIs with different sizeof(PyObject) (i.e. free-threaded & GIL-ful).

By workaround I mean something like:

static Xxo_Type_spec = {
   ...
   .flags = Py_TPFLAGS_IMMUTABLETYPE | ...
};
...
static PyTypeObject *Xxo_Type;
...
Xxo_Type = state->Xxo_Type = (PyTypeObject*)PyType_FromModuleAndSpec(...);

static XxoObject_Data *
Xxo_get_data(PyObject *self)
{
    return PyObject_GetTypeData(self, Xxo_Type);
}

We could also avoid all this if we had a PyObject_GetTypeDataByToken().

static PyTypeObject *Xxo_Type;
...
Xxo_Type = state->Xxo_Type = (PyTypeObject*)PyType_FromModuleAndSpec(...);

That'll overwrite the pointer in a subinterpreter, or if you otherwise load several copies of the module. It's not something we can recommend.

Don't we have to call Py_DECREF(Str_Type) here (on error)?

Thanks for the catch!

I don't think that the (void*) cast is needed here:

Is the (void*) cast useful here?