https://github.com/python/cpython/commit/a3d0306ca08d09b1417d72df62e3b9d775143031
commit: a3d0306ca08d09b1417d72df62e3b9d775143031
branch: main
author: Thomas Grainger <[email protected]>
committer: gvanrossum <[email protected]>
date: 2025-05-22T15:54:56-07:00
summary:
gh-128307: Update docs for asyncio.create_task, TaskGroup.create_task,
asyncio.create_task (#134202)
files:
M Doc/library/asyncio-eventloop.rst
M Doc/library/asyncio-task.rst
diff --git a/Doc/library/asyncio-eventloop.rst
b/Doc/library/asyncio-eventloop.rst
index 21f7d0547af1dd..91970c282391f7 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -361,7 +361,7 @@ Creating Futures and Tasks
.. versionadded:: 3.5.2
-.. method:: loop.create_task(coro, *, name=None, context=None,
eager_start=None)
+.. method:: loop.create_task(coro, *, name=None, context=None,
eager_start=None, **kwargs)
Schedule the execution of :ref:`coroutine <coroutine>` *coro*.
Return a :class:`Task` object.
@@ -370,6 +370,10 @@ Creating Futures and Tasks
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.
+
If the *name* argument is provided and not ``None``, it is set as
the name of the task using :meth:`Task.set_name`.
@@ -388,8 +392,15 @@ Creating Futures and Tasks
.. versionchanged:: 3.11
Added the *context* parameter.
+ .. versionchanged:: 3.13.3
+ Added ``kwargs`` which passes on arbitrary extra parameters, including
``name`` and ``context``.
+
+ .. versionchanged:: 3.13.4
+ Rolled back the change that passes on *name* and *context* (if it is
None),
+ while still passing on other arbitrary keyword arguments (to avoid
breaking backwards compatibility with 3.13.3).
+
.. versionchanged:: 3.14
- Added the *eager_start* parameter.
+ All *kwargs* are now passed on. The *eager_start* parameter works with
eager task factories.
.. method:: loop.set_task_factory(factory)
@@ -402,6 +413,16 @@ Creating Futures and Tasks
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`.
+
+ .. versionchanged:: 3.13.4
+ *name* is no longer passed to task factories. *context* is no longer
passed
+ to task factories if it is ``None``.
+
+ .. versionchanged:: 3.14
+ *name* and *context* are now unconditionally passed on to task
factories again.
+
.. method:: loop.get_task_factory()
Return a task factory or ``None`` if the default one is in use.
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 59acce1990ae04..b19ffa8213a971 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -238,18 +238,24 @@ Creating Tasks
-----------------------------------------------
-.. function:: create_task(coro, *, name=None, context=None)
+.. function:: create_task(coro, *, name=None, context=None, eager_start=None,
**kwargs)
Wrap the *coro* :ref:`coroutine <coroutine>` into a :class:`Task`
and schedule its execution. Return the Task object.
- If *name* is not ``None``, it is set as the name of the task using
- :meth:`Task.set_name`.
+ 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.
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 specifying
+ if the task should execute eagerly during the call to create_task,
+ or be scheduled later. If *eager_start* is not passed the mode set
+ by :meth:`loop.set_task_factory` will be used.
+
The task is executed in the loop returned by :func:`get_running_loop`,
:exc:`RuntimeError` is raised if there is no running loop in
current thread.
@@ -290,6 +296,9 @@ Creating Tasks
.. versionchanged:: 3.11
Added the *context* parameter.
+ .. versionchanged:: 3.14
+ Added the *eager_start* parameter by passing on all *kwargs*.
+
Task Cancellation
=================
@@ -330,7 +339,7 @@ and reliable way to wait for all tasks in the group to
finish.
.. versionadded:: 3.11
- .. method:: create_task(coro, *, name=None, context=None)
+ .. method:: create_task(coro, *, name=None, context=None, eager_start=None,
**kwargs)
Create a task in this task group.
The signature matches that of :func:`asyncio.create_task`.
@@ -342,6 +351,10 @@ and reliable way to wait for all tasks in the group to
finish.
Close the given coroutine if the task group is not active.
+ .. versionchanged:: 3.14
+
+ Passes on all *kwargs* to :meth:`loop.create_task`
+
Example::
async def main():
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
