The "trick" wouldn't be too useful though as this API can't block and the signal flag needs to be processed on the main thread. So I guess documentation it is.

The way I think of this is that the signal.pthread_sigmask API is pretty low level. After that API is called, no more signals will _reach the process_, but the interpreter may process some that happened beforehand. So installing a handler is indeed appropriate.

Also, it is entirely possible for C extension modules or code embedding Python to call pthread_sigmask in its own threads outside of the Python runtimes knowledge. So we us tracking what signals are blocked on our own may not be accurate.  We could instead change the eval loop signal processing code to call `pthread_sigmask(SIG_UNBLOCK, NULL /* set */, &oldset);` to retrieve the processes current mask to decide if the flagged signals should be processed by Python or not.

BUT... I can imagine complex race cases where that'd surprise people who are chaining multiple signal handlers such as one from outside of Python that saved the Python handler and calls it afterwards.  Their C/process-level handler would be called, would chain to Python's "record that signal X happened and set the bit" handler, but Python wouldn't then be guaranteed to call the Python handler code if the sigmask changed before the eval loop did its pending signal check.

So I'm still inclined to keep this simple and stick with just documenting best practices for now.  An implementation of masking from the python eval handler may need to be something conditionally controllable for differing application situations if added.