shield() documentation should mention user needs to keep reference to the task

[graingert]

Documentation

asyncio will only keep weak references to alive tasks (in _all_tasks). If a user does not keep a reference to a task and the task is not currently executing or sleeping, the user may get "Task was destroyed but it is pending!".

see also #88831

shield has the same issue and the documentation currently recommends the incorrect usage

[kumaraditya303]

Can you provide reproducible code where this happens?

[graingert]

See also #93297

[graingert]

@kumaraditya303 here's the repro on python3.10:

import weakref
import asyncio
import gc

import logging


logger = logging.getLogger(__name__)


async def async_fn():
    try:
        await asyncio.get_running_loop().create_future()
    except BaseException:
        logger.exception("closed!")
        raise


async def amain():
    weak_task = weakref.ref(asyncio.create_task(async_fn()))
    await asyncio.sleep(0.01)
    gc.collect()
    print(weak_task())


async def sheild_gc():
    strong_shielded_fut = asyncio.shield(async_fn())
    await asyncio.sleep(0)
    asyncio.current_task().cancel()
    try:
        await strong_shielded_fut
    except asyncio.CancelledError:
        pass

    gc.collect()


asyncio.run(amain())
print("======================")
asyncio.run(sheild_gc())

output:

closed!
Traceback (most recent call last):
  File "/home/graingert/projects/foo.py", line 14, in async_fn
    await asyncio.get_running_loop().create_future()
GeneratorExit
Task was destroyed but it is pending!
task: <Task pending name='Task-2' coro=<async_fn() done, defined at /home/graingert/projects/foo.py:12> wait_for=<Future pending cb=[Task.task_wakeup()]>>
None
======================
closed!
Traceback (most recent call last):
  File "/home/graingert/projects/foo.py", line 14, in async_fn
    await asyncio.get_running_loop().create_future()
GeneratorExit
Task was destroyed but it is pending!
task: <Task pending name='Task-6' coro=<async_fn() done, defined at /home/graingert/projects/foo.py:12> wait_for=<Future pending cb=[Task.task_wakeup()]>>

[gvanrossum]

Are you too busy to submit a PR that updates the docs?

[graingert]

There's one linked here #94973

[gvanrossum]

I think I get the same output on 3.11. Question, is import objgraph needed in the repro? (I had to delete it, no idea what it is.)

[graingert]

I think I get the same output on 3.11. Question, is import objgraph needed in the repro? (I had to delete it, no idea what it is.)

Left in by accident. It's not needed to cause the error but I used it to help build it