gh-145559: Add PyUnstable_DumpTraceback() and PyUnstable_DumpTracebackThreads()

[alexmalyshev]

These functions stopped being exported in #107215. However, they are the only way to print a Python stacktrace safely from a signal handler, making them very useful for extensions. Re-export them.

• Issue: Expose signal-safe way to print stacktraces #145559

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[vstinner]

Rather than exporting internal C API functions, I would prefer to promote them as public or PyUnstable functions.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[alexmalyshev]

Made them PyUnsafe_ functions. I believe that the mentions to them in the configure and emscripten files can just be deleted now that they'll be public.

[sergey-miryanov]

I believe they should have PyUnstable_ prefix, not PyUnsafe_.

[alexmalyshev]

I believe they should have PyUnstable_ prefix, not PyUnsafe_.

Ack I always make this mistake...

[sergey-miryanov]

Please, try to avoid force-push.

[freakboy3742]

!buildbot emscripten

[bedevere-bot]

🤖 New build scheduled with the buildbot fleet by @freakboy3742 for commit 538a1cd 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F145560%2Fmerge

The command will test the builders whose names match following regular expression: emscripten

The builders matched are:

• WASM Emscripten PR

[ZeroIntensity]

Note that PyUnstable_DumpTracebackThreads does not work well on the free-threaded build, because other threads may exit and delete their PyThreadState *. I think it's worth adding a warning for that. Here's an example:

.. warning::
    On the :term:`free-threaded build`, this function is not thread-safe. If
    another thread deletes its :term:`thread state` while this function is being
    called, the process will likely crash.

[ZeroIntensity]

Please also add an entry to the changelog and "What's New in Python 3.15".

For the changelog, you can use blurb_it.
For the "What's New in Python 3.15" page, please add a note under the "C API changes" section (here).

[ZeroIntensity]

One little issue with the blurb entry, but otherwise this looks good.

[vstinner]

LGTM.

It's unusual that PyUnstable_DumpTracebackThreads() returns an error message on error rather than raising an exception, but it's explained by the fact that the function can be called without an attached thread thread.

[vstinner]

I created capi-workgroup/decisions#101 to get the API reviewed by the C API Working Group.

[vstinner]

Hum, I suggest to remove "It will also write this error message to fd." sentence. I'm not sure that it is always a good idea to write the error message to fd.

[alexmalyshev]

I thought that was what the C API discussion was about, writing the string result over to the file (when it's non-NULL). Did I misunderstand?

[encukou]

The function is supposed to dump debug information to fd. It can safely dump this message there, to simplify debugging.

[vstinner]

PyUnstable_DumpTraceback() should either write the error message to fd and return NULL, or not write into fd and return an error message. Doing both sounds redundant to me.

Currently, _Py_DumpTracebackThreads() returns an error message when it knows that it will not be able to output anything useful since it lacks an important data to do its work. For example, it returns an error message if it fails to get the current thread state.

[alexmalyshev]

or not write into fd and return an error message.

I think this is simpler, updated the doc for PyUnstable_DumpTraceback().

Do we still want to do the extra debug logging for PyUnstable_DumpTracebackThreads() then, or shall we update that to also only return the const char*?