From fc37061f49b72a9e71a970337b0b335b6021ade9 Mon Sep 17 00:00:00 2001 From: Thomas Grainger Date: Sun, 18 May 2025 14:50:07 +0100 Subject: [PATCH 1/5] gh-128307: update docs to TaskGroup.create_task and asyncio.create_task --- Doc/library/asyncio-eventloop.rst | 22 ++++++++++++++++++++-- Doc/library/asyncio-task.rst | 21 +++++++++++++++++---- 2 files changed, 37 insertions(+), 6 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 21f7d0547af1dd..8180f9b0fabf6c 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 ` *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,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. diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 59acce1990ae04..3b3c1b16630cce 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 ` 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. + .. versionchanges:: 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(): From 18b6bb53936d4880262789b58f028a3bab16f180 Mon Sep 17 00:00:00 2001 From: Thomas Grainger Date: Mon, 19 May 2025 09:15:05 +0100 Subject: [PATCH 2/5] Update Doc/library/asyncio-eventloop.rst --- Doc/library/asyncio-eventloop.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 8180f9b0fabf6c..a6964fdad589e6 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -419,6 +419,9 @@ Creating Futures and Tasks .. 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() From 10ac91060c6d3745586e16482fcf8771c8ce8721 Mon Sep 17 00:00:00 2001 From: Thomas Grainger Date: Mon, 19 May 2025 09:15:14 +0100 Subject: [PATCH 3/5] Update Doc/library/asyncio-eventloop.rst --- Doc/library/asyncio-eventloop.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index a6964fdad589e6..5686db1aa0b3ae 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -400,7 +400,7 @@ Creating Futures and Tasks while still passing on other arbitrary keyword arguments (to avoid breaking backwards compatibility with 3.13.3). .. versionchanged:: 3.14 - All kwargs are now passed on. The *eager_start* parameter works with eager task factories. + All *kwargs* are now passed on. The *eager_start* parameter works with eager task factories. .. method:: loop.set_task_factory(factory) From 7d7497699827061ade087f8810e40baa9beb0e9e Mon Sep 17 00:00:00 2001 From: Thomas Grainger Date: Mon, 19 May 2025 22:34:31 +0100 Subject: [PATCH 4/5] Update Doc/library/asyncio-task.rst --- Doc/library/asyncio-task.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 3b3c1b16630cce..b19ffa8213a971 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -296,7 +296,7 @@ Creating Tasks .. versionchanged:: 3.11 Added the *context* parameter. - .. versionchanges:: 3.14 + .. versionchanged:: 3.14 Added the *eager_start* parameter by passing on all *kwargs*. From 712748353fa00397f62af4aa9337503e16e009ec Mon Sep 17 00:00:00 2001 From: Thomas Grainger Date: Tue, 20 May 2025 07:45:07 +0100 Subject: [PATCH 5/5] pre-commit --- Doc/library/asyncio-eventloop.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 5686db1aa0b3ae..91970c282391f7 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -419,7 +419,7 @@ Creating Futures and Tasks .. 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.