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

slateny · 2022-07-11T06:59:00Z

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 · 2022-07-11T07:02:43Z

@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 · 2022-07-12T19:02:17Z

Doc/library/os.rst

@@ -4538,7 +4538,7 @@ The following functions take a process status code as returned by
 :func:`system`, :func:`wait`, or :func:`waitpid` as a parameter.  They may be
 used to determine the disposition of a process.

-.. function:: WCOREDUMP(status)
+.. function:: WCOREDUMP(status, /)


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

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.

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 · 2022-09-29T01:06:53Z

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 · 2022-09-29T01:06:54Z

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 · 2022-09-29T01:06:57Z

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 · 2022-09-29T10:13:29Z

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

bedevere-bot · 2022-09-29T10:13:37Z

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

…94735) (cherry picked from commit c759944) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>

(cherry picked from commit c759944) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>

Add position-only markers for os functions

089e249

bedevere-bot added awaiting review docs Documentation in the Doc dir labels Jul 11, 2022

slateny added the skip news label Jul 11, 2022

JelleZijlstra approved these changes Jul 12, 2022

View changes

bedevere-bot added awaiting merge and removed awaiting review labels Jul 12, 2022

JelleZijlstra added needs backport to 3.10 needs backport to 3.11 labels Jul 12, 2022

JelleZijlstra self-assigned this Jul 12, 2022

slateny mentioned this pull request Jul 20, 2022

Missing position-only markers for function parameters #95034

Open

Merge branch 'main' into s/52597

c9adf73

JelleZijlstra merged commit c759944 into python:main Sep 29, 2022
14 checks passed

bedevere-bot removed the awaiting merge label Sep 29, 2022

AlexWaygood added needs backport to 3.11 and removed needs backport to 3.11 labels Sep 29, 2022

bedevere-bot removed the needs backport to 3.11 label Sep 29, 2022

miss-islington added a commit that referenced this pull request Sep 29, 2022

gh-52597: Add position-only markers for os functions (GH-94735)

11b6671

(cherry picked from commit c759944) Co-authored-by: Stanley <46876382+slateny@users.noreply.github.com>

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

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

slateny commented Jul 11, 2022

slateny commented Jul 11, 2022

JelleZijlstra left a comment

JelleZijlstra Jul 12, 2022

slateny Jul 13, 2022

slateny Jul 29, 2022

miss-islington commented Sep 29, 2022

miss-islington commented Sep 29, 2022

miss-islington commented Sep 29, 2022

miss-islington commented Sep 29, 2022

bedevere-bot commented Sep 29, 2022

	"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"

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

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

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

Conversation

slateny commented Jul 11, 2022

slateny commented Jul 11, 2022

JelleZijlstra left a comment

JelleZijlstra Jul 12, 2022

Choose a reason for hiding this comment

slateny Jul 13, 2022

Choose a reason for hiding this comment

slateny Jul 29, 2022

Choose a reason for hiding this comment

miss-islington commented Sep 29, 2022

miss-islington commented Sep 29, 2022

miss-islington commented Sep 29, 2022

miss-islington commented Sep 29, 2022

bedevere-bot commented Sep 29, 2022