gh-52597: Add position-only markers for os functions

[slateny]

#52597

chflags skipped as I couldn't test it due to some AttributeError, but per clinic follow_symlinks shouldn't be keyword-only.

---

For verification, first to get all functions changed:

git diff -U0 HEAD~ | grep '+\.\.' | cut -d' ' -f3 | cut -d'(' -f1

To show the params in the docs:

echo getgrouplist | xargs -n1 -I = grep 'function:: =(' Doc/library/os.rst | sed -r 's|.. function:: (.*)|\1|g'

To show the params in clinic:

echo getgrouplist | xargs -n1 -I = grep '\"=(' Modules/clinic/posixmodule.c.h | sed -r 's|.(.*).module, (.*)...|\1\2|g' | uniq

And combined:

git diff -U0 HEAD~ | grep '+\.\.' | cut -d' ' -f3 | cut -d'(' -f1 | xargs -n1 -I = sh -c "grep 'function:: =(' Doc/library/os.rst | sed -r 's|.. function:: (.*)|\1|g'; grep '\"=(' Modules/clinic/posixmodule.c.h | sed -r 's|.(.*).module, (.*)...|\1\2|g' | uniq; echo" | uniq -u

The last command shows any differences in positional/keyword markers or param names. On visual inspection, all diffs just seem to be differences in param names so the markers in the doc are correct.

[slateny]

@JelleZijlstra Could you take a peek at this one since you'd looked over the docs for io?

[JelleZijlstra]

Thanks! I used this also for fixing a few missing pos-only markers in typeshed: python/typeshed#8283, python/typeshed#8284.

[JelleZijlstra]

Strangely enough, this one is indeed pos-only, but all the other similar ones below it aren't.

[slateny]

Looking at

cpython/Modules/clinic/posixmodule.c.h

Lines 4282 to 4318 in 1009bf1

	"WCOREDUMP($module, status, /)\n"
	"--\n"
	"\n"
	"Return True if the process returning status was dumped to a core file.");
	#define OS_WCOREDUMP_METHODDEF \
	{"WCOREDUMP", (PyCFunction)os_WCOREDUMP, METH_VARARGS, os_WCOREDUMP__doc__},
	static int
	os_WCOREDUMP_impl(PyModuleDef *module, int status);
	static PyObject *
	os_WCOREDUMP(PyModuleDef *module, PyObject *args)
	{
	PyObject *return_value = NULL;
	int status;
	int _return_value;
	if (!PyArg_ParseTuple(args,
	"i:WCOREDUMP",
	&status))
	goto exit;
	_return_value = os_WCOREDUMP_impl(module, status);
	if ((_return_value == -1) && PyErr_Occurred())
	goto exit;
	return_value = PyBool_FromLong((long)_return_value);
	exit:
	return return_value;
	}
	#endif /* defined(HAVE_SYS_WAIT_H) && defined(WCOREDUMP) */
	#if defined(HAVE_SYS_WAIT_H) && defined(WIFCONTINUED)
	PyDoc_STRVAR(os_WIFCONTINUED__doc__,
	"WIFCONTINUED($module, /, status)\n"

when the file was first made the markers were already in place, so maybe there's some reason for it.

Separately, could you check whether you're able to run os.plock(op=None) to verify the keyword can't be used? I gave all the functions a quick run to double-check but like chflags, I'm not able to run plock for some reason.

[slateny]

Actually, seeing that the clinic def

cpython/Modules/clinic/posixmodule.c.h

Lines 3688 to 3692 in f0bf795

	PyDoc_STRVAR(os_plock__doc__,
	"plock($module, op, /)\n"
	"--\n"
	"\n"
	"Lock program segments into memory.\");");

has the position-only marker, then regardless of whether it can be confirmed, adding the plock change would arguably be strictly better than the current docs. In that case, tracking this particular problem can go into some other issue instead, and I'd reckon that the change can go ahead anyways, if there aren't any other problems with the PR.

[miss-islington]

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

[miss-islington]

Sorry @slateny and @JelleZijlstra, I had trouble checking out the 3.11 backport branch.
Please backport using cherry_picker on command line.
cherry_picker c759944f16ed9887a77d5ebd738f17f3892c2476 3.11

[miss-islington]

Sorry, @slateny and @JelleZijlstra, I could not cleanly backport this to 3.10 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker c759944f16ed9887a77d5ebd738f17f3892c2476 3.10

[miss-islington]

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

[bedevere-bot]

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