Documentation about PyTypeObject being part of the Stable ABI

[ov2k]

https://docs.python.org/3/c-api/typeobj.html#static-types says:

Also, since PyTypeObject is not part of the stable ABI, any extension modules using static types must be compiled for a specific Python minor version.

https://docs.python.org/3/c-api/type.html#c.PyTypeObject says:

Part of the Stable ABI.

I'm not sure what needs to be fixed, but something does. Can extension modules using the Stable ABI use static types now?

[erlend-aasland]

The former quote should probably read Limited API, not Stable ABI. cc. @encukou

[kumaraditya303]

Technically PyTypeObject is part of the stable ABI as an opaque struct (whose fields are part of the ABI) because stable ABI uses Limited C API. Maybe it's better to just document it as "part of Limited C API as an opaque struct".

[encukou]

This is fixed in https://docs.python.org/3.11/c-api/type.html#c.PyTypeObject
But it would make sense to backport to earlier docs.

[encukou]

PR is at #95711

[ov2k]

I think https://docs.python.org/3/c-api/typeobj.html#static-types still needs to be fixed. https://docs.python.org/3/c-api/stable.html says:

Extensions that only use the Limited API can be compiled once and work with multiple versions of Python.

It's not that PyTypeObject isn't part of the Stable ABI, but that its members aren't part of the Limited API.

[encukou]

It's both.
In the limited API/stable ABI, PyTypeObject is opaque (and has been since the beginning). The ABI for an opaque struct is just a pointer, so there's nothing specific to PyTypeObject in the Stable ABI.

(The first part of PyTypeObject happens to be stable across releases, but that's because it's needed for declarations without designated initializers using the regular C- API.)

[erlend-aasland]

Suggesting to close this as fixed.

[encukou]

@ov2k, please feel free to comment if you disagree, have other suggestions, or if something is unclear.
(Not sure if you have permission to reopen – if you do, that's also an option.)

[ov2k]

That's exactly my point, but perhaps I wasn't being clear enough. https://docs.python.org/3/c-api/typeobj.html#static-types makes no reference to PyTypeObject being opaque, which is the real reason why extension modules using static types must be compiled for a specific Python minor version. It should say something like:

Also, since PyTypeObject is only part of the Limited API as an opaque struct...

[encukou]

It makes sense to me, but I've been thinking about API/ABI way too much :)
Could you send a PR to make this clearer? If not I'll get to it eventually.