Issue 44665: asyncio.create_task() documentation should mention user needs to keep reference to the task

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!".

I would suggest adding the following paragraph to `create_task()` documentation:

Python only keeps weak references to the scheduled tasks. To avoid the task being destroyed by the garbage collector while still pending, a reference to it should be kept until the task is done.

And maybe an example in case a user wants something "fire and forget"?

```python
running_tasks = set()
# [...]
task = asyncio.create_task(some_background_function())
running_tasks.add(task)
task.add_done_callback(lambda t: running_tasks.remove(t))
```

The same applies to ensure_future as it now uses create_task, so maybe a "See create_task()".

@bernat and ncoghlan, please see if the wording I have used in the linked PR helps to clarify this.

Is there a way to reproduce this issue? I run the following code in Python 3.9 and it works as expected (prints "xyz" twice).

import asyncio
import gc

async def xyz():
    print("xyz")

event_loop = asyncio.get_event_loop()

event_loop.create_task(xyz())

t = event_loop.create_task(xyz())
del t

gc.collect()

event_loop.stop()
event_loop.run_forever()

Hummm, I have a hard time finding a short example when `__del__` is not called until the task is finished. Sorry. I did run into this several time, for example here: https://github.com/ldo/dbussy/pull/45 (and some internal projects as well). So, it happens from time to time, but it is hard to find a simple reproducer.

I just found this PR when a task of mine spontaneously crashed with a "Task was destroyed but it is pending" in the middle of program execution.

I think the warning should be added to `loop.create_task()`, too. Not sure if `loop.call_later()` and `loop.call_at()` are also affected?

I think it would be a good idea to add the fire-and-forget example that @bernat gave. At the moment, stackoverflow is full of suggestions to just use `create_task()` in this case, ignoring the return value. Actually, I think it is a true shortcoming that asyncio doesn't provide a fire-and forget functionality by itself.

pull_requests: + pull_request27437
stage: patch review