bpo-35568: add 'raise_signal' function#11335
Conversation
| @@ -0,0 +1 @@ | |||
| Expose :c:func:`raise(signum)` as `raise_signal` | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
: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
|
is there anything else that should be done for this PR? |
1st1
left a comment
There was a problem hiding this comment.
Looks good overall (and I'm +1 to add this new function), but please address the comments before merging.
| .. function:: raise_signal(signum) | ||
|
|
||
| Sends a signal to the executing process. Returns nothing. If a signal handler | ||
| is called, the *raise* function shall not return until after the signal handler does. |
There was a problem hiding this comment.
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.
| @@ -0,0 +1 @@ | |||
| Expose :c:func:`raise(signum)` as `raise_signal` | |||
There was a problem hiding this comment.
@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
left a comment
There was a problem hiding this comment.
Double backticks please:
``raise(signum)``
|
Thanks! |
As in title, expose C
raisefunction asraise_functioninsignalmodule. Also drop existingraise_signalin_testcapimodule and replace all usages with new function.https://bugs.python.org/issue35568