bpo-34270: Make it possible to name asyncio tasks (GH-8547)

Co-authored-by: Antti Haapala <antti.haapala@anttipatterns.com>

3 files changed, 47 insertions, 4 deletions

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 5b3d29d..1006853 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -246,7 +246,7 @@ Futures
 Tasks
 -----
 
-.. method:: AbstractEventLoop.create_task(coro)
+.. method:: AbstractEventLoop.create_task(coro, \*, name=None)
 
    Schedule the execution of a :ref:`coroutine object <coroutine>`: wrap it in
    a future. Return a :class:`Task` object.
@@ -255,8 +255,14 @@ Tasks
    interoperability. In this case, the result type is a subclass of
    :class:`Task`.
 
+   If the *name* argument is provided and not ``None``, it is set as the name
+   of the task using :meth:`Task.set_name`.
+
    .. versionadded:: 3.4.2
 
+   .. versionchanged:: 3.8
+      Added the ``name`` parameter.
+
 .. method:: AbstractEventLoop.set_task_factory(factory)
 
    Set a task factory that will be used by
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 2b480d4..c73f36b 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -387,10 +387,13 @@ with the result.
 Task
 ----
 
-.. function:: create_task(coro)
+.. function:: create_task(coro, \*, name=None)
 
    Wrap a :ref:`coroutine <coroutine>` *coro* into a task and schedule
-   its execution.  Return the task object.
+   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 task is executed in :func:`get_running_loop` context,
    :exc:`RuntimeError` is raised if there is no running loop in
@@ -398,7 +401,10 @@ Task
 
    .. versionadded:: 3.7
 
-.. class:: Task(coro, \*, loop=None)
+   .. versionchanged:: 3.8
+      Added the ``name`` parameter.
+
+.. class:: Task(coro, \*, loop=None, name=None)
 
    A unit for concurrent running of :ref:`coroutines <coroutine>`,
    subclass of :class:`Future`.
@@ -438,6 +444,9 @@ Task
    .. versionchanged:: 3.7
       Added support for the :mod:`contextvars` module.
 
+   .. versionchanged:: 3.8
+      Added the ``name`` parameter.
+
    .. classmethod:: all_tasks(loop=None)
 
       Return a set of all tasks for an event loop.
@@ -504,6 +513,27 @@ Task
       get_stack().  The file argument is an I/O stream to which the output
       is written; by default output is written to sys.stderr.
 
+   .. method:: get_name()
+
+      Return the name of the task.
+
+      If no name has been explicitly assigned to the task, the default
+      ``Task`` implementation generates a default name during instantiation.
+
+      .. versionadded:: 3.8
+
+   .. method:: set_name(value)
+
+      Set the name of the task.
+
+      The *value* argument can be any object, which is then converted to a
+      string.
+
+      In the default ``Task`` implementation, the name will be visible in the
+      :func:`repr` output of a task object.
+
+      .. versionadded:: 3.8
+
 
 Example: Parallel execution of tasks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index bab1e06..6e0c8b8 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -249,6 +249,13 @@ Changes in the Python API
 * ``PyGC_Head`` struct is changed completely.  All code touched the
   struct member should be rewritten.  (See :issue:`33597`)
 
+* Asyncio tasks can now be named, either by passing the ``name`` keyword
+  argument to :func:`asyncio.create_task` or
+  the :meth:`~asyncio.AbstractEventLoop.create_task` event loop method, or by
+  calling the :meth:`~asyncio.Task.set_name` method on the task object. The
+  task name is visible in the ``repr()`` output of :class:`asyncio.Task` and
+  can also be retrieved using the :meth:`~asyncio.Task.get_name` method.
+
 
 CPython bytecode changes
 ------------------------