gh-141070: Add PyUnstable_Object_Dump() function

[vstinner]

• Promote _PyObject_Dump() as a public function.
• Keep _PyObject_Dump() alias to PyUnstable_Object_Dump() for backward compatibility.
• Replace _PyObject_Dump() with PyUnstable_Object_Dump().

• Issue: [C API] Promote _PyObject_Dump() to a public function #141070

---

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

[vstinner]

cc @ZeroIntensity @picnixz

[ZeroIntensity]

The tests seem to be failing on Windows.

[vstinner]

The tests seem to be failing on Windows.

object address : 0000017EAEAFA4D0

Ah yes, printf("%p", ptr) doesn't print 0x prefix on Windows.

[ZeroIntensity]

LGTM with a few English nitpicks on the docs.

[encukou]

I think this is a great candidate for unstable API.

[vstinner]

I created a C API Working Group decision issue.

[ZeroIntensity]

Hm, @encukou, why make this an unstable API? I don't think we ever plan to remove the ability to print objects from the C API. If you're concerned about people relying on the exact output, we can just tell them "don't do that" in the docs.

[encukou]

I don't think we ever plan to remove the ability to print objects from the C API.

That we don't, but _PyObject_Dump is about dumping object internals to a fixed stream. AFAICS, it's strictly a debugging tool.

Or is there a use case where you call this from a releasable extension?

[ZeroIntensity]

Or is there a use case where you call this from a releasable extension?

Absolutely, we do it ourselves. It's a convenient debugging tool, but it's also quite handy as a last-ditch effort to display something to the user, like with PyErr_Display.

I think as long as we specify the function as "dump non-specific debugging information about an object", it should be fine to add it as a non-unstable API. If we do add it to PyUnstable, I'd be strongly -1 on any proposal to remove it, which I feel kind of defeats the point of the unstable API in the first place.

[vstinner]

Entries should be sorted.

[encukou]

I didn't know that. What's the sort key?

[vstinner]

"Sorted alphabetically". @hugovk added comments like that in the What's New document:

.. Add C API deprecations above alphabetically, not here at the end.

We should add a similar comment for C API "New features". I think that it was @AA-Turner who started to sort items in What's New In Python 3.14.

[vstinner]

I renamed the function to PyUnstable_Object_Dump().

[encukou]

Absolutely, we do it ourselves.

That's debugging helper. Unstable API is great for those :)

If we do add it to PyUnstable, I'd be strongly -1 on any proposal to remove it, which I feel kind of defeats the point of the unstable API in the first place.

There's a bunch of unstable API like that -- I think some people would be sad to PyUnstable_Code_GetExtra go, for example.

[vstinner]

@ZeroIntensity: I prefer the PyUnstable prefix since the function behavior is not well defined. It can change between Python versions, especially the output, even if it has not changed frequently. Also, this function should only be used for debugging purpose. Well, I proposed PyUnstable_Object_Dump() name to the C API Working Group and it's been accepted (4/5 votes so far).

[serhiy-storchaka]

Maybe add a special case for op == NULL?

And for type == NULL?

[vstinner]

It displays freed in both cases. There is now an unit test for that.

How do you suggest to format op==NULL and/or type==NULL?

[serhiy-storchaka]

If this is already tested, then good. I was not sure that _PyObject_IsFreed() works with NULL (it could crash).

If type==NULL (very unlikely), then type->tp_name and repr() will crash. They will also crash if type was freed or if it is just a garbage. We could skip prints in that case avoid crash, although it may be too late.

Looking at the code, it seems the ideas I had (testing against the patterns used to fill the freed memory) was already implemented in _PyMem_IsPtrFreed().

[vstinner]

If type==NULL (very unlikely), then type->tp_name and repr() will crash

_PyObject_IsFreed() checks _PyMem_IsPtrFreed(Py_TYPE(op)). We just display freed in this case, without displaying tp_name or trying to call repr().

[ZeroIntensity]

There's a bunch of unstable API like that -- I think some people would be sad to PyUnstable_Code_GetExtra go, for example.

What's the point of an unstable API that we can't remove?