[Python-checkins] gh-97696: Improve and fix documentation for asyncio eager tasks (#104256)

[kumaraditya303]

https://github.com/python/cpython/commit/c2683fc46d775d6c4afcb23658c0fd1e328e3c53
commit: c2683fc46d775d6c4afcb23658c0fd1e328e3c53
branch: main
author: Itamar Ostricher <itamarost at gmail.com>
committer: kumaraditya303 <59607654+kumaraditya303 at users.noreply.github.com>
date: 2023-05-08T17:29:34+05:30
summary:

gh-97696: Improve and fix documentation for asyncio eager tasks (#104256)

files:
M Doc/library/asyncio-task.rst
M Misc/NEWS.d/next/Library/2023-05-03-16-51-53.gh-issue-104144.653Q0P.rst

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index a46ebc1c3d25..b2d7362a9de2 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -560,6 +560,13 @@ Eager Task Factory
     using the provided *custom_task_constructor* when creating a new task instead
     of the default :class:`Task`.
 
+    *custom_task_constructor* must be a *callable* with the signature matching
+    the signature of :class:`Task.__init__ <Task>`.
+    The callable must return a :class:`asyncio.Task`-compatible object.
+
+    This function returns a *callable* intended to be used as a task factory of an
+    event loop via :meth:`loop.set_task_factory(factory) <loop.set_task_factory>`).
+
     .. versionadded:: 3.12
 
 
@@ -1014,7 +1021,7 @@ Introspection
 Task Object
 ===========
 
-.. class:: Task(coro, *, loop=None, name=None, context=None)
+.. class:: Task(coro, *, loop=None, name=None, context=None, eager_start=False)
 
    A :class:`Future-like <Future>` object that runs a Python
    :ref:`coroutine <coroutine>`.  Not thread-safe.
@@ -1054,6 +1061,13 @@ Task Object
    If no *context* is provided, the Task copies the current context
    and later runs its coroutine in the copied context.
 
+   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.7
       Added support for the :mod:`contextvars` module.
 
@@ -1067,6 +1081,9 @@ Task Object
    .. versionchanged:: 3.11
       Added the *context* parameter.
 
+   .. versionchanged:: 3.12
+      Added the *eager_start* parameter.
+
    .. method:: done()
 
       Return ``True`` if the Task is *done*.
diff --git a/Misc/NEWS.d/next/Library/2023-05-03-16-51-53.gh-issue-104144.653Q0P.rst b/Misc/NEWS.d/next/Library/2023-05-03-16-51-53.gh-issue-104144.653Q0P.rst
index 59870de3e02e..ced3b7cea049 100644
--- a/Misc/NEWS.d/next/Library/2023-05-03-16-51-53.gh-issue-104144.653Q0P.rst
+++ b/Misc/NEWS.d/next/Library/2023-05-03-16-51-53.gh-issue-104144.653Q0P.rst
@@ -1 +1,2 @@
-Optimize :class:`asyncio.TaskGroup` when using :func:`asyncio.eager_task_factory`. Skip scheduling done callbacks when all tasks finish without blocking.
+Optimize :class:`asyncio.TaskGroup` when using :func:`asyncio.eager_task_factory`.
+Skip scheduling a done callback if a TaskGroup task completes eagerly.