classification
Title: Tweak parameter names for fcntl module
Type: enhancement Stage: commit review
Components: Documentation Versions: Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: serhiy.storchaka Nosy List: ashkop, berker.peksag, brett.cannon, docs@python, martin.panter, python-dev, r.david.murray, serhiy.storchaka
Priority: normal Keywords: easy, patch

Created on 2014-11-10 01:32 by brett.cannon, last changed 2015-03-22 10:33 by martin.panter. This issue is now closed.

Files
File name Uploaded Description Edit
issue22832.patch ashkop, 2015-02-27 08:55 review
issue22832_v2.patch ashkop, 2015-03-02 07:31 review
issue22832_v3.patch ashkop, 2015-03-20 11:20 review
Messages (15)
msg230931 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2014-11-10 01:32
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.
msg236733 - (view) Author: Alex Shkop (ashkop) * Date: 2015-02-27 08:55
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.
msg236749 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2015-02-27 14:10
The patch LGTM. Serhiy, you have anything to add?
msg236760 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-02-27 15:07
I found a lot of not related issues in the documentation.
msg236767 - (view) Author: Alex Shkop (ashkop) * Date: 2015-02-27 15:34
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?
msg236775 - (view) Author: Alex Shkop (ashkop) * Date: 2015-02-27 16:12
Docs say that mutate_flag is true by default since Python 2.5. Looks like I should fix the docstring.
msg237024 - (view) Author: Alex Shkop (ashkop) * Date: 2015-03-02 07:31
This patch fixes pointed out bugs in documentation and docstring for ioctl() function.
msg238646 - (view) Author: Alex Shkop (ashkop) * Date: 2015-03-20 11:20
Fixed default values for fcntl(), ioctl() and lockf()
msg238703 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-20 17:58
Except brackets the patch LGTM.
msg238706 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-03-20 18:18
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
msg238707 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-20 18:19
Thanks you for your patch Alex.
msg238736 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-03-20 23:30
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.
msg238747 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2015-03-21 01:59
> 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.
msg238762 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-21 04:44
This is worth a discussion on Python-Dev.
http://comments.gmane.org/gmane.comp.python.devel/152025
msg238891 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-03-22 10:33
I opened Issue 23738 about my problem with the new signature, so it does not get forgotten.
History
Date User Action Args
2015-03-22 10:33:19martin.pantersetmessages: + msg238891
2015-03-21 04:44:38serhiy.storchakasetmessages: + msg238762
2015-03-21 01:59:13berker.peksagsetnosy: + berker.peksag
messages: + msg238747
2015-03-20 23:30:39martin.pantersetmessages: + msg238736
2015-03-20 18:19:55serhiy.storchakasetstatus: open -> closed
resolution: fixed
messages: + msg238707
2015-03-20 18:18:36python-devsetnosy: + python-dev
messages: + msg238706
2015-03-20 17:58:36serhiy.storchakasetmessages: + msg238703
2015-03-20 12:26:25brett.cannonsetassignee: docs@python -> serhiy.storchaka
2015-03-20 11:20:09ashkopsetfiles: + issue22832_v3.patch

messages: + msg238646
2015-03-20 02:25:05martin.pantersetnosy: + martin.panter
2015-03-02 07:31:46ashkopsetfiles: + issue22832_v2.patch

messages: + msg237024
2015-02-27 16:12:12ashkopsetmessages: + msg236775
2015-02-27 15:34:03ashkopsetmessages: + msg236767
2015-02-27 15:07:08serhiy.storchakasetnosy: + r.david.murray
messages: + msg236760
2015-02-27 14:10:07brett.cannonsetmessages: + msg236749
stage: needs patch -> commit review
2015-02-27 08:55:56ashkopsetfiles: + issue22832.patch

nosy: + ashkop
messages: + msg236733

keywords: + patch
2014-11-10 01:32:31brett.cannoncreate