[Python-Dev] Documenting the private C API (was Re: Questions about signal handling.)

[Barry Warsaw]

On Sep 25, 2018, at 03:44, Victor Stinner <vstinner at redhat.com> wrote:

> By the way, recently, we had to fix yet another bug in signal
> handling. A new function has been added:
> 
> void
> _PyEval_SignalReceived(void)
> {
>    /* bpo-30703: Function called when the C signal handler of Python gets a
>       signal. We cannot queue a callback using Py_AddPendingCall() since
>       that function is not async-signal-safe. */
>    SIGNAL_PENDING_CALLS();
> }

Is anybody else concerned about the proliferation of undocumented private C API functions?  I’m fine with adding leading underscore functions and macros when it makes sense, but what concerns me is that they don’t appear in the Python C API documentation (AFAICT).  That means they are undiscoverable, and their existence and utility is buried in institutional knowledge and obscure places within the C code.  And yet, the interpreter relies heavily on them.

Maybe this is better off discussed in doc-sig but I think we need to consider documenting the private C API.

-Barry

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: Message signed with OpenPGP
URL: <http://mail.python.org/pipermail/python-dev/attachments/20180925/23a604b5/attachment.sig>