I know that the "18.5.3. Tasks and coroutines" section of the documentation is probably the worst section :-( Feel free to suggest changes with a patch!

I started to enhance the documentation of the Task class, but there is still a lot of work to enhance the whole section.


> "We then see an example that appears to include scheduling a future via asyncio.async, because there is a specific mention of how we can attach a callback after it is scheduled but before the event loop is started."

I guess that you are talking about this example?
https://docs.python.org/dev/library/asyncio-task.html#example-future-with-run-until-complete

You cannot "schedule" a Future object. A Future object doesn't contain code. It only schedules callbacks when set_result() or set_exception() is called.

In this example, a call to the slow_operation coroutine function is scheduled: "slow_operation(future)" creates a coroutine object which is wrapped into a Task object. A coroutine is disconnected from the event loop. The role of the task is to schedule the execution of a coroutine object.

It becomes more complex when you know that the Task class inherits from the Future class :-/


> "I see that a Future is scheduled by its creation"

Again, this is wrong. You cannot "schedule a future". You can schedule a coroutine object by creating a task wrapping it.


> As a followon point, the gloss on example of parallel execution of tasks says "A task is automatically scheduled for execution when it is created.  The event loop stops when all tasks are done."  This reads very strangely to me.  The first sentence seems to be pointing out the difference between this example and the previous one with Future where we had to explicitly schedule it (by calling async which creates a task...).  But it seems that that isn't true...so why is that sentence there? The second sentence presumably refers to the fact that run_until_complete runs the event loop until all scheduled tasks are complete..because they are wrapped in 'wait'.  But wait is not cross referenced or mentioned in the gloss, so I had to think about it carefully and look up wait to conclude that that was what it meant.

Hum, I summarized too many information in "The event loop stops when all tasks are done." In fact, the example stops when run_until_complete() finished its job.