Improve clarity of signal.siginterrupt docs

[a4eb36e5-6759-47bf-8e24-1aa4d349c6ed]

BPO	25559
Nosy	@vstinner, @bitdancer

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2015-11-05.16:54:37.756>
labels = ['type-feature', 'docs']
title = 'signal.siginterrupt description has typo'
updated_at = <Date 2015-11-05.20:30:22.448>
user = 'https://bugs.python.org/TomMeagher'

bugs.python.org fields:

activity = <Date 2015-11-05.20:30:22.448>
actor = 'vstinner'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2015-11-05.16:54:37.756>
creator = 'Tom Meagher'
dependencies = []
files = []
hgrepos = []
issue_num = 25559
keywords = []
message_count = 3.0
messages = ['254121', '254132', '254140']
nosy_count = 4.0
nosy_names = ['vstinner', 'r.david.murray', 'docs@python', 'Tom Meagher']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue25559'
versions = []

[a4eb36e5-6759-47bf-8e24-1aa4d349c6ed]

"if flag is False, system calls will be restarted when interrupted by signal signalnum, otherwise system calls will be interrupted."

This sentence doesn't make any sense as written. I assume there should be a "not" in there somewhere, but I'm unclear if signal calls are not interrupted when the flag is false, or not interrupted when they are true.

[bitdancer]

The first phase says "restarted when interrupted", the second phrase says "interrupted". So the difference is whether the system call is restarted or left in interrupted state (ie: the signal will propagate, which is confirmed by the second paragraph). I can't see a way to phrase it any more clearly, can you?

[vstinner]

For more information on how Python handles signals, you can also read the PEP-475 (which changed how Python 3.5 handles signals ;-))