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.

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

os.waitid() documentation needs TLC #85991

Closed
birkenfeld opened this issue Sep 21, 2020 · 4 comments · Fixed by #22356
Closed

os.waitid() documentation needs TLC #85991

birkenfeld opened this issue Sep 21, 2020 · 4 comments · Fixed by #22356
Labels
3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir easy stdlib Python modules in the Lib dir type-feature A feature request or enhancement

Comments

@birkenfeld
Copy link
Member

BPO 41825
Nosy @birkenfeld, @iritkatriel
PRs
  • bpo-41825: restructure docs for the os.wait*() family #22356
    		•

    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 2020-09-21.16:41:50.762>
labels = ['easy', '3.9', '3.10', '3.11', 'type-feature', 'library', 'docs']
title = 'os.waitid() documentation needs TLC'
updated_at = <Date 2021-06-24.23:44:30.315>
user = 'https://github.com/birkenfeld'

    bugs.python.org fields:

    activity = <Date 2021-06-24.23:44:30.315>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Library (Lib)']
creation = <Date 2020-09-21.16:41:50.762>
creator = 'georg.brandl'
dependencies = []
files = []
hgrepos = []
issue_num = 41825
keywords = ['patch', 'easy']
message_count = 2.0
messages = ['377263', '396516']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'docs@python', 'iritkatriel']
pr_nums = ['22356']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue41825'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']
    @birkenfeld
    Copy link
    Member Author

    There are a few points where os.waitid() docs need improvement. Current text:

    Wait for the completion of one or more child processes. idtype can be P_PID, P_PGID or P_ALL. id specifies the pid to wait on. options is constructed from the ORing of one or more of WEXITED, WSTOPPED or WCONTINUED and additionally may be ORed with WNOHANG or WNOWAIT. The return value is an object representing the data contained in the siginfo_t structure, namely: si_pid, si_uid, si_signo, si_status, si_code or None if WNOHANG is specified and there are no children in a waitable state.

    Problems are:

    • The given use of the pid argument is only for the case of idtype=P_PID. For P_ALL it is ignored, and for P_PGID it specifies that the child's PGID must be pid.

    • "One or more child processes" is misleading -- the function waits for until exactly one child process to exit (or aborts with WNOHANG). Sure, there can be multiple candidate processes, but this should be formulated differently.

    • The explanation of *options* is quite cumbersome, it seems to be copied directly from the manpage (where it is laid out much more clearly and with explanation of the different options).

    Additionally the flags P_, W and CLD_* are just stated as-is, and need explanation in the docs. You should not need to consult the manpage to be able to use the function at all.

    @birkenfeld birkenfeld added 3.8 only security fixes 3.10 only security fixes 3.9 only security fixes labels Sep 21, 2020
    @birkenfeld birkenfeld added docs Documentation in the Doc dir easy type-feature A feature request or enhancement 3.8 only security fixes 3.10 only security fixes 3.9 only security fixes labels Sep 21, 2020
    @birkenfeld birkenfeld added docs Documentation in the Doc dir easy type-feature A feature request or enhancement labels Sep 21, 2020
    @iritkatriel iritkatriel added stdlib Python modules in the Lib dir 3.11 only security fixes and removed 3.8 only security fixes labels Jun 24, 2021
    @iritkatriel
    Copy link
    Member

    See also bpo-38802, bpo-34278, bpo-27808.

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @ddurgoji
    Copy link

    How do I know if a open issue has PR submitted/merged or not?
    I saw few tickets which are in open state but already has a open or merged PR.

    @iritkatriel
    Copy link
    Member

    How do I know if a open issue has PR submitted/merged or not?
    I saw few tickets which are in open state but already has a open or merged PR.

    Please use the core- mentorship list for general questions of this kind.

    @birkenfeld birkenfeld mentioned this issue Nov 26, 2022
    Merged
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir easy stdlib Python modules in the Lib dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    Successfully merging a pull request may close this issue.

    bpo-41825: restructure docs for the os.wait*() family
    3 participants
    @birkenfeld @iritkatriel @ddurgoji