gh-75459: Doc: C API: Improve object life cycle documentation (GH-125962)
* Add "cyclic isolate" to the glossary.
* Add a new "Object Life Cycle" page.
* Improve docs for related API, with special focus on cross-references and warnings
(cherry picked from commit 3246ea514d)
Co-authored-by: Richard Hansen <rhansen@rhansen.org>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Docs of the other `PyType_From*` functions link to `PyType_FromMetaclass`,
which noted that they differ for backwards compatibility reasons.
The note is no longer relevant in 3.14.
The other functions have `versionchanged` blurbs.
* Update documentation for tp_basicsize & tp_itemsize
- Add alignment requirement
- Mention that ob_size is unreliable if you don't control it
- Add some links for context
- basicsize should include the base type in generaly not just PyObject
This adds a “by-the-way” link to `PyObject_New`, which shouldn't be
used for GC types. In order to be comfortable linking to it, I also
add a link to `PyObject_GC_New` from its docs. And the same for
`*Var` variants, while I'm here.
* Strongly suggest Py_SIZE & Py_SET_SIZE
* gh-110803: Reorganize docs for what PyType_Slot doesn't cover
- Cover the offset fields first
- Mention the old alternative for MANAGED flags, which is needed
to support older Pythons
- De-emphasize the internal flags: use an inline list.
- Add a note to PyMemberDef saying what to do with it
* Remove an older draft...
* Uncomment object removal in pairindextypes
* Use new-style index directive ('object') - C API
* Use new-style index directive ('object') - Library
* Use new-style index directive ('object') - Reference
* Use new-style index directive ('object') - Tutorial
This checks the bases of of a type created using the FromSpec
API to inherit the bases metaclasses. The metaclass's alloc
function will be called as is done in `tp_new` for classes
created in Python.
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
Added a new stable API function ``PyType_FromMetaclass``, which mirrors
the behavior of ``PyType_FromModuleAndSpec`` except that it takes an
additional metaclass argument. This is, e.g., useful for language
binding tools that need to store additional information in the type
object.
I think that none of these API calls can fail, but only few of them are
documented as such. Add the sentence "This function always succeeds" (which is
the same already used e.g. by PyNumber_Check) to all of them.
* There were leaks if Py_tp_bases is used more than once or if some call is
failed before setting tp_bases.
* There was a crash if the bases argument or the Py_tp_bases slot is not a tuple.
* The documentation was not accurate.
