Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clearer wording of os.WNOHANG documentation to avoid misinterpretation #82983

Open
bbmmy mannequin opened this issue Nov 14, 2019 · 3 comments
Open

Clearer wording of os.WNOHANG documentation to avoid misinterpretation #82983

bbmmy mannequin opened this issue Nov 14, 2019 · 3 comments
Labels
3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes docs Documentation in the Doc dir stdlib Python modules in the Lib dir type-feature A feature request or enhancement

Comments

@bbmmy
Copy link
Mannequin

bbmmy mannequin commented Nov 14, 2019

BPO 38802
Nosy @iritkatriel

Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-11-14.21:52:21.080>
labels = ['3.7', '3.8', '3.9', 'type-feature', 'library', 'docs']
title = 'Clearer wording of os.WNOHANG documentation to avoid misinterpretation'
updated_at = <Date 2021-06-24.23:45:41.286>
user = 'https://bugs.python.org/bbmmy'

bugs.python.org fields:

activity = <Date 2021-06-24.23:45:41.286>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Library (Lib)']
creation = <Date 2019-11-14.21:52:21.080>
creator = 'bbmmy'
dependencies = []
files = []
hgrepos = []
issue_num = 38802
keywords = []
message_count = 3.0
messages = ['356627', '356628', '396517']
nosy_count = 3.0
nosy_names = ['docs@python', 'bbmmy', 'iritkatriel']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue38802'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9']
@bbmmy
Copy link
Mannequin Author

bbmmy mannequin commented Nov 14, 2019

For versions 2.7 through 3.9 of https://docs.python.org/3/library/os.html, os.WNOHANG is described as returning (0, 0) when no child process status is immediately available.

However, both os.wait3() and os.wait4() return 3-element tuples and are described as being similar to os.waitpid(). This, combined with the os.WNOHANG documentation being somewhat open to interpretation, makes it very easy to conclude (incorrectly) that wait3(WNOHANG) and wait4(WNOHANG) would return (0, 0) when no child process status is immediately available. In fact, they would return a 3-element tuple with the first 2 elements being 0.

I suggest rephrasing the os.WNOHANG documentation to the following (or something similar):

"The option for waitpid() to return immediately if no child process status is available immediately, in which case the function returns (0, 0). Correspondingly, wait3() and wait4() would return 3-element tuples with the first 2 elements being 0 and the last being a default-constructed resource usage information object."

Unfortunately that last part about the default-constructed resource usage information object is only true after this recent bug fix:
https://github.com/python/cpython/pull/15111/files

So I'll leave it to y'all to decide how to update the documentation since my proposed phrasing is dependent on that bug fix.

@bbmmy bbmmy mannequin added 3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes labels Nov 14, 2019
@bbmmy bbmmy mannequin assigned docspython Nov 14, 2019
@bbmmy bbmmy mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Nov 14, 2019
@bbmmy
Copy link
Mannequin Author

bbmmy mannequin commented Nov 14, 2019

If this documentation fix will not be backported (i.e. it will only apply to versions *after* the aforementioned bug fix) then a more precise way to phrase that last part would be:

"...with the first 2 elements being 0 and the last being an all-zero resource usage information object."

@iritkatriel
Copy link
Member

see also bpo-41825, bpo-34278, bpo-27808.

@iritkatriel iritkatriel added the stdlib Python modules in the Lib dir label Jun 24, 2021
@ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes docs Documentation in the Doc dir stdlib Python modules in the Lib dir type-feature A feature request or enhancement
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@iritkatriel