[issue20806] os.times document points to wrong section of non-Linux manual
New submission from Geoffrey Spear: The documentation for os.times directs the reader: "See the Unix manual page times(2) or the corresponding Windows Platform API documentation." However, the POSIX manual page in question is times(3P), and on OS X and BSD systems it's times(3). Falling back to "man times" without specifying a manual section also doesn't work, since this finds the bash builtin rather than the library function. ---------- assignee: docs@python components: Documentation messages: 212424 nosy: docs@python, geoffreyspear priority: normal severity: normal status: open title: os.times document points to wrong section of non-Linux manual versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20806> _______________________________________
R. David Murray added the comment: section 2 is the linux man page (system calls). On the other hand, on a freebsd 6.4 system I have access to, 'man times' does show the man 3 page. Since linux normally ships with the posix man pages as well, we should probably change the the section reference to 3p. I also notice that os/2 is mentioned in the python3 entry for os.times, but os/2 is no longer supported. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20806> _______________________________________
Change by Joannah Nanjekye <nanjekyejoannah@gmail.com>: ---------- keywords: +patch pull_requests: +15165 stage: -> patch review pull_request: https://github.com/python/cpython/pull/15479 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
Joannah Nanjekye <nanjekyejoannah@gmail.com> added the comment: I opened a PR for this. @david please review. ---------- nosy: +nanjekyejoannah stage: patch review -> _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment: Section 3p is OS specific (Debian and derivatives). `man 3 times` works as well. But the manpages-posix-dev is not installed by default, so changing this will add a regression on Linux. I thank that it would be better to add both references, times(2) and times(3). And we can also add a link to MSDN. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
Joannah Nanjekye <nanjekyejoannah@gmail.com> added the comment: Serhiy, This sounds good. I will update the PR. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
Eryk Sun <eryksun@gmail.com> added the comment: The function's doc string also needs to be updated to use the correct field names: "user", "system", "children_user", "children_system", and "elapsed".
And we can also add a link to MSDN.
os.times calls GetProcessTimes [1]. The user and kernel process times are incremented in clock ticks, i.e. in integer multiples of the system clock interrupt time. QueryUnbiasedInterruptTime [2] could thus be used for the value of `elapsed`. (Windows doesn't implement a process tree for the children_user and children_system values. It has jobs, which are similar to Linux control groups, but jobs aren't applicable here. POSIX doesn't have anything like Windows jobs or Linux cgroups.) [1] https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-proc... [2] https://docs.microsoft.com/en-us/windows/win32/api/realtimeapiset/nf-realtim... ---------- nosy: +eryksun _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
Joannah Nanjekye <nanjekyejoannah@gmail.com> added the comment: I updated the PR to reference times(2) and times(3) along with an MSDN link. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment: New changeset 3ccdbc33385a849c60a268def578cb06b8d41be6 by Serhiy Storchaka (Joannah Nanjekye) in branch 'master': bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479) https://github.com/python/cpython/commit/3ccdbc33385a849c60a268def578cb06b8d... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +15376 stage: -> patch review pull_request: https://github.com/python/cpython/pull/15722 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +15377 pull_request: https://github.com/python/cpython/pull/15723 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset cc51a6d7c7b6b06fb537860428347d88776d802b by Miss Islington (bot) in branch '3.8': bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479) https://github.com/python/cpython/commit/cc51a6d7c7b6b06fb537860428347d88776... ---------- nosy: +miss-islington _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset a6eac83c1804fd14ed076b1776ffeea8dcb9478a by Miss Islington (bot) in branch '3.7': bpo-20806: Reference both times(2) and times(3) and link to MSDN. (GH-15479) https://github.com/python/cpython/commit/a6eac83c1804fd14ed076b1776ffeea8dcb... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed versions: +Python 3.7, Python 3.8, Python 3.9 -Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20806> _______________________________________
participants (6)
-
Eryk Sun -
Geoffrey Spear
-
Joannah Nanjekye
-
miss-islington
-
R. David Murray
-
Serhiy Storchaka