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

Created on 2017-07-28 10:30 by mark.dickinson, last changed 2017-08-29 14:46 by gregory.p.smith.

Files
File name Uploaded Description Edit
issue31065.diff Elena.Oat, 2017-08-26 08:56
Pull Requests
URL Status Linked Edit
PR 3169 merged vanadium23, 2017-08-21 16:44
Messages (8)
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.
msg300642 - (view) Author: Ivan Chernov (vanadium23) * Date: 2017-08-21 16:45
Try to solve this issue, because it's pretty simple (:
msg300864 - (view) Author: Elena Oat (Elena.Oat) * Date: 2017-08-26 08:56
I've added a sentence saying about the explicit return value.
msg300991 - (view) Author: Gregory P. Smith (gregory.p.smith) * (Python committer) Date: 2017-08-29 14:46
New changeset 006617ff7d6df3fdedcfe53e94ee2c52cc796437 by Gregory P. Smith (Ivan Chernoff) in branch 'master':
bpo-31065: Add doc about Popen.poll returning None. (#3169)
https://github.com/python/cpython/commit/006617ff7d6df3fdedcfe53e94ee2c52cc796437
History
Date User Action Args
2017-08-29 14:46:26gregory.p.smithsetnosy: + gregory.p.smith
messages: + msg300991
2017-08-27 11:27:33Elena.Oatsetpull_requests: - pull_request3258
2017-08-27 11:25:45Elena.Oatsetpull_requests: + pull_request3258
2017-08-26 08:56:21Elena.Oatsetfiles: + issue31065.diff

nosy: + Elena.Oat
messages: + msg300864

keywords: + patch
2017-08-21 16:45:27vanadium23setnosy: + vanadium23
messages: + msg300642
2017-08-21 16:44:10vanadium23setpull_requests: + pull_request3205
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