From 4f0a034b9e42048b782f5265344e026902bd3e95 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Tue, 22 Jun 2021 16:23:03 +0800 Subject: [PATCH] Added a note about %autoawait off for IPython. --- docs/topics/async.txt | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/docs/topics/async.txt b/docs/topics/async.txt index a79562e0f4..1cc5a7c15c 100644 --- a/docs/topics/async.txt +++ b/docs/topics/async.txt @@ -136,11 +136,26 @@ functions in its own, sync function, and call that using :func:`asgiref.sync.sync_to_async` (or any other way of running sync code in its own thread). -You may still be forced to run sync code from an async context. For example, -if the requirement is forced on you by an external environment, such as in a -Jupyter_ notebook. If you are sure there is no chance of the code being run -concurrently, and you *absolutely* need to run this sync code from an async -context, then you can disable the warning by setting the +The async context can be imposed upon you by the environment in which you are +running your Django code. For example, Jupyter_ notebooks and IPython_ +interactive shells both transparently provide an active event loop so that it is +easier to interact with asynchronous APIs. + +If you're using an IPython shell, you can disable this event loop by running:: + + %autoawait off + +as a command at the IPython prompt. This will allow you to run synchronous code +without generating :exc:`~django.core.exceptions.SynchronousOnlyOperation` +errors; however, you also won't be able to ``await`` asynchronous APIs. To turn +the event loop back on, run:: + + %autoawait on + +If you're in an environment other than IPython (or you can't turn off +``autoawait`` in IPython for some reason), you are *certain* there is no chance +of your code being run concurrently, and you *absolutely* need to run your sync +code from an async context, then you can disable the warning by setting the :envvar:`DJANGO_ALLOW_ASYNC_UNSAFE` environment variable to any value. .. warning:: @@ -156,6 +171,7 @@ If you need to do this from within Python, do that with ``os.environ``:: os.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true" .. _Jupyter: https://jupyter.org/ +.. _IPython: https://ipython.org Async adapter functions =======================