[3.14] gh-128307: Update docs for asyncio.create_task, TaskGroup.create_task, asyncio.create_task (GH-134202) (#134553)

miss-islington · graingert · web-flow · commit 1cdbb33771f7 · 2025-05-23T09:36:19.000+05:30
gh-128307: Update docs for asyncio.create_task, TaskGroup.create_task, asyncio.create_task (GH-134202) (cherry picked from commit a3d0306) Co-authored-by: Thomas Grainger <tagrain@gmail.com>
diff --git 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
@@ -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():
