From 45de0c299bfc8117b04bb47df61a676a5013c4ce Mon Sep 17 00:00:00 2001 From: Andrew Godwin Date: Tue, 3 Dec 2019 10:29:04 +0100 Subject: [PATCH] [3.0.x] Refs #30451 -- Doc'd asynchronous support and async-safety. Backport of 635a3f8e6e0303e8a87586ef6be4ab0cc01d7c0d from master --- docs/index.txt | 3 ++- docs/spelling_wordlist | 2 ++ docs/topics/async.txt | 36 ++++++++++++++++++++++++++++++++++++ docs/topics/index.txt | 1 + 4 files changed, 41 insertions(+), 1 deletion(-) create mode 100644 docs/topics/async.txt diff --git a/docs/index.txt b/docs/index.txt index 64a45c876d..d8ef87f777 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -110,7 +110,8 @@ manipulating the data of your Web application. Learn more about it below: :doc:`Custom lookups ` | :doc:`Query Expressions ` | :doc:`Conditional Expressions ` | - :doc:`Database Functions ` + :doc:`Database Functions ` | + :doc:`Asynchronous Support ` * **Other:** :doc:`Supported databases ` | diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index 43e8a68385..9c56339cc0 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -116,6 +116,7 @@ conf config contenttypes contrib +coroutine coroutines covariance criticals @@ -664,6 +665,7 @@ th that'll Thejaswi This'll +threadpool timeframe timeline timelines diff --git a/docs/topics/async.txt b/docs/topics/async.txt new file mode 100644 index 0000000000..6a6f0030c9 --- /dev/null +++ b/docs/topics/async.txt @@ -0,0 +1,36 @@ +==================== +Asynchronous support +==================== + +.. versionadded:: 3.0 + +Django has developing support for asynchronous ("async") Python, but does not +yet support asynchronous views or middleware; they will be coming in a future +release. + +There is limited support for other parts of the async ecosystem; namely, Django +can natively talk :doc:`ASGI `, and some async +safety support. + +Async-safety +------------ + +Certain key parts of Django are not able to operate safely in an asynchronous +environment, as they have global state that is not coroutine-aware. These parts +of Django are classified as "async-unsafe", and are protected from execution in +an asynchronous environment. The ORM is the main example, but there are other +parts that are also protected in this way. + +If you try to run any of these parts from a thread where there is a *running +event loop*, you will get a +:exc:`~django.core.exceptions.SynchronousOnlyOperation` error. Note that you +don't have to be inside an async function directly to have this error occur. If +you have called a synchronous function directly from an asynchronous function +without going through something like ``sync_to_async`` or a threadpool, then it +can also occur, as your code is still running in an asynchronous context. + +If you encounter this error, you should fix your code to not call the offending +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. diff --git a/docs/topics/index.txt b/docs/topics/index.txt index 55a5fc6af3..ffb9fa9d92 100644 --- a/docs/topics/index.txt +++ b/docs/topics/index.txt @@ -31,3 +31,4 @@ Introductions to all the key parts of Django you'll need to know: signals checks external-packages + async