classification
Title: kqueue.control() documentation and implementation mismatch
Type: behavior Stage:
Components: Documentation Versions: Python 3.7, Python 3.6, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: a.badger, berker.peksag, docs@python, martin.panter, taleinat, xtreak
Priority: normal Keywords:

Created on 2018-08-10 06:20 by a.badger, last changed 2018-08-12 10:21 by taleinat.

Messages (7)
msg323357 - (view) Author: Toshio Kuratomi (a.badger) * Date: 2018-08-10 06:20
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
    control(changelist, max_events[, timeout=None]) -> eventlist
    
    Calls the kernel kevent function.
    - changelist must be an iterable of kevent objects describing the changes
      to be made to the kernel's watch list or None.
    - max_events lets you specify the maximum number of events that the
      kernel will return.
    - timeout is the maximum time to wait in seconds, or else None,
      to wait forever. timeout accepts floats for smaller timeouts, too.

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.
msg323366 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-08-10 12:00
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
    Polls the set of registered file descriptors.

>>> select.poll().poll(timeout=0.1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: poll() takes no keyword arguments
msg323370 - (view) Author: Toshio Kuratomi (a.badger) * Date: 2018-08-10 13:50
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.
msg323426 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2018-08-12 00:21
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 Issue 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 Issue 21314 about explaining this notation in the documentation somewhere.
msg323435 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2018-08-12 07:50
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
    Calls the kernel kevent function.

    changelist
      Must be an iterable of kevent objects describing the changes to be made
      to the kernel's watch list or None.
    maxevents
      The maximum number of events that the kernel will return.
    timeout
      The maximum time to wait in seconds, or else None to wait forever.
      This accepts floats for smaller timeouts, too.
msg323438 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2018-08-12 09:56
Even in 3.8, the main documentation is not fixed: https://docs.python.org/dev/library/select.html#kqueue-objects
msg323439 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2018-08-12 10:21
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?).
History
Date User Action Args
2018-08-12 10:21:54taleinatsetmessages: + msg323439
2018-08-12 09:56:15martin.pantersetmessages: + msg323438
2018-08-12 07:50:05taleinatsetmessages: + msg323435
versions: + Python 3.6
2018-08-12 00:21:27martin.pantersetversions: + Python 2.7
nosy: + martin.panter, docs@python

messages: + msg323426

assignee: docs@python
components: + Documentation, - Library (Lib)
2018-08-10 13:50:21a.badgersetmessages: + msg323370
2018-08-10 12:00:01berker.peksagsetnosy: + berker.peksag, taleinat

messages: + msg323366
versions: - Python 2.7
2018-08-10 11:38:55xtreaksetnosy: + xtreak
2018-08-10 06:20:16a.badgercreate