STINNER Victor added the comment: 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. ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue22476> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
