http://bugs.python.org/review/20152/ is filled with various suggestions from Serhiy on how to update the function parameters in the fcntl module to more closely match what is in the man pages. This should be fully backwards-compatible as the parameters are positional-only. It should be easy as the code doesn't need to change thanks to Argument Clinic. Trick will be updating both the code and the docs.

Created a patch. It renames arguments in clinic declarations and in documents. For lockf I've chosen Linux naming, because it really calls fcntl which has an argument called cmd, not function.

The patch LGTM. Serhiy, you have anything to add?

I found a lot of not related issues in the documentation.

Looks like default value for mutate_flag in ioctl() should be False. Docstring says:

"If the argument is a mutable buffer and the mutable_flag argument is not
passed or is false, the behavior is as if a string had been passed."

Should I change the default value or the docstring?

Docs say that mutate_flag is true by default since Python 2.5. Looks like I should fix the docstring.

This patch fixes pointed out bugs in documentation and docstring for ioctl() function.

Fixed default values for fcntl(), ioctl() and lockf()

Except brackets the patch LGTM.

New changeset a3c9c2c92b87 by Serhiy Storchaka in branch 'default':
Issue #22832: Tweaked parameter names for fcntl module to better match
https://hg.python.org/cpython/rev/a3c9c2c92b87

Thanks you for your patch Alex.

I object to dropping the brackets from the function signatures. Now it gives the impression that the functions accept keyword arguments:

ioctl(fd, request, arg=0, mutate_flag=True)

but:

>>> ioctl(0, 0, bytearray(), mutate_flag=False)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: ioctl() takes no keyword arguments

There is already a little bit of precedent for this, e.g. the built-in eval() function, but I would prefer using square brackets, or some other non-Python syntax indicator.

> I object to dropping the brackets from the function signatures. Now it gives the impression that the functions accept keyword arguments:

See issue 21488 for a similar confusion.

This is worth a discussion on Python-Dev.
http://comments.gmane.org/gmane.comp.python.devel/152025

I opened Issue 23738 about my problem with the new signature, so it does not get forgotten.