[issue31065] Documentation for Popen.poll is unclear
New submission from Mark Dickinson: 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. ---------- assignee: docs@python components: Documentation messages: 299378 nosy: docs@python, mark.dickinson priority: normal severity: normal status: open title: Documentation for Popen.poll is unclear versions: Python 2.7, Python 3.6, Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
Changes by Mark Dickinson <dickinsm@gmail.com>: ---------- keywords: +easy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
R. David Murray added the comment: 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 :) ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
Mark Dickinson added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
Mark Dickinson added the comment:
I don't there's
I don't *think* there's ... Stupid fingers. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
R. David Murray added the comment: Agreed. Explicit is good. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
Changes by Ivan Chernov <chernoffivan@gmail.com>: ---------- pull_requests: +3205 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
Ivan Chernov added the comment: Try to solve this issue, because it's pretty simple (: ---------- nosy: +vanadium23 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
Elena Oat added the comment: I've added a sentence saying about the explicit return value. ---------- keywords: +patch nosy: +Elena.Oat Added file: http://bugs.python.org/file47102/issue31065.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
Changes by Elena Oat <oat.elena@gmail.com>: ---------- pull_requests: +3258 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
Changes by Elena Oat <oat.elena@gmail.com>: ---------- pull_requests: -3258 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
Gregory P. Smith added the comment: 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/006617ff7d6df3fdedcfe53e94ee2c52cc7... ---------- nosy: +gregory.p.smith _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue31065> _______________________________________
Change by Berker Peksag <berker.peksag@gmail.com>: ---------- pull_requests: +4130 stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue31065> _______________________________________
Berker Peksag <berker.peksag@gmail.com> added the comment: 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/0f1973d06e2116deafb19bbb9443b138187... ---------- nosy: +berker.peksag _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue31065> _______________________________________
Berker Peksag <berker.peksag@gmail.com> added the comment: I've backported 006617ff7d6df3fdedcfe53e94ee2c52cc796437 to 3.6. I think this can be closed now, thank you! ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed type: -> enhancement versions: -Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue31065> _______________________________________
participants (6)
-
Berker Peksag -
Elena Oat
-
Gregory P. Smith
-
Ivan Chernov
-
Mark Dickinson
-
R. David Murray