From 6f86628759ded007feb326eb97a24996813c14f5 Mon Sep 17 00:00:00 2001 From: Zane Bitter Date: Thu, 24 Sep 2020 21:10:45 -0400 Subject: [PATCH] bpo-41857: Document timeout arguments in select module The docstring for the poll() methods of the select.poll[1] and select.devpoll[2] classes did not describe the expected units of the timeout argument (milliseconds). Previously this information was only available from the online documentation. This is a potential source of confusion, because other poll() methods in the select module, such as select.epoll and select.kqueue objects, use units of seconds (and were documented). Include the units in the docstring description so that this information is at least available from interactive help. [1] https://docs.python.org/3/library/select.html#select.poll.poll [2] https://docs.python.org/3/library/select.html#select.devpoll.poll --- Modules/clinic/selectmodule.c.h | 10 +++++++++- Modules/selectmodule.c | 8 ++++++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/Modules/clinic/selectmodule.c.h b/Modules/clinic/selectmodule.c.h index d7095dfb00ead9..be752e981667ce 100644 --- a/Modules/clinic/selectmodule.c.h +++ b/Modules/clinic/selectmodule.c.h @@ -193,6 +193,10 @@ PyDoc_STRVAR(select_poll_poll__doc__, "\n" "Polls the set of registered file descriptors.\n" "\n" +" timeout\n" +" The maximum time to wait in milliseconds, or else None (or a negative\n" +" value) to wait indefinitely.\n" +"\n" "Returns a list containing any descriptors that have events or errors to\n" "report, as a list of (fd, event) 2-tuples."); @@ -363,6 +367,10 @@ PyDoc_STRVAR(select_devpoll_poll__doc__, "\n" "Polls the set of registered file descriptors.\n" "\n" +" timeout\n" +" The maximum time to wait in milliseconds, or else None (or a negative\n" +" value) to wait indefinitely.\n" +"\n" "Returns a list containing any descriptors that have events or errors to\n" "report, as a list of (fd, event) 2-tuples."); @@ -1179,4 +1187,4 @@ select_kqueue_control(kqueue_queue_Object *self, PyObject *const *args, Py_ssize #ifndef SELECT_KQUEUE_CONTROL_METHODDEF #define SELECT_KQUEUE_CONTROL_METHODDEF #endif /* !defined(SELECT_KQUEUE_CONTROL_METHODDEF) */ -/*[clinic end generated code: output=cd2062a787e13b35 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=a8fc031269d28454 input=a9049054013a1b77]*/ diff --git a/Modules/selectmodule.c b/Modules/selectmodule.c index 693a833caea77b..2a222b68075466 100644 --- a/Modules/selectmodule.c +++ b/Modules/selectmodule.c @@ -564,6 +564,8 @@ select_poll_unregister_impl(pollObject *self, int fd) select.poll.poll timeout as timeout_obj: object = None + The maximum time to wait in milliseconds, or else None (or a negative + value) to wait indefinitely. / Polls the set of registered file descriptors. @@ -574,7 +576,7 @@ report, as a list of (fd, event) 2-tuples. static PyObject * select_poll_poll_impl(pollObject *self, PyObject *timeout_obj) -/*[clinic end generated code: output=876e837d193ed7e4 input=7a446ed45189e894]*/ +/*[clinic end generated code: output=876e837d193ed7e4 input=c2f6953ec45e5622]*/ { PyObject *result_list = NULL; int poll_result, i, j; @@ -895,6 +897,8 @@ select_devpoll_unregister_impl(devpollObject *self, int fd) /*[clinic input] select.devpoll.poll timeout as timeout_obj: object = None + The maximum time to wait in milliseconds, or else None (or a negative + value) to wait indefinitely. / Polls the set of registered file descriptors. @@ -905,7 +909,7 @@ report, as a list of (fd, event) 2-tuples. static PyObject * select_devpoll_poll_impl(devpollObject *self, PyObject *timeout_obj) -/*[clinic end generated code: output=2654e5457cca0b3c input=fd0db698d84f0333]*/ +/*[clinic end generated code: output=2654e5457cca0b3c input=3c3f0a355ec2bedb]*/ { struct dvpoll dvp; PyObject *result_list = NULL;