Skip to content
Merged
Changes from 6 commits
Commits
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
29 changes: 28 additions & 1 deletion Doc/library/asyncio-eventloop.rst
Original file line number Diff line number Diff line change
Expand Up @@ -355,7 +355,7 @@

.. versionadded:: 3.5.2

.. method:: loop.create_task(coro, *, name=None, context=None)
.. method:: loop.create_task(coro, *, name=None, context=None, eager_start=None, **kwargs)
Comment thread
graingert marked this conversation as resolved.
Outdated

Schedule the execution of :ref:`coroutine <coroutine>` *coro*.
Return a :class:`Task` object.
Expand All @@ -364,19 +364,39 @@
for interoperability. In this case, the result type is a subclass
of :class:`Task`.

The full function signature is largely the same as that of the
:class:`Task` constructor (or factory) - all of the keyword arguments to
this function are passed through to that interface, except *name*,
or *context* if it is ``None``.

If the *name* argument is provided and not ``None``, it is set as
the name of the task using :meth:`Task.set_name`.

An optional keyword-only *context* argument allows specifying a
custom :class:`contextvars.Context` for the *coro* to run in.
The current context copy is created when no *context* is provided.

An optional keyword-only *eager_start* argument allows eagerly starting
the execution of the :class:`asyncio.Task` at task creation time.
If set to ``True`` and the event loop is running, the task will start
executing the coroutine immediately, until the first time the coroutine
blocks. If the coroutine returns or raises without blocking, the task
will be finished eagerly and will skip scheduling to the event loop.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I don't believe we should document eager_start here at all. I doesn't require special treatment, it can just be put in **kwargs. It looks like we added this in 3.13.4, and such feature changes in a bugfix release are frowned upon. We should only advertise **kwargs as an unfortunate added in3.13.3 and fixed in 3.13.4.

Comment thread
graingert marked this conversation as resolved.
Outdated
.. versionchanged:: 3.8
Added the *name* parameter.

.. versionchanged:: 3.11
Added the *context* parameter.

.. versionchanged:: 3.13.3
Added ``kwargs`` which always passes on ``kwargs`` such as the *eager_start*
parameter and *name* parameter.
Comment thread
graingert marked this conversation as resolved.
Outdated

.. versionchanged:: 3.13.4
Rolled back the change that passes on *name* and *context* (if it is None),
passing on new keyword arguments such as *eager_start* is still supported.
Comment thread
graingert marked this conversation as resolved.
Outdated

.. method:: loop.set_task_factory(factory)

Set a task factory that will be used by
Expand All @@ -388,6 +408,13 @@
event loop, and *coro* is a coroutine object. The callable
must pass on all *kwargs*, and return a :class:`asyncio.Task`-compatible object.

.. versionchanged:: 3.13.3
Required that all *kwargs* are passed on to :class:`asyncio.Task`.

Check warning on line 412 in Doc/library/asyncio-eventloop.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

Explicit markup ends without a blank line; unexpected unindent. [docutils]
Comment thread
graingert marked this conversation as resolved.
Outdated

.. versionchanged:: 3.13.4
*name* is no longer passed to task factories. *context* is no longer passed

Check warning on line 415 in Doc/library/asyncio-eventloop.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

Explicit markup ends without a blank line; unexpected unindent. [docutils]
to task factories if it is ``None``.
Comment thread
graingert marked this conversation as resolved.
Outdated

.. method:: loop.get_task_factory()

Return a task factory or ``None`` if the default one is in use.
Expand Down
Loading