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

[Victor Stinner]

Nobody should use _PyEval_SignalReceived(). It should only be used the
the C signal handler.

But if we have a separated documented for CPython internals, why not
documenting private functions. At least, I would prefer to not put it
at the same place an the *public* C API. (At least, a different
directory.)

Victor
Le mar. 25 sept. 2018 à 16:05, Barry Warsaw <barry at python.org> a écrit :
>
> 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
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: https://mail.python.org/mailman/options/python-dev/vstinner%40redhat.com