Effects on IPython.embed()

IPython core being asynchronous, the use of IPython.embed() will now require a loop to run. By default IPython will use a fake coroutine runner which should allow IPython.embed() to be nested. Though this will prevent usage of the :magic:`%autoawait` feature when using IPython embed.

You can set explicitly a coroutine runner for embed() if you desire to run asynchronous code, the exact behavior is though undefined.

Effects on Magics

A couple of magics (%%timeit, %timeit, %%time, %%prun) have not yet been updated to work with asynchronous code and will raise syntax errors when trying to use top-level await. We welcome any contribution to help fix those, and extra cases we haven't caught yet. We hope for better support in Cor Python for top-level Async code.

Internals

As running asynchronous code is not supported in interactive REPL (as of Python 3.7) we have to rely to a number of complex workaround and heuristic to allow this to happen. It is interesting to understand how this works in order to comprehend potential bugs, or provide a custom runner.

Among the many approaches that are at our disposition, we find only one that suited out need. Under the hood we use the code object from a async-def function and run it in global namespace after modifying it to not create a new locals() scope:

async def inner_async():
    locals().update(**global_namespace)
    #
    # here is user code
    #
    return last_user_statement
codeobj = modify(inner_async.__code__)
coroutine = eval(codeobj, user_ns)
display(loop_runner(coroutine))

The first thing you'll notice is that unlike classical exec, there is only one namespace. Second, user code runs in a function scope, and not a module scope.

On top of the above there are significant modification to the AST of function, and loop_runner can be arbitrary complex. So there is a significant overhead to this kind of code.

By default the generated coroutine function will be consumed by Asyncio's loop_runner = asyncio.get_evenloop().run_until_complete() method if async mode is deemed necessary, otherwise the coroutine will just be exhausted in a simple runner. It is though possible to change the default runner.

A loop runner is a synchronous function responsible from running a coroutine object.

The runner is responsible from ensuring that coroutine run to completion, and should return the result of executing the coroutine. Let's write a runner for trio that print a message when used as an exercise, trio is special as it usually prefer to run a function object and make a coroutine by itself, we can get around this limitation by wrapping it in an async-def without parameters and passing this value to trio:

In [1]: import trio
   ...: from types import CoroutineType
   ...:
   ...: def trio_runner(coro:CoroutineType):
   ...:     print('running asynchronous code')
   ...:     async def corowrap(coro):
   ...:         return await coro
   ...:     return trio.run(corowrap, coro)

We can set it up by passing it to %autoawait:

In [2]: %autoawait trio_runner

In [3]: async def async_hello(name):
   ...:     await trio.sleep(1)
   ...:     print(f'Hello {name} world !')
   ...:     await trio.sleep(1)

In [4]: await async_hello('async')
running asynchronous code
Hello async world !

Asynchronous programming in python (and in particular in the REPL) is still a relatively young subject. We expect some code to not behave as you expect, so feel free to contribute improvements to this codebase and give us feedback.

We invite you to thoroughly test this feature and report any unexpected behavior as well as propose any improvement.

Using Autoawait in a notebook (IPykernel)

Update ipykernel to version 5.0 or greater:

pip install ipykernel ipython --upgrade
# or
conda install ipykernel ipython --upgrade

This should automatically enable :magic:`autoawait` integration. Unlike terminal IPython, all code runs on asyncio eventloop, so creating a loop by hand will not work, including with magics like :magic:`%run` or other frameworks that create the eventloop themselves. In cases like these you can try to use projects like nest_asyncio and follow this discussion

Difference between terminal IPython and IPykernel

The exact asynchronous code running behavior varies between Terminal IPython and IPykernel. The root cause of this behavior is due to IPykernel having a persistent asyncio loop running, while Terminal IPython starts and stops a loop for each code block. This can lead to surprising behavior in some case if you are used to manipulate asyncio loop yourself, see for example :ghissue:`11303` for a longer discussion but here are some of the astonishing cases.

This behavior is an implementation detail, and should not be relied upon. It can change without warnings in future versions of IPython.

In terminal IPython a loop is started for each code blocks only if there is top level async code:

$ ipython
In [1]: import asyncio
   ...: asyncio.get_event_loop()
Out[1]: <_UnixSelectorEventLoop running=False closed=False debug=False>

In [2]:

In [2]: import asyncio
   ...: await asyncio.sleep(0)
   ...: asyncio.get_event_loop()
Out[2]: <_UnixSelectorEventLoop running=True closed=False debug=False>

See that running is True only in the case were we await sleep()

In a Notebook, with ipykernel the asyncio eventloop is always running:

$ jupyter notebook
In [1]: import asyncio
   ...: loop1 = asyncio.get_event_loop()
   ...: loop1
Out[1]: <_UnixSelectorEventLoop running=True closed=False debug=False>

In [2]: loop2 = asyncio.get_event_loop()
   ...: loop2
Out[2]: <_UnixSelectorEventLoop running=True closed=False debug=False>

In [3]: loop1 is loop2
Out[3]: True

In Terminal IPython background tasks are only processed while the foreground task is running, if and only if the foreground task is async:

$ ipython
In [1]: import asyncio
   ...:
   ...: async def repeat(msg, n):
   ...:     for i in range(n):
   ...:         print(f"{msg} {i}")
   ...:         await asyncio.sleep(1)
   ...:     return f"{msg} done"
   ...:
   ...: asyncio.ensure_future(repeat("background", 10))
Out[1]: <Task pending coro=<repeat() running at <ipython-input-1-02d0ef250fe7>:3>>

In [2]: await asyncio.sleep(3)
background 0
background 1
background 2
background 3

In [3]: import time
...: time.sleep(5)

In [4]: await asyncio.sleep(3)
background 4
background 5
background 6g

In a Notebook, QtConsole, or any other frontend using IPykernel, background tasks should behave as expected.