[New-bugs-announce] [issue21365] asyncio.Task reference misses the most important fact about it, related info spread around intros and example commentary instead

[Paul Sokolovsky]

New submission from Paul Sokolovsky:

It caused me a big surprise that asyncio.Task object automatically schedules itself in the main loop for execution upon creation (i.e. in constructor).

Nowhere in the main reference part of section "18.5.2.4. Task" (https://docs.python.org/3.5/library/asyncio-task.html#task) does it mention that fact. Vice versa, it explicitly says that Task is merely "A coroutine object wrapped in a Future.", which surely sets grounds for surprise when finding that Task is not just coroutine wrapped in Future, but exhibits extra behavior unexpected of plain Future.

Docs cursorily mention this property of Task outside main reference section for it. Specifically:

1) "18.5.2.1. Coroutines", end of intro section:

"In the case of a coroutine object, there are two basic ways to start it running: call yield from coroutine from another coroutine (assuming the other coroutine is already running!), or convert it to a Task."

I would argue that this is way too cursorily and doesn't put strong enough emphasis on the property of self-scheduling, to catch attention of novice or casual reader. For example, my entailments after reading the passage above are: "... or convert it to a Task, to schedule it in a loop [explicitly], because a coroutine can't be scheduled in a loop directly, but Task can be".

2) Very end of subsection "18.5.2.4.1. Example: Parallel execution of tasks", a short line squeezed between colored example block and new section heading - a place where some user will miss it outright: "A task is automatically scheduled for execution when it is created."



Based on case study above, I would like to propose:

1). In section "18.5.2.4. Task", in class description, make unmissable fact that instantiating an object makes it scheduled. For example, append after: "A coroutine object wrapped in a Future. Subclass of Future." following: "Instantiating object of this class automatically schedules it to be run in an event loop specified by 'loop' parameter (or default event loop)."

2) Ideally, update 2 excerpts above to convey more explicit information, and be more visible (for case 2, for example, move it before the example, not after).

----------
assignee: docs at python
components: Documentation
messages: 217272
nosy: docs at python, pfalcon
priority: normal
severity: normal
status: open
title: asyncio.Task reference misses the most important fact about it, related info spread around intros and example commentary instead
type: enhancement
versions: Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue21365>
_______________________________________