Document ob_refcnt, ob_type, ob_size

[encukou]

The fields of PyObject and PyVarObject are only documented in static type object docs. They should have entries under their own types.

(Their use is discouraged. That makes proper docs all the more important.)

Linked PRs

• gh-135913: Document ob_refcnt, ob_type, ob_size #135914
• [3.14] gh-135913: Document ob_refcnt, ob_type, ob_size (GH-135914) #136377

[markshannon]

Should the docs just say: "Don't use these fields"?

I think their use should be "forbidden", rather than "discouraged". I can't think of a correct way to use them directly.

[encukou]

Here's one use: https://github.com/numpy/numpy/blob/6eeaae25ddfacf586ee02ddc600618127fa79cfd/numpy/_core/include/numpy/ndarrayobject.h#L35

Yes, we don't want people to do that. But suddenly adding “that's forbidden” to docs isn't a deprecation strategy. Per PEP 387, these need to keep working as they have in the past.