Title: Documentation for Popen.poll is unclear
Type: Stage:
Components: Documentation Versions: Python 3.7, Python 3.6, Python 2.7
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, mark.dickinson, r.david.murray
Priority: normal Keywords: easy

Created on 2017-07-28 10:30 by mark.dickinson, last changed 2017-07-28 16:48 by r.david.murray.

Messages (5)
msg299378 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2017-07-28 10:30
The documentation for Popen.poll says:

> Check if child process has terminated. Set and return returncode attribute.

This requires the reader to guess that if the child process has not terminated, the call returns immediately, with a return value of ``None``. It would be good to be explicit about this.
msg299387 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-07-28 13:48
Yes we can add "otherwise return None".  However it is pretty clear as is, since "poll" implies an immediate return, and if there's no return code to return, the logical value in Python to get back is None :)
msg299397 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2017-07-28 15:30
Right, after following the source, I realise that `poll` is indeed returning `self.returncode` in all cases, and if the process hasn't terminated yet then `self.returncode` is still at its initial value of `None`.

I can think of other ways that the result could potentially be indicated, though: when I poll, I'm asking whether the child process is still running or not, so a boolean result wouldn't be unreasonable. Or perhaps an exception (like doing `get(block=False)` on a queue does). I don't there's a good reason not to be explicit here.
msg299398 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2017-07-28 15:31
> I don't there's

I don't *think* there's ...

Stupid fingers.
msg299408 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-07-28 16:48
Agreed.  Explicit is good.
Date User Action Args
2017-07-28 16:48:54r.david.murraysetmessages: + msg299408
2017-07-28 15:31:22mark.dickinsonsetmessages: + msg299398
2017-07-28 15:30:51mark.dickinsonsetmessages: + msg299397
2017-07-28 13:48:31r.david.murraysetnosy: + r.david.murray
messages: + msg299387
2017-07-28 10:31:17mark.dickinsonsetkeywords: + easy
2017-07-28 10:30:57mark.dickinsoncreate