Django has support for writing asynchronous (“async”) views, along with an\nentirely async-enabled request stack if you are running under ASGI. Async views will still work under WSGI, but\nwith a small per-request adaptation cost (see Performance), and\nwithout the ability to have efficient long-running requests.
\nMany parts of Django provide asynchronous APIs, including the ORM, the cache framework, authentication, sessions, and signals.\nFor other code, the sync_to_async() adapter is a low-cost bridge (see\nPerformance). A wide range of async-native Python libraries can\nalso be integrated.
Any view can be declared async by making the callable part of it return a\ncoroutine - commonly, this is done using async def. For a function-based\nview, this means declaring the whole view using async def. For a\nclass-based view, this means declaring the HTTP method handlers, such as\nget() and post() as async def (not its __init__(), or\nas_view()).
Under a WSGI server, async views will run in their own, one-off event loop.\nThis means you can use async features, like concurrent async HTTP requests,\nwithout any issues, but you will not get the benefits of an async stack.
\nThe main benefits are the ability to service hundreds of connections without\nusing Python threads. This allows you to use slow streaming, long-polling, and\nother exciting response types.
\nIf you want to use these, you will need to deploy Django using\nASGI instead.
\n\nIn both ASGI and WSGI mode, you can still safely use asynchronous support to\nrun code concurrently rather than serially. This is especially handy when\ndealing with external APIs or data stores.
\nIf you want to call a part of Django that is still synchronous, you will need\nto wrap it in a sync_to_async() call. For example:
from asgiref.sync import sync_to_async\n\nresults = await sync_to_async(sync_function, thread_sensitive=True)(pk=123)\nIf you accidentally try to call a part of Django that is synchronous-only\nfrom an async view, you will trigger Django’s\nasynchronous safety protection to protect your data from\ncorruption.
\nThe following decorators can be used with both synchronous and asynchronous\nview functions:
\nconditional_page()
xframe_options_deny()
xframe_options_sameorigin()
xframe_options_exempt()
For example:
\nfrom django.views.decorators.cache import never_cache\n\n\n@never_cache\ndef my_sync_view(request): ...\n\n\n@never_cache\nasync def my_async_view(request): ...\nmethod_decorator() can be used with asynchronous\nmethods, including async def view handlers. Note, though, that if\ndecorating dispatch() on a View with\nasynchronous handlers, you will need to override dispatch to make it\nasync def as well:
class MyClass(View):\n @method_decorator(never_cache)\n async def dispatch(self, *args, **kwargs):\n return super().dispatch(*args, **kwargs)\n\n async def get(self, request): ...\n\n async def post(self, request): ...\nHere, because we are decorating dispatch, rather than the individual\nhandler methods, we need to make dispatch asynchronous so that\nmethod_decorator can correctly mark the resulting method as a coroutine\nfunction.
With some exceptions, Django can run ORM queries asynchronously:
\nasync for author in Author.objects.filter(name__startswith="A"):\n book = await author.books.afirst()\nDetailed notes can be found in Asynchronous queries, but in short:
\nAll QuerySet methods that cause an SQL query to occur have an\na-prefixed asynchronous variant.
async for is supported on all QuerySets (including the output of\nvalues() and values_list().)
Asynchronous model methods that use the database are also supported:
\nasync def make_book(*args, **kwargs):\n book = Book(...)\n await book.asave(using="secondary")\n\n\nasync def make_book_with_tags(tags, *args, **kwargs):\n book = await Book.objects.acreate(...)\n await book.tags.aset(tags)\nTransactions do not yet work in async mode. If you have a piece of code that\nneeds transactions behavior, we recommend you write that piece as a single\nsynchronous function and call it using sync_to_async().
Persistent database connections, set\nvia the CONN_MAX_AGE setting, should also be disabled in async mode.\nInstead, use your database backend’s built-in connection pooling if available,\nor investigate a third-party connection pooling option if required. As in\nsynchronous Django, concurrent requests in a single process share that pool, so\nsize it to the target in-flight query concurrency.
When running in a mode that does not match the view (e.g. an async view under\nWSGI, or a traditional sync view under ASGI), Django must emulate the other\ncall style to allow your code to run. The per-call cost of this adaptation is\nsmall: tens of microseconds in the in-request ASGI path, where the running\nevent loop is reused, and a few hundred microseconds in the cold-start path\nused by management commands, background tasks, and scripts. Against typical\nrequest times measured in milliseconds, this is rarely visible in itself, but\ncan become so under GIL contention as the number of active threads grows.
\nIf you find yourself wrapping individual rows or operations in a tight loop,\nrestructure your code so the loop runs inside a single sync_to_async()\n(or async_to_sync()) crossing. The per-call cost of the context switch is\nthen spread across the whole loop and effectively disappears.
The same per-call adaptation cost applies to middleware. Django will attempt to\nminimize the number of context-switches between sync and async. If you have an\nASGI server, but all your middleware and views are synchronous, it will switch\njust once, before it enters the middleware stack.
\nHowever, if you put synchronous middleware between an ASGI server and an\nasynchronous view, it will have to switch into sync mode for the middleware and\nthen back to async mode for the view. Django will also hold the sync thread\nopen for middleware exception propagation. For request/response views that hit\nthe ORM and return, this is not usually a meaningful penalty. It matters most\nwhen you are using ASGI for high in-process concurrency over non-ORM I/O (for\nexample upstream HTTP fan-out, server-sent events, or other long-lived\nrequests), where the extra thread per request caps that concurrency.
\nYou should do your own performance testing to see what effect ASGI versus WSGI\nhas on your code. In some cases, there may be a performance increase even for\na purely synchronous codebase under ASGI because the request-handling code is\nstill all running asynchronously. In general you will only want to enable ASGI\nmode if you have asynchronous code in your project.
\nFor long-lived requests, a client may disconnect before the view returns a\nresponse. In this case, an asyncio.CancelledError will be raised in the\nview. You can catch this error and handle it if you need to perform any\ncleanup:
async def my_view(request):\n try:\n # Do some work\n ...\n except asyncio.CancelledError:\n # Handle disconnect\n raise\nYou can also handle client disconnects in streaming responses.
\nCertain key parts of Django are not able to operate safely in an async\nenvironment, as they have global state that is not coroutine-aware. These parts\nof Django are classified as “async-unsafe”, and are protected from execution in\nan async environment. The synchronous API of the ORM is the main example, but\nthere are other parts that are also protected in this way.
\nIf you try to run any of these parts from a thread where there is a running\nevent loop, you will get a\nSynchronousOnlyOperation error. Note that you\ndon’t have to be inside an async function directly to have this error occur. If\nyou have called a sync function directly from an async function,\nwithout using sync_to_async() or similar, then it can also occur. This is\nbecause your code is still running in a thread with an active event loop, even\nthough it may not be declared as async code.
If you encounter this error, you should fix your code to not call the offending\ncode from an async context. Instead, write your code that talks to async-unsafe\nfunctions in its own, sync function, and call that using\nasgiref.sync.sync_to_async() (or any other way of running sync code in\nits own thread).
The async context can be imposed upon you by the environment in which you are\nrunning your Django code. For example, Jupyter notebooks and IPython\ninteractive shells both transparently provide an active event loop so that it\nis easier to interact with asynchronous APIs.
\nIf you’re using an IPython shell, you can disable this event loop by running:
\n%autoawait off\nas a command at the IPython prompt. This will allow you to run synchronous code\nwithout generating SynchronousOnlyOperation\nerrors; however, you also won’t be able to await asynchronous APIs. To turn\nthe event loop back on, run:
%autoawait on\nIf you’re in an environment other than IPython (or you can’t turn off\nautoawait in IPython for some reason), you are certain there is no chance\nof your code being run concurrently, and you absolutely need to run your sync\ncode from an async context, then you can disable the warning by setting the\nDJANGO_ALLOW_ASYNC_UNSAFE environment variable to any value.
If you need to do this from within Python, do that with os.environ:
import os\n\nos.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true"\nIt is necessary to adapt the calling style when calling sync code from an async\ncontext, or vice-versa. For this there are two adapter functions, from the\nasgiref.sync module: async_to_sync() and sync_to_async(). They\nare used to transition between the calling styles while preserving\ncompatibility.
These adapter functions are widely used in Django. The asgiref package\nitself is part of the Django project, and it is automatically installed as a\ndependency when you install Django with pip.
async_to_sync()Link to this heading#Takes an async function and returns a sync function that wraps it. Can be used\nas either a direct wrapper or a decorator:
\nfrom asgiref.sync import async_to_sync\n\n\nasync def get_data(): ...\n\n\nsync_get_data = async_to_sync(get_data)\n\n\n@async_to_sync\nasync def get_other_data(): ...\nThe async function is run in the event loop for the current thread, if one is\npresent. If there is no current event loop, a new event loop is spun up\nspecifically for the single async invocation and shut down again once it\ncompletes. In either situation, the async function will execute on a different\nthread to the calling code.
\nThreadlocals and contextvars values are preserved across the boundary in both\ndirections.
\nasync_to_sync() is essentially a more powerful version of the\nasyncio.run() function in Python’s standard library. As well as ensuring\nthreadlocals work, it also enables the thread_sensitive mode of\nsync_to_async() when that wrapper is used below it. In the cold path\n(no running event loop) it pays the cost of starting a fresh event loop, like\nasyncio.run(); when an event loop is already running (the in-request ASGI\ncase), the running loop is reused and the cost drops accordingly.
sync_to_async()Link to this heading#Takes a sync function and returns an async function that wraps it. Can be used\nas either a direct wrapper or a decorator:
\nfrom asgiref.sync import sync_to_async\n\nasync_function = sync_to_async(sync_function, thread_sensitive=False)\nasync_function = sync_to_async(sensitive_sync_function, thread_sensitive=True)\n\n\n@sync_to_async\ndef sync_function(): ...\nThreadlocals and contextvars values are preserved across the boundary in both\ndirections.
\nSync functions tend to be written assuming they all run in the main\nthread, so sync_to_async() has two threading modes:
thread_sensitive=True (the default): the sync function will run in the\nsame thread as all other thread_sensitive functions. This will be the\nmain thread, if the main thread is synchronous and you are using the\nasync_to_sync() wrapper.
thread_sensitive=False: the sync function will run in a brand new thread\nwhich is then closed once the invocation completes.
Thread-sensitive mode is quite special, and does a lot of work to run all\nfunctions in the same thread. Note, though, that it relies on usage of\nasync_to_sync() above it in the stack to correctly run things on the\nmain thread. If you use asyncio.run() or similar, it will fall back to\nrunning thread-sensitive functions in a single, shared thread, but this will\nnot be the main thread.
The reason this is needed in Django is that many libraries, specifically\ndatabase adapters, require that they are accessed in the same thread that they\nwere created in. Also a lot of existing Django code assumes it all runs in the\nsame thread, e.g. middleware adding things to a request for later use in views.
\nRather than introduce potential compatibility issues with this code, we instead\nopted to add this mode so that all existing Django sync code runs in the same\nthread and thus is fully compatible with async mode. Note that sync code will\nalways be in a different thread to any async code that is calling it, so you\nshould avoid passing raw database handles or other thread-sensitive references\naround.
\nWithin a single request, multiple thread_sensitive calls serialize on that\nrequest’s worker thread, but each request gets its own per-context worker, so\nconcurrent requests do not serialize against each other. This mirrors\nDjango’s connection-per-thread model, and the same constraint applies in other\nasync database libraries, where concurrent queries on a single connection\nserialize on a lock. To support more concurrent requests, increase the\nconnection pool size accordingly rather than disabling thread_sensitive.
In practice this restriction means that you should not pass features of the\ndatabase connection object when calling sync_to_async(). Doing so will\ntrigger the thread safety checks:
# DJANGO_SETTINGS_MODULE=settings.py python -m asyncio\n>>> import asyncio\n>>> from asgiref.sync import sync_to_async\n>>> from django.db import connection\n>>> # In an async context so you cannot use the database directly:\n>>> connection.cursor()\ndjango.core.exceptions.SynchronousOnlyOperation: You cannot call this from\nan async context - use a thread or sync_to_async.\n>>> # Nor can you pass resolved connection attributes across threads:\n>>> await sync_to_async(connection.cursor)()\ndjango.db.utils.DatabaseError: DatabaseWrapper objects created in a thread\ncan only be used in that same thread. The object with alias 'default' was\ncreated in thread id 4371465600 and this is thread id 6131478528.\nRather, you should encapsulate all database access within a helper function\nthat can be called with sync_to_async() without relying on the connection\nobject in the calling code.