PyObject_CallFinalizerFromDealloc is undocumented

[pv]

BPO	31276
Nosy	@pv

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2017-08-25.14:26:48.286>
labels = ['3.7', 'docs']
title = 'PyObject_CallFinalizerFromDealloc is undocumented'
updated_at = <Date 2017-08-25.14:26:48.286>
user = 'https://github.com/pv'

bugs.python.org fields:

activity = <Date 2017-08-25.14:26:48.286>
actor = 'pv'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2017-08-25.14:26:48.286>
creator = 'pv'
dependencies = []
files = []
hgrepos = []
issue_num = 31276
keywords = []
message_count = 1.0
messages = ['300842']
nosy_count = 2.0
nosy_names = ['pv', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue31276'
versions = ['Python 3.7']

Linked PRs

• gh-75459: Doc: C API: Improve object life cycle documentation #125962
• [3.14] gh-75459: Doc: C API: Improve object life cycle documentation (GH-125962) #134344
• gh-75459: versionadded for PyObject_CallFinalizer*() API #143982
• [3.14] gh-75459: versionadded for PyObject_CallFinalizer*() API (GH-143982) #144026

[pv]

It's unclear if PyObject_CallFinalizerFromDealloc is a public function
or not. It is not documented, but it seems there's no other way to
ensure that tp_finalize runs, at least for objects without
Py_TPFLAGS_HAVE_GC.

In the documentation of tp_finalize (https://docs.python.org/3/c-api/typeobj.html?highlight=tp_finalize#c.PyTypeObject.tp_finalize)
there is the sentence:

"""It is called either from the garbage collector (if the instance is
part of an isolated reference cycle) or just before the object is
deallocated."""

However, it appears it is necessary to call it explicitly from any
user-provided tp_dealloc. Indeed, there are several calls to
PyObject_CallFinalizerFromDealloc in cpython/Modules/* e.g. in
posixmodule.c:ScandirIterator_dealloc