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

[johnhawkinson]

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/

[cpython-cla-bot]

All commit authors signed the Contributor License Agreement.

[johnhawkinson]

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]

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]

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]

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]

LGTM

Thanks for the PR!

[miss-islington-app]

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

[bedevere-app]

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

[bedevere-app]

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