pymethods: add support for __del__

[messense]

Adds support for __del__ in #[pymethods], mapped to CPython's tp_finalize slot.

#[pymethods]
impl MyClass {
    fn __del__(&mut self) {
        println!("instance is being destroyed");
    }
}

Why a custom impl_del_slot instead of SlotDef?

The generic SlotDef machinery assumes the trampoline module name and the FFI type name are the same (e.g., inquiry for Py_tp_clear). For tp_finalize, the FFI type is destructor (void-returning) but the trampoline needs to be finalizefunc — they don't match. A custom impl_del_slot (following the same pattern as impl_clear_slot) avoids complicating the generic machinery for a single special case.

Alternative considered: Adding a separate ffi_type field to SlotDef to decouple the trampoline name from the cast type. Rejected because it would add complexity to the generic path that only __del__ would use.

Why a dedicated trampoline instead of trampoline_unraisable?

CPython's slot_tp_finalize saves the active exception before calling __del__ and restores it afterwards, since finalizers can run at arbitrary points during execution. We need the same save/restore semantics, but crucially, the restore must happen even if __del__ panics. If we used trampoline_unraisable (which wraps the entire body in catch_unwind), a panic would unwind past the restore, silently swallowing the active exception. The dedicated trampoline puts catch_unwind around only the user's __del__ call, so the exception restore always runs.

Alternative considered: Nesting the error handling inside trampoline_unraisable's body — save exception, call __del__, write_unraisable on error, restore exception, return Ok(()). This was the initial implementation but was replaced because a panic in __del__ would skip the restore, leaking the saved exception PyObject* pointers and losing the active exception state.

Why call PyObject_CallFinalizerFromDealloc from tp_dealloc?

PyO3 replaces CPython's subtype_dealloc with its own tp_dealloc, so tp_finalize would never be called during normal deallocation without explicit invocation. The GC track/untrack dance in tp_dealloc_with_gc (untrack → re-track → finalize → untrack) mirrors CPython's subtype_dealloc to correctly handle object resurrection and GC visibility during finalization.

Alternative considered: Hooking into subtype_dealloc or using tp_del (the deprecated pre-PEP 442 slot). Rejected because PyO3 already owns the tp_dealloc slot, so calling PyObject_CallFinalizerFromDealloc directly is the most straightforward approach, and tp_del is deprecated since Python 3.4.

abi3 limitation

PyObject_CallFinalizerFromDealloc is not in the stable ABI, so on abi3 builds __del__ won't fire during normal refcount-based deallocation. The Py_tp_finalize slot is still set, so __del__ is invoked by the cyclic garbage collector for GC-tracked types and can be called explicitly via Python code. This is documented in the guide.

Alternative considered: Manually inlining the logic of PyObject_CallFinalizerFromDealloc (temporarily resurrect the object, call tp_finalize, check refcount) using only stable-ABI functions. Rejected because it would duplicate subtle CPython internals and could diverge across Python versions.

Closes #2479

[davidhewitt]

Thanks! Please also add a CHANGELOG and add to protocols.md in the guide.

Note that also on Python 3.7 we need to set Py_TPFLAGS_HAVE_FINALIZE, it's ignored on newer versions.

[davidhewitt]

I found today that if we don't implement tp_dealloc then the default tp_dealloc implementation (at least for CPython) will call tp_finalize. This gives us a potential route to support this and also fix #3064 at the same time.

However the documentation in this area is confusing, as it implies that tp_dealloc doesn't have a default - python/cpython#105018 / https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_dealloc

I think it may be possible that we use that default implementation to support this case, but we'll need to test carefully whether this also works for all Python versions, PyPy etc.

[davidhewitt]

I spoke to vstinner (thought no need to ping so no @) briefly about this, I understood that PyObject_CallFinalizerFromDealloc could be added to the limited API in 3.13. So maybe we can figure out a way to proceed with this where __del__ is supported without abi3 for now and then we can add abi3 support on 3.13.

[codspeed-hq]

Merging this PR will not alter performance

✅ 105 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing messense:del (9cd1578) with main (d07a1ab)}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

[messense]

With the help from LLM, made some progress on this, tests are passing, review would be appreciated!

I have also looked into removing our tp_dealloc implementation but turns out to be pretty hard to get everything right.