Why do most asyncio examples use loop.run_until_complete()?

I was going through the Python documentation for asyncio and I'm wondering why most examples use loop.run_until_complete() as opposed to Asyncio.ensure_future().

For example: https://docs.python.org/dev/library/asyncio-task.html

It seems ensure_future would be a much better way to demonstrate the advantages of non-blocking functions. run_until_complete on the other hand, blocks the loop like synchronous functions do.

This makes me feel like I should be using run_until_complete instead of a combination of ensure_futurewith loop.run_forever() to run multiple co-routines concurrently.

Solution

run_until_complete is used to run a future until it's finished. It will block the execution of code following it. It does, however, cause the event loop to run. Any futures that have been scheduled will run until the future passed to run_until_complete is done.

Given this example:

import asyncio

async def do_io():
    print('io start')
    await asyncio.sleep(5)
    print('io end')

async def do_other_things():
    print('doing other things')

loop = asyncio.get_event_loop()

loop.run_until_complete(do_io())
loop.run_until_complete(do_other_things())

loop.close()

do_io will run. After it's complete, do_other_things will run. Your output will be:

io start
io end
doing other things

If you schedule do_other_things with the event loop before running do_io, control will switch from do_io to do_other_things when the former awaits.

loop.create_task(do_other_things())
loop.run_until_complete(do_io())

This will get you the output of:

doing other things
io start
io end

This is because do_other_things was scheduled before do_io. There are a lot of different ways to get the same output, but which one makes sense really depends on what your application actually does. So I'll leave that as an exercise to the reader.