From 4b8658a567ac9e6b8c709841ac59f5da70fca651 Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Thu, 15 Jan 2026 17:16:01 +0200 Subject: [PATCH] Clarify the docs for `args` in asyncio callbacks --- Doc/library/asyncio-eventloop.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 72f484fd1cbe77..759c4fe93b073a 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -297,8 +297,9 @@ clocks to track time. are called is undefined. The optional positional *args* will be passed to the callback when - it is called. If you want the callback to be called with keyword - arguments use :func:`functools.partial`. + it is called. You can use :func:`functools.partial` + :ref:`to pass *keyword* arguments ` to + *callback*. An optional keyword-only *context* argument allows specifying a custom :class:`contextvars.Context` for the *callback* to run in. @@ -1034,13 +1035,13 @@ Watching file descriptors .. method:: loop.add_writer(fd, callback, *args) Start monitoring the *fd* file descriptor for write availability and - invoke *callback* with the specified arguments once *fd* is available for - writing. + invoke *callback* with the specified arguments *args* once *fd* is + available for writing. Any preexisting callback registered for *fd* is cancelled and replaced by *callback*. - Use :func:`functools.partial` :ref:`to pass keyword arguments + You can use :func:`functools.partial` :ref:`to pass *keyword* arguments ` to *callback*. .. method:: loop.remove_writer(fd) @@ -1308,7 +1309,8 @@ Unix signals .. method:: loop.add_signal_handler(signum, callback, *args) - Set *callback* as the handler for the *signum* signal. + Set *callback* as the handler for the *signum* signal, + passing *args* as positional arguments. The callback will be invoked by *loop*, along with other queued callbacks and runnable coroutines of that event loop. Unlike signal handlers @@ -1318,7 +1320,7 @@ Unix signals Raise :exc:`ValueError` if the signal number is invalid or uncatchable. Raise :exc:`RuntimeError` if there is a problem setting up the handler. - Use :func:`functools.partial` :ref:`to pass keyword arguments + You can use :func:`functools.partial` :ref:`to pass *keyword* arguments ` to *callback*. Like :func:`signal.signal`, this function must be invoked in the main @@ -1343,7 +1345,8 @@ Executing code in thread or process pools .. awaitablemethod:: loop.run_in_executor(executor, func, *args) - Arrange for *func* to be called in the specified executor. + Arrange for *func* to be called in the specified executor + with *args* being passed as positional arguments. The *executor* argument should be an :class:`concurrent.futures.Executor` instance. The default executor is used if *executor* is ``None``. @@ -1406,7 +1409,7 @@ Executing code in thread or process pools This method returns a :class:`asyncio.Future` object. - Use :func:`functools.partial` :ref:`to pass keyword arguments + You can use :func:`functools.partial` :ref:`to pass *keyword* arguments ` to *func*. .. versionchanged:: 3.5.3