Why should we document something, just to tell people not to use it?

This field is exposed to the user who may use local PyTypeObject instances that are statically initialized (the LinuxCNC project implements that use case several places). If you do not initialize this field, then you get a warning missing initializer for member '_typeobject::tp_versions_used'.

Therefore, it should be documented (and it needs to be set to zero when statically initialized).

Sorry for the delay on the response. Please don't use a static PyTypeObject if you're running into this problem -- use a heap type (PyType_Spec) instead, which uses an array of slots rather than a struct.

Please don't use a static PyTypeObject if you're running into this problem [snip]

That is easily said, but you are too late. The static use case of PyTypeObject is already a fact and has been for a long time (like the past 19 years for LinuxCNC). I'm sure other projects also use it in a static fashion.

If you want to hide static use of PyTypeObject from the users, then you will have to go through a proper deprecation cycle. If you are not prepared to do that or there is no support for deprecation, then you should simply document every field in this structure.

BTW, the phrase "documenting the field" does not mean that you have to tell its inner secrets to all users.

The only "documenting" you must do is to acknowledge the field's existence, just like all other fields of the PyTypeObject, so all fields are listed together in the documentation. You may even tell the user that it is "for internal use only" and then be done with it. That is all.

I think this is probably the better approach, but instead of a deprecation with a planned removal, we should just soft deprecate static types.

Static use is documented and it specifically mentions PyTypeObject. Even though it contains a warning about 'static types must be compiled for a specific Python minor version', there is no mention that users should avoid it.

And with soft deprecation: from PEP378: A soft deprecation can be used when using an API which should no longer be used to write new code, but it remains safe to continue using it in existing code. The API remains documented and tested, but will not be developed further (no enhancement).

With soft deprecation, you a) cannot add a new field to this structure any more because of the "no enhancement" clause and b) you cannot use soft deprecation to "hide" a field and maintain compatibility because of the "remains documented" clause.

The simple solution is that you document this field.

Static use is documented and it specifically mentions PyTypeObject. Even though it contains a warning about 'static types must be compiled for a specific Python minor version', there is no mention that users should avoid it.

Yes, you're right that static types need to be discouraged more in the documentation. That's a planned thing to do, but nobody has gotten around to it yet. But, that page does contain several other downsides of static types.

With soft deprecation, you a) cannot add a new field to this structure any more because of the "no enhancement" clause and b) you cannot use soft deprecation to "hide" a field and maintain compatibility because of the "remains documented" clause.

I meant soft deprecating public use of PyTypeObject. We still want to change it, but we can soft deprecate doing things like passing static types to PyType_Ready.

The simple solution is that you document this field.

I'm trying to be reasonable, but I've explained several times now why I'm strongly against doing so. This is a private field that users shouldn't touch. If you want to avoid the warning, just add .tp_versions_used = 0 to your structure initialization -- C users will implicitly do that anyway (we can't just add a field that needs a non-zero default value without breaking things), so it's fine to do it in C++ too.

I have two alternative proposals that don't involve switching to heap types:

1. Document that PyTypeObject contains some internal fields that should be initialized to zero. That way, we don't have to document internal fields while still letting people know what to do.
2. Add a proper section (not just "do not use") on type versions and put that in the docs alongside tp_versions_used. (Basically, promote tp_versions_used to a public API.)

Otherwise, unless another core dev speaks up and is strongly +1 on documenting tp_versions_used in this way, this won't go any further.

I'm either +1 or -1 here because we have a precedent, that is tp_watched and tp_version_tag. Both are documented as "internal, do not use". However I fail to see how it could actually really help in initializing. How do you deal with those fields as they are only documented for internal use? I mean, all of them should 0 by default but I'm surprised that the compiler doesn't complain then. Since they are internal, we should maybe first indicate the default values they should take instead of saying that they are "internal" only, just so that users can initialize them. So yes, I would prefer that we document the default values and which ones are internals.

Yeah, I saw those fields. I think they were added during a time when there was much more emphasis on static types.

However I fail to see how it could actually really help in initializing.

It's only an issue when compiling with -Wmissing-field-initializers. But even then, it tells you exactly which fields you need to initialize, and the default values will have to be zero for any PyTypeObject field we add (because otherwise we'd break code).

I'd prefer we add a note that says PyTypeObject contains some internal fields, and that the user should just initialize them to zero.

I'd prefer we add a note that says PyTypeObject contains some internal fields, and that the user should just initialize them to zero.

I also prefer that. What's important is the default values to be known to users that are worried about it. Because if it's an internal field, nothing would forbid us to use another default value!