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

Antoine Pitrou solipsis at pitrou.net
Tue Sep 25 10🔞07 EDT 2018

On Tue, 25 Sep 2018 10:01:56 -0400 Barry Warsaw <barry at python.org> wrote:

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 > PyEvalSignalReceived(void) > { > /* bpo-30703: Function called when the C signal handler of Python gets a > signal. We cannot queue a callback using PyAddPendingCall() since > that function is not async-signal-safe. */ > SIGNALPENDINGCALLS(); > } 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).

Not really. Many are just like "static" (i.e. module-private) functions, except that they need to be shared by two or three different C modules. It's definitely the case for _PyEval_SignalReceived().

Putting them in the C API documentation risks making the docs harder to browse through for third-party users. I think it's enough if there's a comment in the .h file explaining the given function.

Regards

Antoine.

More information about the Python-Dev mailing list