[docs] [issue31276] PyObject_CallFinalizerFromDealloc is undocumented

[Pauli Virtanen]

New submission from Pauli Virtanen:

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

----------
assignee: docs at python
components: Documentation
messages: 300842
nosy: docs at python, pv
priority: normal
severity: normal
status: open
title: PyObject_CallFinalizerFromDealloc is undocumented
versions: Python 3.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue31276>
_______________________________________