Skip to content

Clarify the docs for args in asyncio callbacks #143873

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.

Sign up for GitHub

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

Open
akx wants to merge 1 commit into
base: main
Choose a base branch
from
+12 −9
Open

Clarify the docs for args in asyncio callbacks #143873

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions Doc/library/asyncio-eventloop.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <asyncio-pass-keywords>` to
*callback*.

An optional keyword-only *context* argument allows specifying a
custom :class:`contextvars.Context` for the *callback* to run in.
Expand Down Expand Up @@ -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
Copy link
Member

@StanFromIreland StanFromIreland Jan 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please avoid such rewordings, and italics should be used for parameter names.

Copy link
Contributor Author

@akx akx Jan 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the rewording makes it clearer (and kinder, in a sense). (What's the particular "such" here, though, so I know to avoid, well, such things in the future?)

My point for the italics was to emphasize for the reader that this is for keyword arguments, and the *args mechanism is already there for posargs.

<asyncio-pass-keywords>` to *callback*.

.. method:: loop.remove_writer(fd)
Expand Down Expand Up @@ -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
Expand All @@ -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
Copy link
Member

@StanFromIreland StanFromIreland Jan 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto here.

<asyncio-pass-keywords>` to *callback*.

Like :func:`signal.signal`, this function must be invoked in the main
Expand All @@ -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``.
Expand Down Expand Up @@ -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
Copy link
Member

@StanFromIreland StanFromIreland Jan 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And here.

<asyncio-pass-keywords>` to *func*.

.. versionchanged:: 3.5.3
Expand Down
Loading