◐ Shell
reader mode source ↗
Skip to content

Doc/library/os.rst: os.waitid absent on MacOS#104558

Merged
ronaldoussoren merged 3 commits into
python:mainfrom
johnhawkinson:2024.05.16.osx-waitid-doc
Dec 28, 2023
Merged

Doc/library/os.rst: os.waitid absent on MacOS#104558
ronaldoussoren merged 3 commits into
python:mainfrom
johnhawkinson:2024.05.16.osx-waitid-doc

Conversation

@johnhawkinson

@johnhawkinson johnhawkinson commented May 16, 2023 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Contributor

os.waitid() is disabled on MacOS, and that's not documented.
It's not precisely clear why its disabled, and it was discussed in #55021 (deeplink) which was closed without resolution.

But regardless of why, the documentation needs to clearly reflect that the function is not available.

I've followed the model of os.fdatasync() and noted the lack of availability in the Note section, rather than the Availability section. Absent that precedent, I would have instead changed Availability to Unix, not Emscripten, not Macos, not WASI, perhaps somewhat consistent with CLOCK_UPTIME_RAW in time.rst L866.

I hope this is appropriate for a PR without an Issue, but if I'm wrong, I apologize and am happy to file an Issue.

📚 Documentation preview 📚: https://cpython-previews--104558.org.readthedocs.build/

@bedevere-bot bedevere-bot added awaiting review docs Documentation in the Doc dir skip news labels May 16, 2023
@ghost

ghost commented May 16, 2023 •
edited by ghost
Loading

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.
CLA signed

@johnhawkinson johnhawkinson force-pushed the 2024.05.16.osx-waitid-doc branch from b2399e2 to e7bc73d Compare May 16, 2023 18:11
@johnhawkinson

johnhawkinson commented May 17, 2023

Copy link
Copy Markdown
Contributor Author

os.waitid() is disabled on MacOS, and that's not documented.

I probably should have supported the statement that it's disabled, sorry.
As discussed in the linked issue, the disabling is from the && !defined(__APPLE__) here:

cpython/Modules/posixmodule.c

Lines 9191 to 9213 in c649df6

#if defined(HAVE_WAITID) && !defined(__APPLE__)
/*[clinic input]
os.waitid
idtype: idtype_t
Must be one of be P_PID, P_PGID or P_ALL.
id: id_t
The id to wait on.
options: int
Constructed from the ORing of one or more of WEXITED, WSTOPPED
or WCONTINUED and additionally may be ORed with WNOHANG or WNOWAIT.
/
Returns the result of waiting for a process or processes.
Returns either waitid_result or None if WNOHANG is specified and there are
no children in a waitable state.
[clinic start generated code]*/
static PyObject *
os_waitid_impl(PyObject *module, idtype_t idtype, id_t id, int options)
/*[clinic end generated code: output=5d2e1c0bde61f4d8 input=d8e7f76e052b7920]*/
{

@ronaldoussoren

ronaldoussoren commented Dec 27, 2023

Copy link
Copy Markdown
Contributor

The more interesting question here is why os.waitid is not exposed on macOS.

There's some discussion in #55021, waitid was not exposed for unclear reasons. IMHO we should expose it for macOS and if needed document limitations with the API (it was disabled for unspecified problems in versions of the OS that we no longer supported in our installers).

@johnhawkinson

johnhawkinson commented Dec 27, 2023

Copy link
Copy Markdown
Contributor Author

The more interesting question here is why os.waitid is not exposed on macOS.

You know…no it's not!

If it takes 6 months to get a doc fix in and 12 months to have a policy debate and maybe change the policy and get a code fix in, I am entirely uninterested in postponing the former in favor of the latter. Open a new PR or Issue to expose waitid but don't hold up fixing the broken documentation now.

Thank you. I am not as bitter as I sound.

@ronaldoussoren

ronaldoussoren commented Dec 28, 2023

Copy link
Copy Markdown
Contributor

Thank you. I am not as bitter as I sound.

I don't know about other core devs, but personally I only regularly check GitHub issues for things to work on. That's mostly out of habit, but we do have a longstanding culture of having issues for almost all changes. I'm not going to argue that's a good thing, but it does explain why PRs without an issue can get lost and not get core dev attention.

Anyway, I'll file an issue about exposing os.waitid in 3.13 and will return to this PR soon with the intention to merge it.

@ronaldoussoren @aisk
Update Doc/library/os.rst …
273d105 
Co-authored-by: AN Long <aisk@users.noreply.github.com>
ronaldoussoren
ronaldoussoren approved these changes Dec 28, 2023
View reviewed changes

@ronaldoussoren ronaldoussoren left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hide comment

LGTM

Thanks for the PR!

@ronaldoussoren ronaldoussoren merged commit db1c882 into python:main Dec 28, 2023
@miss-islington-app

miss-islington-app Bot commented Dec 28, 2023

Copy link
Copy Markdown

Thanks @johnhawkinson for the PR, and @ronaldoussoren for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Dec 28, 2023
@johnhawkinson @aisk @miss-islington
Doc/library/os.rst: os.waitid absent on MacOS (pythonGH-104558) …
47361e6 
* Doc/library/os.rst: `os.waitid` absent on MacOS

(cherry picked from commit db1c882)

Co-authored-by: John Hawkinson <jhawk@alum.mit.edu>
Co-authored-by: AN Long <aisk@users.noreply.github.com>
@bedevere-app

bedevere-app Bot commented Dec 28, 2023

Copy link
Copy Markdown

GH-113553 is a backport of this pull request to the 3.12 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.12 only security fixes label Dec 28, 2023
@bedevere-app

bedevere-app Bot commented Dec 28, 2023

Copy link
Copy Markdown

GH-113554 is a backport of this pull request to the 3.11 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.11 only security fixes label Dec 28, 2023
ronaldoussoren pushed a commit that referenced this pull request Dec 29, 2023
@miss-islington @johnhawkinson @aisk
[3.12] Doc/library/os.rst: os.waitid absent on MacOS (GH-104558) (#… …
f982ab5 
…113553)

Doc/library/os.rst: `os.waitid` absent on MacOS (GH-104558)

* Doc/library/os.rst: `os.waitid` absent on MacOS

(cherry picked from commit db1c882)

Co-authored-by: John Hawkinson <jhawk@alum.mit.edu>
Co-authored-by: AN Long <aisk@users.noreply.github.com>
ronaldoussoren pushed a commit that referenced this pull request Dec 29, 2023
@miss-islington @johnhawkinson @aisk
[3.11] Doc/library/os.rst: os.waitid absent on MacOS (GH-104558) (#… …
2025d9f 
…113554)

Doc/library/os.rst: `os.waitid` absent on MacOS (GH-104558)

* Doc/library/os.rst: `os.waitid` absent on MacOS

(cherry picked from commit db1c882)

Co-authored-by: John Hawkinson <jhawk@alum.mit.edu>
Co-authored-by: AN Long <aisk@users.noreply.github.com>
kulikjak pushed a commit to kulikjak/cpython that referenced this pull request Jan 22, 2024
@johnhawkinson @aisk @kulikjak
Doc/library/os.rst: os.waitid absent on MacOS (python#104558) …
4f91191 
* Doc/library/os.rst: `os.waitid` absent on MacOS

Co-authored-by: AN Long <aisk@users.noreply.github.com>
aisk added a commit to aisk/cpython that referenced this pull request Feb 11, 2024
@johnhawkinson @aisk
Doc/library/os.rst: os.waitid absent on MacOS (python#104558) …
33937bc 
* Doc/library/os.rst: `os.waitid` absent on MacOS

Co-authored-by: AN Long <aisk@users.noreply.github.com>
Glyphack pushed a commit to Glyphack/cpython that referenced this pull request Sep 2, 2024
@johnhawkinson @aisk @Glyphack
Doc/library/os.rst: os.waitid absent on MacOS (python#104558) …
d5ffe7b 
* Doc/library/os.rst: `os.waitid` absent on MacOS

Co-authored-by: AN Long <aisk@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@aisk aisk aisk left review comments

@ronaldoussoren ronaldoussoren ronaldoussoren approved these changes

Assignees

No one assigned

Labels

docs Documentation in the Doc dir OS-mac skip issue skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@johnhawkinson @ronaldoussoren @aisk @arhadthedev @bedevere-bot