[3.0.x] Fixed #31056 -- Allowed disabling async-unsafe check with an environment variable.

Backport of c90ab30fa1305481024b9c3c50b5a6ed6cd9a2f5 from master

1 files changed, 20 insertions, 0 deletions

diff --git a/docs/topics/async.txt b/docs/topics/async.txt
index 6a6f0030c9..b341084b1a 100644
--- a/docs/topics/async.txt
+++ b/docs/topics/async.txt
@@ -12,6 +12,8 @@ There is limited support for other parts of the async ecosystem; namely, Django
 can natively talk :doc:`ASGI </howto/deployment/asgi/index>`, and some async
 safety support.
 
+.. _async-safety:
+
 Async-safety
 ------------
 
@@ -34,3 +36,21 @@ code from an async context; instead, write your code that talks to async-unsafe
 in its own, synchronous function, and call that using
 ``asgiref.sync.async_to_sync``, or any other preferred way of running
 synchronous code in its own thread.
+
+If you are *absolutely* in dire need to run this code from an asynchronous
+context - for example, it is being forced on you by an external environment,
+and you are sure there is no chance of it being run concurrently (e.g. you are
+in a Jupyter_ notebook), then you can disable the warning with the
+``DJANGO_ALLOW_ASYNC_UNSAFE`` environment variable.
+
+.. warning::
+
+    If you enable this option and there is concurrent access to the
+    async-unsafe parts of Django, you may suffer data loss or corruption. Be
+    very careful and do not use this in production environments.
+
+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/