Recently, @vstinner proposed to promote the internal _PyObject_Dump function to a public API, per my request.
The C API WG approved the public API as PyUnstable_Object_Dump, which I found to be a bit unfortunate. When debugging, I’ve found it really helpful to call _PyObject_Dump to quickly show information about an object, but PyUnstable_Object_Dump is much harder to type, which hurts that use case. I raised my concerns on the original issue: https://github.com/python/cpython/issues/141070
To summarize the discussion there, I think the workgroup’s decision to make this unstable was based on the idea that _PyObject_Dump isn’t meant for actual use in an extension, but I don’t think that’s entirely true. Apart from debugging, it’s a handy API for displaying debug information about an object before the program crashes (we do this internally with things like _PyObject_ASSERT). Additionally, _PyObject_Dump doesn’t expose any implementation details that aren’t already part of the limited API, so I doubt the ability to remove it someday will be helpful in practice.
My initial hope was that this would be named PyObject_Dump, but @encukou also suggested Py_Dump if we’re targeting the GDB use case. If anyone is strongly in favor of keeping this unstable, I’d be okay with this existing as PyUnstable_Dump, since that’s a lot easier to type than PyUnstable_Object_Dump.
What do others think? Should this be an unstable API?
I think it’s an API where we can promise not to change or remove the API itself (PyObject_Dump(PyObject *) is pretty safe), without promising that the output will be in any way usable or reliable except when read by a human (or possibly an AI). That way, we can change the output it prints whenever we need.
I don’t like Py[Unstable]_Dump, because it takes a PyObject * and doesn’t necessary work on our other types (not many right now, and it’s pretty obvious that it won’t work on e.g. Py_member_def when you think about it, but if we have PyObject in the API name then you don’t even have to think about it).
I see here a call for short name for CLI debugging (and without custom aliases for the CLI debugger). I’d like to get a feel for how important that use case is in general.
It’s the same as Py_IncRef or Py_TYPE in that respect. I don’t think “omitting the default” hurts here.
And there is a valid-looking reason for brevity.
Not quite, those names imply that the argument has a reference count, or has a type (and in fact, provided they do have those fields at the same place as PyObject, the macros will work, due to horrendous type casting that it would be better if we didn’t do it, but that’s where they’re at).
“Dump” implies nothing about the argument, so I have no way to infer that it should be an object. And plenty of other Py_* APIs don’t take PyObject, so it’s not like there’s anything obvious.
Personally, I think PyObject_Dump is good enough for debugging. I agree that Py_Dump would be even easier to use, but I also agree that there are some downsides to that name.