bpo-35568: add 'raise_signal' function

[vladima]

As in title, expose C raise function as raise_function in signal module. Also drop existing raise_signal in _testcapi module and replace all usages with new function.

https://bugs.python.org/issue35568

[zooba]

Someone may know better, but I'm pretty sure the :c:func: directive is only for our own C functions, which means this will end up being a broken link.

[vladima]

I've used this comment where :c:func: was used for GetFinalPathNameByHandle as an example. If this is not correct - I'd be happy to fix it.

[1st1]

@zooba's right, :c:func: is used for CPython C API functions. It's a bug if it is used for Posix/etc functions in other places.

[vladima]

Should it then be just a :func:? It is a bit confusing, Documenting Python doc only mentions c:func as :

c:func
The name of a C-language function. Should include trailing parentheses.

without diving into specific details whether it should be any C function or function from C API. Also I can see a number places in existing docs where externally defined functions are referenced via c:func:, i.e.

*datetime.rst*

if the timestamp is out
   of the range of values supported by the platform C :c:func:`localtime` function

*asyncio-subprocess.rst*

On Windows the Win32 API function :c:func:`TerminateProcess` is
   called to stop the child process.

*asyncore.rst*

If your operating system supports the :c:func:`select` system call in its I/O
library (and nearly all do),

*ctypes.rst*

I will present an example here which uses the standard C library's
:c:func:`qsort` function

[asvetlov]

:c:func:qsort creates a link to .. c:function:: qsort block.
If the block is absent no link is created but :c:func:qsort is pointless in this case.
Since CPython documentation has no definition for .. c:function:: qsort the cross-reference should be removed, consider it as a hurtless bug.

The same is for raise. Double backticks should work fine

[vladima]

is there anything else that should be done for this PR?

[1st1]

Looks good overall (and I'm +1 to add this new function), but please address the comments before merging.

[1st1]

Sends a signal to the executing process.

IMO "to the calling process" reads better.

If a signal handler
is called, the raise function shall not return until after the signal handler does.

While this is true for the C raise function, it's not for Python. In Python, signals are queued and their handlers are executed at some undetermined point later. I suggest removing this sentence.

[1st1]

@zooba's right, :c:func: is used for CPython C API functions. It's a bug if it is used for Posix/etc functions in other places.

[asvetlov]

Double backticks please:

``raise(signum)``

[asvetlov]

Thanks!