[Python-checkins] gh-94972: document that shield users need to keep a reference to their task (GH-96724)

[miss-islington]

https://github.com/python/cpython/commit/335bd1ee8be187b464ef797745d42f9a974bc970
commit: 335bd1ee8be187b464ef797745d42f9a974bc970
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-09-10T08:03:35-07:00
summary:

gh-94972: document that shield users need to keep a reference to their task (GH-96724)


Co-authored-by: Thomas Grainger <tagrain at gmail.com>
Co-authored-by: Guido van Rossum <gvanrossum at gmail.com>
(cherry picked from commit 6281affee6423296893b509cd78dc563ca58b196)

Co-authored-by: Hendrik Makait <hendrik.makait at gmail.com>

files:
M Doc/library/asyncio-future.rst
M Doc/library/asyncio-task.rst
M Lib/asyncio/tasks.py

diff --git a/Doc/library/asyncio-future.rst b/Doc/library/asyncio-future.rst
index f74f2e6f8935..99a5d3a8287b 100644
--- a/Doc/library/asyncio-future.rst
+++ b/Doc/library/asyncio-future.rst
@@ -55,7 +55,7 @@ Future Functions
       preferred way for creating new Tasks.
 
       Save a reference to the result of this function, to avoid
-      a task disappearing mid execution.
+      a task disappearing mid-execution.
 
    .. versionchanged:: 3.5.1
       The function accepts any :term:`awaitable` object.
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index ffbf421bae5e..221197ea40ff 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -254,9 +254,9 @@ Creating Tasks
    .. important::
 
       Save a reference to the result of this function, to avoid
-      a task disappearing mid execution. The event loop only keeps
+      a task disappearing mid-execution. The event loop only keeps
       weak references to tasks. A task that isn't referenced elsewhere
-      may get garbage-collected at any time, even before it's done.
+      may get garbage collected at any time, even before it's done.
       For reliable "fire-and-forget" background tasks, gather them in
       a collection::
 
@@ -520,7 +520,8 @@ Shielding From Cancellation
 
    The statement::
 
-       res = await shield(something())
+       task = asyncio.create_task(something())
+       res = await shield(task)
 
    is equivalent to::
 
@@ -539,11 +540,19 @@ Shielding From Cancellation
    the ``shield()`` function should be combined with a try/except
    clause, as follows::
 
+       task = asyncio.create_task(something())
        try:
-           res = await shield(something())
+           res = await shield(task)
        except CancelledError:
            res = None
 
+   .. important::
+
+      Save a reference to tasks passed to this function, to avoid
+      a task disappearing mid-execution. The event loop only keeps
+      weak references to tasks. A task that isn't referenced elsewhere
+      may get garbage collected at any time, even before it's done.
+
    .. versionchanged:: 3.10
       Removed the *loop* parameter.
 
diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py
index 27fe58da1513..56a355cbdc70 100644
--- a/Lib/asyncio/tasks.py
+++ b/Lib/asyncio/tasks.py
@@ -848,7 +848,8 @@ def shield(arg):
 
     The statement
 
-        res = await shield(something())
+        task = asyncio.create_task(something())
+        res = await shield(task)
 
     is exactly equivalent to the statement
 
@@ -864,10 +865,16 @@ def shield(arg):
     If you want to completely ignore cancellation (not recommended)
     you can combine shield() with a try/except clause, as follows:
 
+        task = asyncio.create_task(something())
         try:
-            res = await shield(something())
+            res = await shield(task)
         except CancelledError:
             res = None
+
+    Save a reference to tasks passed to this function, to avoid
+    a task disappearing mid-execution. The event loop only keeps
+    weak references to tasks. A task that isn't referenced elsewhere
+    may get garbage collected at any time, even before it's done.
     """
     inner = _ensure_future(arg)
     if inner.done():