PEP 820 – PySlot: Unified slot system for the C API

encukou · 2026-01-26T09:53:42.308Z

Mark Shannon:

What do you anticipate _sl_reserved being used for, or is it really just padding?

Just padding now, but reserved for possible future improvements.
In an earlier iteration of the idea, arrays (of slots, MethodDefs ,etc.) could explicit size instead of zero-terminated. You’d set a flag, and put the size here.
I now don’t think this feature is worth the complexity, and I doubt it’ll ever be, but there might be something like it.

Mark Shannon:

I thought we generally avoided anonymous unions in the API, as C++ doesn’t support them.

tl;dr: it’s unions that are a bit problematic; we don’t gain anything by avoiding anonymous unions.

For the long story: C++ supports anonymous unions, but:

They’re only supported in C since C11. But we already require the feature.^[1]
Until C++20 which adds C-style designated initializers, C++ initializers only allow setting the first member of a union. But that’s an issue for named unions as well.
The PEP proposes workaround macros (PySlot_PTR & PySlot_PTR_STATIC) for use in C++11-compatible code.
C++ doesn’t have anonymous structs (which is irrelevant here but it’s what always confuses me)

We don’t necessarily require the standard spelling: the _Py_ANONYMOUS macro can request a compiler extension. ↩︎

encukou · 2026-01-28T21:59:00.253Z

I’ve updated the PEP a bit:

Be clearer that the PEP 793 API added in 3.15 alpha (PyModExport, PyModule_FromSlotsAndSpec) will be changed to return the new slots.
Deprecation of things that were documented to not work, but worked in practice:
- setting a slot value to NULL (except if the slot explicitly allows this)
- repeating a slot ID in a definition (except )
As with all deprecations, happy to hear use cases for un-deprecation.
Added “third-party slot ID allocation” and “avoiding anonymous unions” to Rejected Ideas.

vstinner · 2026-01-29T15:26:06.873Z

Hi,

Thanks for this interesting PEP. I read it multiple times but so I far I failed to make my opinion about it. I’m not convinced yet that it’s worth it. But at the same time, I’m not strongly against it neither.

PEP 820 adds many features: typed union, nested slots, single identifier space, optional slot, “has fallback” slot, etc. In exchange, it requires C extension maintainers to update their code from PyType_FromSpec()/PyModuleDef_Init() APIs to PyType_FromSlots()/PyModule_FromSlotsAndSpec(). Since new functions are not available on Python 3.14 and older, C extensions should continue maintaining existing code (using PyType_FromSpec()/PyModuleDef_Init()). At least, “nested slots” should allow to reuse code. But I’m not convinced yet that this migration is worth it.

“Motivation: Type safety”: casting to void* is “technically undefined or implementation-defined behaviour in C”. Well ok, but in practice, it just works for many years and I’m not aware of any open issue about this cast.

Optional slot (PySlot_OPTIONAL): “If the slot ID is unknown, the interpreter should ignore the slot entirely”. We can modify PyType_FromSpec()/PyModuleDef_Init() to ignore unknown slots which would allow building a single C extension working on old and new Python versions (useful for the stable ABI).

PySlot_HAS_FALLBACK: if tp_getattr is being deprecated/removed, PyType_FromSpec() can ignore silently the Py_tp_getattr slot and require the Py_tp_getattro slot. I’m not convinced that PySlot_HAS_FALLBACK is needed (and it looks a little bit complicated to use).

I also have concerns about the macros used to define a slot, such as PySlot_DATA(). They require C11 but I’m not sure that all C extensions can already use C11. The anonymous union may also cause C compatibility issues.

If I put all my concerns aside, sure, an unified API to define types and modules is appealing. It should help the stable ABI in the future. It can be stricter than the previous API, and avoids corner cases (slots set to NULL, slots defined multiple times).

encukou · 2026-01-29T15:48:32.675Z

Victor Stinner:

But I’m not convinced yet that this migration is worth it.

Same here.
But, if we want this, we want it in 3.15. This is the iteration I have now.

Victor Stinner:

Since new functions are not available on Python 3.14 and older, C extensions should continue maintaining existing code (using PyType_FromSpec()/PyModuleDef_Init()). At least, “nested slots” should allow to reuse code. But I’m not convinced yet that this migration is worth it.

But, they can continue using only PyType_FromSpec()/PyModuleDef_Init(), unless they want some slots-related feature that’s new in 3.15 (and so they’re modifying code anyway). For other extensions there should be no need to migrate immediately, or to maintain two sets of init data.

Victor Stinner:

PySlot_OPTIONAL: […] We can modify PyType_FromSpec()/PyModuleDef_Init() to ignore unknown slots

Silently dropping features on older Python versions is sometimes the right thing to do, but not always. IMO, users are the best judge of that.

Victor Stinner:

I’m not convinced that PySlot_HAS_FALLBACK is needed

It’s the easiest API I could find for dealing with CPython replacing one slot with another (a better, upgraded version), if you want to use the improvement but also support CPythons before the change.
It’s not needed, but not having it is making it hard to evolve the API.

Victor Stinner:

I also have concerns about the macros used to define a slot, such as PySlot_DATA(). They require C11 but I’m not sure that all C extensions can already use C11.

That’s fine. They can use PySlot_PTR, no shame. They lose some type safety, which is (IMO) good to provide for languages that can initialize unions.

Victor Stinner:

The anonymous union may also cause C compatibility issues.

There’s a rather extensive section on that. Do you have any concrete issues that aren’t covered?

Victor Stinner:

If I put all my concerns aside, sure, an unified API to define types and modules is appealing.

Yeah. This is a long-term thing. There’ll never be a time when it’s needed, but over the years there have been so many times when I’ve wanted it.
And the interaction with PEP 793 (PyModExport) means that if we want this, we should put it in 3.15. (If we don’t, we’ll want yet another module export hook to return new slots, and that’s not likely to happen.)

vstinner · 2026-03-05T16:43:34.702Z

I’m sorry, I still don’t get the rationale for adding yet another API for types and modules. I don’t see which concrete issues are being addressed by the new PySlot API. To me, PySlot would be a nice API to have, but I don’t think that it’s worth the cost of the migration and having to support a new API.

Petr Viktorin:

But, they can continue using only PyType_FromSpec()/PyModuleDef_Init(), unless they want some slots-related feature that’s new in 3.15 (and so they’re modifying code anyway).

If existing extensions don’t have to migrate to the new API, which projects/use cases will need the new API? Is it an API for new C extensions which only support recent Python versions (3.15 and newer)?

To me, type safety is nice to have, but it’s not really a problem which is preventing developers to write C extensions. The current API just works in practice.

An unified namespace for all slots is nice to have, but I’m fine with the current two namespaces (module slots and type slots).

As I wrote previously, PySlot_OPTIONAL and PySlot_HAS_FALLBACK can be implemented differently, by modifying PyType_FromSpec() to ignore old/deprecated slots and ignore unknown slots (from a more recent Python version).

One of the biggest compatibility issue related to type definition that I recall is https://bugs.python.org/issue37250 : when printfunc tp_print; has been replaced with Py_ssize_t tp_vectorcall_offset; in PyTypeObject. It broke C code generated by Cython which assigned tp_print to 0. If I understand correctly, this issue can already be avoided using PyType_FromSpec() which can silently ignore old/removed tp_print slot.

makes it cumbersome to add/obsolete/adjust the required info (for example, in PEP 697 I gave meaning to negative values of an existing field; adding a new field would be cleaner in similar situations);

You can already add a new slot ID using existing PyType_FromSpec() API, no?

encukou · 2026-03-06T14:26:18.885Z

Victor Stinner:

If existing extensions don’t have to migrate to the new API, which projects/use cases will need the new API? Is it an API for new C extensions which only support recent Python versions (3.15 and newer)?

Yes.
We won’t be able to add optional slots functionality in the version where they would be more useful. They need to be supported in the previous version.

Victor Stinner:

To me, type safety [and] unified namespace for all slots is nice to have

Indeed; that’s a nice to have and an implementation detail.

Victor Stinner:

As I wrote previously, PySlot_OPTIONAL and PySlot_HAS_FALLBACK can be implemented differently, by modifying PyType_FromSpec() to ignore old/deprecated slots and ignore unknown slots (from a more recent Python version).

They can not. Ignoring unknown slots means removing the error checking – if a slot is required but the interpreter doesn’t support it, it would be silently ignored.
Optionality needs to be opt-in.

To show some recent examples: NumPy has code like:

#if PY_VERSION_HEX >= 0x030c00f0  // Python 3.12+
    {Py_mod_multiple_interpreters, Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED},
#endif
#if PY_VERSION_HEX >= 0x030d00f0  // Python 3.13+
    // signal that this module supports running without an active GIL
    {Py_mod_gil, Py_MOD_GIL_NOT_USED},
#endif

#ifdef is not compatible with the stable ABI
this uses version detection rather than feature detection, which is problematic for alternate implementations. For example, PyPy or MicroPython would implement all (or most) of a given Python version but also some features from newer versions.
Of course, there currently aren’t that many alternate implementations of the C API – but that’s partly because we don’t care about them :‍)

These particular slots are “ignorable”, so yes, this issue could be solved by making Python ignore unknown slots.
But, if we added a slot like Py_tp_metaclass, Python should probably error out if it doesn’t support the feature.

Another example: PyO3 wants to specify Py_mod_name & co. when using PyModExport, but not when using PyModuleDef. There’s a workaround they can use, but if we had PEP 820 nested slots, that workaround wouldn’t be necessary. (Again – you need PEP 820 before it’ll be useful.)

Or: the PyType_From* family of functions grows a new function every time it needs some information that’s not a good fit for immutable static data: PyType_FromSpec only had the spec, then bases was added, then module, then metaclass.
Nested slots array allow specifying such values in a small slots array on the stack, and refer to a big static array for the “regular” static slots.

vstinner · 2026-03-06T17:32:12.055Z

Thanks for additional examples of slots, it helps me to understand the big picture.

So if I understand correctly, PyType_FromModuleAndSpec() and PyType_FromMetaclass() were added instead of adding Py_tp_module and Py_tp_metaclass, because slots are almost always defined at the module level as a static array like static PyType_Slot type_slots[] = {...};. Interesting. I now see better the advantage of nested slots:

static PySlot type_static_slots[] = {
    ...  // values known at build time
};

static int
init_type(PyObject *module)
{
    PySlot type_dynamic_slots[] = {
        ... // values only known at runtime
        PySlot_PTR(Py_tp_slots, type_static_slots),
        PySlot_END,
    };

    state->type = PyType_FromSlots(type_dynamic_slots);
    ...
}

For example, the module isn’t known at build time, but it can only be used in “dynamic slots”.

For PySlot_OPTIONAL, if I understood correctly the use case, the idea is to build an extension with Python 3.16 and new slots which only exists in Python 3.16, but mark these slots as “optional” to be able to use this extension on Python 3.15: so PyType_Slots() know that these unknown slots should be ignored.

Petr Viktorin:

But, if we added a slot like Py_tp_metaclass, Python should probably error out if it doesn’t support the feature.

If I understand correctly, all slots added after Python 3.15 should be used with PySlot_OPTIONAL. That’s not convenient. I would instead expect PyType_Slots() to ignore all “new” slots by default.

But if we add a new “mandatory” slot in Python 3.16, it should not be silently ignored by Python 3.15 (but fail with an error). In that case, I would prefer to mark such specific slot as PySlot_MANDATORY.

I don’t understand the PySlot_HAS_FALLBACK example with tp_getattr to tp_getattro.

For me, it seems easy to modify PyType_FromSlots() to handle migrations. For example, if tp_getattr and tp_getattro are defined, only use tp_getattro (and ignore tp_getattr). I don’t see how it would be better to implement the migration logic in slots.

I would prefer to remove PySlot_HAS_FALLBACK for now.

encukou · 2026-03-09T08:10:16.515Z

Victor Stinner:

If I understand correctly, all slots added after Python 3.15 should be used with PySlot_OPTIONAL. That’s not convenient. I would instead expect PyType_Slots() to ignore all “new” slots by default.

But if we add a new “mandatory” slot in Python 3.16, it should not be silently ignored by Python 3.15 (but fail with an error). In that case, I would prefer to mark such specific slot as PySlot_MANDATORY.

We could do that, but:

The behaviour would be more error-prone: when you take a codebase and compile it for an earlier version of Python, some slots would be silently ignored. I’d much prefer only ignoring things if the user code explicitly says it’s OK.
Currently, all slots are “mandatory”. To preserve the behaviour, when you convert from “old” slots to PySlot, all of them would need the flag.

Victor Stinner:

I would prefer to remove PySlot_HAS_FALLBACK for now.

OK. This one can be added later, in the version that needs it.

encukou · 2026-03-13T12:20:11.982Z

I’ve removed PySlot_HAS_FALLBACK from the PEP. How does it look now?

da-woods · 2026-03-14T13:46:49.696Z

Connor J Gibson:

Currently (in 3.14) __slots__ […]

My feeling is that this is pretty unrelated to the this PEP. This PEP is describing changes to how extension types and modules are initialized from C. That probably doesn’t actually lead to any changes to how any Python type is structured once it’s been created.

nextdoortech · 2026-03-14T21:31:23.314Z

Da Woods:

This PEP is describing changes to how extension types and modules are initialized from C.

I suppose I should clarify: I might be wrong, but I’m 99.9% sure that the restriction disallowing multiple parent classes with __slots__ was originally put in place only because of the way slots entries are (currently) handled in C – child class __slots__ are appended to the (sole) parent’s C struct so that parent methods accessing inherited slots can use the same pointer offset as they would in the parent class.

There seems to be no language-theoretical reason that Python should disallow multiple inheritance with slots, but again, I could be completely wrong.

If this PEP would completely rework the C backend to __slots__ then it may also remove the limitation mentioned above. I’m specifically looking at this part of the PEP:

Nested slot tables

In this proposal, the array of slots can reference another array of slots, which is treated as if it was merged into its “parent”, recursively. This complicates slot handling inside the interpreter, but allows:

Mixing dynamically allocated (or stack-allocated) slots with static ones. This solves the issue that lead to the PyType_From* family of functions expanding with values that typically can’t be static. For example, the module argument to PyType_FromModuleAndSpec() should be a heap-allocated module object.

Sharing a subset of the slots to implement functionality common to several classes/modules.

Easily including some slots conditionally, e.g. based on the Python version.

If the array of slots can reference another array, then wouldn’t that allow two disjoint inherited arrays from different parents to be contained in the same child? If so, then the limitation on multiple inheritance could be safely removed.

gcewing · 2026-03-15T02:26:01.000Z

There are two different meanings of the word “slot” being used in this
discussion: type slots, which live in the type are function pointers to
implementations of the type’s methods, and instance slots, which live in
the instance and hold values of instance variables.

If I understand correctly, this PEP is only concerned with type slots,
not instance slots, so it won’t affect the way the |slots| mechanism
works.

However, it seems to me that it wouldn’t be difficult to remove the
limitation on |slots| inheritance by recomputing the offsets of all
of a class’s instance slots when the class is created, instead of
inheriting the offsets of the base class’s slots.

I’m not sure if it would be advisable to do this, because it might break
extension modules that make assumptions about the layout of an object’s
C struct.

In any case, this ought to be the subject of another PEP, since it’s an
independent issue.

vstinner · 2026-03-17T16:49:19.079Z

tl;dr Ok, I’m now convinced that treating all slots as mandatory by default is a sane behavior for backward and forward compatibility. Only slots explicitly marked with PySlot_OPTIONAL should be ignored.

Petr Viktorin:

We could do that, but:

The behaviour would be more error-prone: when you take a codebase and compile it for an earlier version of Python, some slots would be silently ignored. I’d much prefer only ignoring things if the user code explicitly says it’s OK.

Currently, all slots are “mandatory”. To preserve the behaviour, when you convert from “old” slots to PySlot, all of them would need the flag.

Hum. Let me took at type slots added over the last years:

Py_nb_matrix_multiply (Python 3.5).
Py_tp_module (PEP 820).
Py_tp_metaclass (PEP 820).
Py_tp_token (Python 3.14).
Py_tp_vectorcall (Python 3.14).
Py_am_send (Python 3.10).
Py_tp_finalize (Python 3.5).
Python 3.11 added Py_bf_getbuffer and Py_bf_releasebuffer to the limited C API.
Special tp_pypy_flags: only available on PyPy.

MANDATORY: IMO PyType_FromSlots() should fail if it gets the following unknown slots: Py_tp_metaclass, Py_am_send.

OPTIONAL: IMO it should be safe to silently ignore the following slots if they are unknown: Py_nb_matrix_multiply, Py_tp_module, Py_tp_token, Py_tp_vectorcall, Py_tp_finalize, tp_pypy_flags. But I’m not sure that an extension would work as expected if some type slots are silently ignored…

What if the extension uses PyType_GetModuleByToken() whereas Py_tp_token is ignored? The function is likely to fail which is not the behavior expected by the extension (written for a Python version which understands Py_tp_token). It can lead to crashes if the extension doesn’t handle PyType_GetModuleByToken() failures.

If Py_tp_finalize is silently ignored, the extension may leak memory since the finalization code is ignored.

If Py_bf_getbuffer and Py_bf_releasebuffer are silently ignored by Python 3.10, the object doesn’t implement the buffer protocol and operations such as memoryview(obj) start failing.

Hum. It seems like it would be safer to treat all of these slots as “mandatory” by default, and only ignore them if they are marked with an explicit PySlot_OPTIONAL.

Ok, I’m convinced that treating all slots as mandatory by default is a sane behavior for backward and forward compatibility.

vstinner · 2026-03-17T17:02:48.986Z

I changed my mind and I’m now a supporter of PEP 820 It took me a while but I now see the PEP 820 advantages: it enhances the backward compatibility and the stable ABI.

PEP 820 avoids the need to add new PyType_FromXXX() functions when new members/slots are added thanks to the ability to define some slots on the heap memory, and some others as static data. It helps with backward compatibility, before new functions were not available on old Python versions preventing to import the extension module.

PEP 820 enhances the backward compatibility by allowing to skip new slots on an old Python version using the PySlot_OPTIONAL flag. It’s useful for the stable ABI: a single binary works on multiple Python versions.

There are some other nice features, not really needed but good to have:

Unique namespace for slot identifiers (instead of 2 before: type and module slots).
Type safety: replace void* with an union.

encukou · 2026-03-18T13:29:21.444Z

Thank you!

Submitted to the SC: PEP 820 – PySlot: Unified slot system for the C API · Issue #337 · python/steering-council · GitHub

I’ve also added a section with some quotes from this thread.

encukou · 2026-03-18T13:38:17.380Z

Connor J Gibson:

Currently (in 3.14) __slots__ has a limitation that prevents a child class from inheriting from two parents which both define __slots__:
[…]
I understand why this limitation would be in place from the standpoint of the underlying cPython implementation (i.e. having the offsets for slots within the underlying c struct be constant for all children; whereas multiple inheritance would cause offset collisions and create complications for inherited functions), but surely this could be worked around.

An unrelated issue, as noted before. Type/module slots aren’t __slots__. (Dear admins, could you split this thread of discussion to Ideas?)

The usual workaround is using normal Python attributes, rather than __slots__.

thomas · 2026-04-21T11:39:24.852Z

(Posting for the SC.)

The Steering Council is reviewing PEP 820 and we are mostly positive, but we have a few concerns. We realize that the PEP came out of the discussions around PEP 793 (PyModExport: A new entry point for C extension modules) and that it would be convenient to make these changes in Python 3.15 to avoid backward compatibility concerns, but we struggle a little with the motivation for this specific design.

Nested slot tables, in particular, seem like a complex feature with no justification other than “it seems useful”, and perhaps as a generalization of PyType_Slot and PyModuleDef_Slot arrays. The arbitrary limit on nesting, for example: what use-cases do you see for nested slots that make the limit of 5 reasonable?

We’re also a little skeptical about the type safety claims the PEP makes about the new API. While the new API makes it harder to pass the wrong data type to a slot-setting macro (like passing a string to PySlot_FUNC), it does nothing to protect from using the wrong slot-setting macro for a particular slot (like PySlot_STATIC(tp_repr, "<myclass repr>")). The new API is marginally better, but the question is if that’s a good enough reason to add yet another type/module initialization API. Is this really the best API we can come up with, long term, or are we expected to see yet another new API to further improve the type safety?

Lastly, we’re concerned about the new deprecation warnings for existing users of slots that may be setting slots to NULL. We don’t want to flood users with warnings for things that are outside of their control. It would be much better if the deprecation warnings were only issued for uses of the new APIs, unless we’re really confident the only cases that would produce the deprecation warning are, in fact, problematic situations. From the description of the state of affairs that doesn’t seem to be the case.

We would also like to invite extension authors to weigh in on the discussion here, if there are any concerns. While we take objections from third-party authors seriously, we wouldn’t necessarily expect active endorsement from them as this PEP probably doesn’t materially make their lives easier. We just want to make sure that we aren’t making it dramatically harder.

We know time is running out for Python 3.15, but we would appreciate your opinion on these concerns before we decide on this PEP.

encukou · 2026-04-21T13:15:04.207Z

Thank you for considering the PEP!

Thomas Wouters:

Nested slot tables, in particular, seem like a complex feature with no justification other than “it seems useful”

The justification is in the rationale – Nested slot tables & Nested “legacy” slot tables.

The key use cases are mixing static & heap tables, and migrating from the old format. Both are rather important.

Thomas Wouters:

The arbitrary limit on nesting, for example: what use-cases do you see for nested slots that make the limit of 5 reasonable?

The limit is supposed to be unreasonable; you shouldn’t hit it in practice :‍)

You need roughly up to one level of nesting for each feature listed in the rationale (mixing static & heap tables, migrating from the old format, sharing slots, including slots conditionally), but I don’t think you’d need all of them at once.
I expect two levels to be common for migrating from the old format (i.e. PyModInit & PyModExport sharing an old-style slots array); nested array (with the slot ID as a “format header”) is the most natural API I found for that. Limiting to 2 levels wouldn’t simplify the implementation much.

Thomas Wouters:

We’re also a little skeptical about the type safety claims the PEP makes about the new API.

Yeah, type safety is mainly about avoiding undefined behavior: data⭤function pointer casts. (This is not an issue in current compilers, and probably won’t become a problem in new platforms, but as Python/emscripten_trampoline.c shows, even new platforms can be “weird”.)

(And also about having an explicit number of bits for flags in a slots – as we drop 32 platforms, we could easily start relying on 64-bit intptr_t, making the API unportable back to 32 bits.)

Thomas Wouters:

The new API is marginally better, but the question is if that’s a good enough reason to add yet another type/module initialization API. Is this really the best API we can come up with, long term, or are we expected to see yet another new API to further improve the type safety?

This is not the best API, but IMO it’s ready for making incremental improvements rather than adding yet another API. (In particular, I’m thinking about slot-specific macros, i.e. instead of PySlot_FUNC(tp_repr, myClass_repr) you’d do something PySlot_tp_repr(myClass_repr). But to be usable in a static array, that needs C _Generic or C++ constexpr, and of course something else in other languages. I’d still want the PEP 820 API as a fallback.)

The ABI is best I can come up with, long term (though it’s of course missing stuff we don’t need now but can add later).
The API is a basic wrapper plus a few convenience macros.

Thomas Wouters:

It would be much better if the deprecation warnings were only issued for uses of the new APIs, unless we’re really confident the only cases that would produce the deprecation warning are, in fact, problematic situations.

I couldn’t find much evidence of NULL slots being popular, but I agree this would make for a smoother transition where they are used. Let’s do it.

thomas · 2026-04-23T21:54:39.227Z

Thanks! With the change to omit the deprecation warnings for NULL slots, the SC has decided to accept the PEP. Congrats

encukou · 2026-04-29T10:11:02.093Z

Thank you for reviewing it!

I’ve marked the PEP as accepted, and sent a PR.

It would be much better if the deprecation warnings were only issued for uses of the new APIs, unless we’re really confident the only cases that would produce the deprecation warning are, in fact, problematic situations.

Probably well below SC-level resolution, but: “is this new API?” is ambiguous in case of nested “legacy” slots.
In my PR, the “outer-most” layer (or equivalently, the function you call/export), determine whether warnings are shown. So if you switch to PyModExport but keep the struct old format, you’ll get the warnings.
If this turns out to be a problem (in practice with the beta, or with the SC), I’d rather remove deprecation of repeated slots entirely. (Tracking which struct a slot occurred in isn’t worth it; I don’t want to base the warn-or-not decision only on the second occurrence: slot order mostly doesn’t matter, and I don’t want warnings showing up after you alphabetize a “set” definition.)