classification
Title: Documentation for Popen.poll is unclear
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Elena.Oat, berker.peksag, 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-10-29 04:07 by berker.peksag. This issue is now closed.

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
PR 4161 merged berker.peksag, 2017-10-29 04:00
Messages (10)
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
msg305175 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2017-10-29 04:06
New changeset 0f1973d06e2116deafb19bbb9443b138187803c7 by Berker Peksag in branch '3.6':
bpo-31065: Add doc about Popen.poll returning None. (GH-3169)
https://github.com/python/cpython/commit/0f1973d06e2116deafb19bbb9443b138187803c7
msg305176 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2017-10-29 04:07
I've backported 006617ff7d6df3fdedcfe53e94ee2c52cc796437  to 3.6. I think this can be closed now, thank you!
History
Date User Action Args
2017-10-29 04:07:46berker.peksagsetstatus: open -> closed
versions: - Python 2.7
type: enhancement
messages: + msg305176

resolution: fixed
stage: patch review -> resolved
2017-10-29 04:06:51berker.peksagsetnosy: + berker.peksag
messages: + msg305175
2017-10-29 04:00:17berker.peksagsetstage: patch review
pull_requests: + pull_request4130
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