update docs about create_task

Author: graingert

Doc/library/asyncio-eventloop.rst

@@ -355,7 +355,7 @@ Creating Futures and Tasks
 
    .. 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)
 
    Schedule the execution of :ref:`coroutine <coroutine>` *coro*.
    Return a :class:`Task` object.
@@ -371,12 +371,27 @@ Creating Futures and Tasks
    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.
+
    .. 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.
+
+   .. versionchanged:: 3.13.4
+      Rolled back the change that passes on *name* and *context* (if it is None),
+      passing on new keword arguments such as *eager_start* is still supported.
+
 .. method:: loop.set_task_factory(factory)
 
    Set a task factory that will be used by
@@ -388,6 +403,13 @@ 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``.
+
 .. method:: loop.get_task_factory()
 
    Return a task factory or ``None`` if the default one is in use.

Doc/library/asyncio-task.rst

@@ -238,18 +238,31 @@ 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.
 
+   The arguments shown above are merely the most common ones, described below
+   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 *name* is 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.
+
    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 +303,14 @@ Creating Tasks
    .. 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.
+
+   .. versionchanged:: 3.13.4
+      Rolled back the change that passes on *name* and *context* (if it is None),
+      passing on new keword arguments such as *eager_start* is still supported.
+
 
 Task Cancellation
 =================
@@ -330,10 +351,10 @@ 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`.
+      The signature matches that of :meth:`loop.create_task`.
       If the task group is inactive (e.g. not yet entered,
       already finished, or in the process of shutting down),
       we will close the given ``coro``.
@@ -342,6 +363,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.13.3
+
+         Passes on all keyword arguments to :meth:`loop.create_task`
+
 Example::
 
     async def main():