Skip to content

gh-75459: Doc: C API: Improve object life cycle documentation - #125962

Merged
encukou merged 29 commits into
python:mainfrom
rhansen:docs
May 20, 2025
Merged

encukou merged 29 commits into
python:mainfrom
rhansen:docs

Conversation

@rhansen

@rhansen rhansen commented Oct 25, 2024 •

Copy link
Copy Markdown
Contributor
  • Add "cyclic isolate" to the glossary.
  • Add a new "Object Life Cycle" page.
    • Illustrate the order of life cycle functions.
    • Document PyObject_CallFinalizer and PyObject_CallFinalizerFromDealloc.
  • PyObject_Init does not call tp_init.
  • PyObject_New:
    • also initializes the memory
    • does not call tp_alloc, tp_new, or tp_init
    • should not be used for GC-enabled objects
    • memory must be freed by PyObject_Free
  • PyObject_GC_New memory must be freed by PyObject_GC_Del.
  • Warn that garbage collector functions can be called from any thread.
  • tp_finalize and tp_clear:
    • Only called when there's a cyclic isolate.
    • Only one object in the cyclic isolate is finalized/cleared at a time.
    • Clearly warn that they might not be called.
    • They can optionally be manually called from tp_dealloc (via PyObject_CallFinalizerFromDealloc in the case of tp_finalize).
  • tp_finalize:
    • Reference object.__del__.
    • The finalizer can resurrect the object.
    • Suggest PyErr_GetRaisedException and PyErr_SetRaisedException instead of the deprecated PyErr_Fetch and PyErr_Restore functions.
    • Add links to PyErr_GetRaisedException and PyErr_SetRaisedException.
    • Suggest using PyErr_WriteUnraisable if an exception is raised during finalization.
    • Rename the example function from local_finalize to foo_finalize for consistency with the tp_dealloc documentation and as a hint that the name isn't special.
    • Minor wording and sylistic tweaks.
    • Warn that tp_finalize can be called during shutdown.

📚 Documentation preview 📚: https://cpython-previews--125962.org.readthedocs.build/

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation in the Doc dir skip news

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

7 participants