New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
kqueue.control() documentation and implementation mismatch #78550
Comments
The current kqueue documentation specifies that timeout is a keyword argument but it can only be passed as a positional argument right now: >>> import select
>>> ko = select.kqueue()
>>> ko.control([1], 0, timeout=10)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: control() takes no keyword arguments
>>> help(ko.control)
Help on built-in function control: control(...) method of select.kqueue instance
This may be related to https://bugs.python.org/issue3852 in which the max_events argument used to be documented as optional but the code made it mandatory. |
This is probably a regression from the Argument Clinic conversion. Another docstring mismatches: select(rlist, wlist, xlist, timeout=None, /)
Wait until one or more file descriptors are ready for some kind of I/O. >>> select.select(timeout=0.1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: select() takes no keyword arguments poll(timeout=None, /) method of select.poll instance >>> select.poll().poll(timeout=0.1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: poll() takes no keyword arguments |
I don't believe (kqueue.control at least) is a regression from Argument Clinic. Both the documentation and the behaviour are the same in Python-2.7. |
I think this was an attempt to specify a positional-only parameter (by using square brackets), and include a default value in the signature. The usual approach in this situation is to use square brackets, but only mention the default value in the text: control(changelist, max_events[, timeout])
. . .
The default for "timeout" is None, to wait forever. In bpo-13386 Ezio suggested against showing both square brackets and a default value, and I agree. Berker: your "select" and "poll" cases all include the PEP-457 slash "/" notation, which was supposed to indicate positional-only parameters. See bpo-21314 about explaining this notation in the documentation somewhere. |
In Python 3.8 this will have already been fixed (thanks to the recent conversion of the select module to use Argument Clinic); see below output from a recent build from the master branch. Given that, is this worth fixing on 2.7 and <3.8? Help on built-in function control: control(changelist, maxevents, timeout=None, /) method of select.kqueue instance
|
Even in 3.8, the main documentation is not fixed: https://docs.python.org/dev/library/select.html#kqueue-objects |
We can just remove the "=None" in the docs for select.kqueue.control() to conform with the rest of that doc. We don't use the PEP-457 slash notation in the docs for select (or perhaps at all?). |
I think removing all mention of “None” is a step too far. The “devpoll”, “epoll”, and “poll” documentation all say that “None” is acceptable for the timeout. Only the “select” function doesn’t say this. What about adding to the text:
|
I agree Martin, I hadn't noticed that the docs don't otherwise mention the default behavior WRT timeout. I've added a description as per your suggestion to the PR. |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: