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 Prestanda), 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\nPrestanda). A wide range of async-native Python libraries can\nalso be integrated.
Alla vyer kan förklaras asynkrona genom att den anropbara delen av den returnerar en coroutine - vanligtvis görs detta med hjälp av async def. För en funktionsbaserad vy innebär detta att hela vyn deklareras med async def. För en klassbaserad vy innebär det att HTTP-metodhanterarna, till exempel get() och post(), deklareras som async def (inte dess __init__() eller as_view()).
Under en WSGI-server kommer asynkrona vyer att köras i sin egen engångshändelseslinga. Detta innebär att du kan använda asynkrona funktioner, som samtidiga asynkrona HTTP-förfrågningar, utan problem, men du får inte fördelarna med en asynkron stack.
\nDe främsta fördelarna är möjligheten att hantera hundratals anslutningar utan att använda Python-trådar. Detta gör att du kan använda långsam streaming, long-polling och andra spännande svarstyper.
\nOm du vill använda dessa måste du distribuera Django med hjälp av ASGI istället.
\n\nI både ASGI- och WSGI-läge kan du fortfarande på ett säkert sätt använda asynkront stöd för att köra kod samtidigt i stället för seriellt. Detta är särskilt praktiskt när du hanterar externa API:er eller datalager.
\nOm du vill anropa en del av Django som fortfarande är synkron, måste du linda in den i ett sync_to_async()-anrop. Till exempel:
from asgiref.sync import sync_to_async\n\nresults = await sync_to_async(sync_function, thread_sensitive=True)(pk=123)\nOm du av misstag försöker anropa en del av Django som endast är synkron från en asynkron vy, kommer du att utlösa Djangos asynkrona säkerhetsskydd för att skydda dina data från korruption.
\nFöljande dekoratorer kan användas med både synkrona och asynkrona vyfunktioner:
\nvillkorlig_sida()
xframe_options_deny()
xframe_options_sameorigin()
xframe_options_exempt()
Till exempel:
\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): ...\nWith some exceptions, Django can run ORM queries asynchronously:
\nasync for author in Author.objects.filter(name__startswith="A"):\n book = await author.books.afirst()\nDetaljerade anvisningar finns i Asynkrona förfrågningar, men i korthet:
\nAlla QuerySet-metoder som orsakar en SQL-fråga har en asynkron variant med a-prefix.
async for stöds på alla QuerySets (inklusive utdata från values() och 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)\nTransaktioner fungerar ännu inte i asynkront läge. Om du har en del av koden som behöver transaktionsbeteende rekommenderar vi att du skriver den delen som en enda synkron funktion och anropar den med 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.
\nDu bör göra dina egna prestandatester för att se vilken effekt ASGI kontra WSGI har på din kod. I vissa fall kan det finnas en prestandaförbättring även för en rent synkron kodbas under ASGI eftersom all kod som hanterar förfrågningar fortfarande körs asynkront. I allmänhet vill du bara aktivera ASGI-läget om du har asynkron kod i ditt projekt.
\nFör långlivade förfrågningar kan en klient koppla från innan vyn returnerar ett svar. I detta fall kommer ett asyncio.CancelledError att uppstå i vyn. Du kan fånga detta fel och hantera det om du behöver utföra någon upprensning:
async def my_view(request):\n try:\n # Do some work\n ...\n except asyncio.CancelledError:\n # Handle disconnect\n raise\nDu kan också hantera klientavbrott i strömmande svar.
\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.
\nOm du försöker köra någon av dessa delar från en tråd där det finns en löpande händelseslinga, kommer du att få ett SynchronousOnlyOperation-fel. Observera att du inte behöver vara inne i en async-funktion direkt för att detta fel ska uppstå. Om du har anropat en sync-funktion direkt från en async-funktion, utan att använda sync_to_async() eller liknande, så kan det också inträffa. Detta beror på att din kod fortfarande körs i en tråd med en aktiv händelseslinga, även om den kanske inte är deklarerad som asynkron kod.
Om du stöter på detta fel bör du korrigera din kod så att du inte anropar den felaktiga koden från ett async-sammanhang. Skriv istället din kod som pratar med async-osäkra funktioner i sin egen sync-funktion och anropa den med asgiref.sync.sync_to_async() (eller något annat sätt att köra sync-kod i sin egen tråd).
Async-kontexten kan påtvingas dig av den miljö där du kör din Django-kod. Till exempel tillhandahåller Jupyter-anteckningsböcker och IPython interaktiva skal båda transparent en aktiv händelseslinga så att det är lättare att interagera med asynkrona API: er.
\nOm du använder ett IPython-skal kan du inaktivera den här händelseslingan genom att köra:
\n%autoawait off\nsom ett kommando i IPython-prompten. Detta gör att du kan köra synkron kod utan att generera SynchronousOnlyOperation-fel; men du kommer inte heller att kunna await asynkrona API:er. För att slå på händelseslingan igen, kör:
%autoawait on\nOm du befinner dig i en annan miljö än IPython (eller om du av någon anledning inte kan stänga av autoawait i IPython), du är säker på att det inte finns någon chans att din kod körs samtidigt och du absolut behöver köra din synkroniseringskod från en asynkron kontext, kan du inaktivera varningen genom att ställa in miljövariabeln DJANGO_ALLOW_ASYNC_UNSAFE till valfritt värde.
Om du behöver göra detta från Python, gör det med os.environ:
import os\n\nos.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true"\nDet är nödvändigt att anpassa anropsstilen när man anropar sync-kod från en async-kontext, eller vice versa. För detta finns det två adapterfunktioner från modulen asgiref.sync: async_to_sync`() och sync_to_async`(). De används för att övergå mellan anropsstilarna samtidigt som kompatibiliteten bevaras.
Dessa adapterfunktioner används i stor utsträckning i Django. Själva paketet asgiref är en del av Django-projektet och det installeras automatiskt som ett beroende när du installerar Django med pip.
async_to_sync()Link to this heading#Tar en async-funktion och returnerar en sync-funktion som omsluter den. Kan användas som antingen en direkt omslutning eller en dekorator:
\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(): ...\nAsync-funktionen körs i händelseslingan för den aktuella tråden, om en sådan finns. Om det inte finns någon aktuell händelseslinga startas en ny händelseslinga specifikt för den enskilda async-inkallningen och stängs av igen när den är klar. I båda situationerna kommer async-funktionen att köras i en annan tråd än den anropande koden.
\nVärdena för Threadlocals och contextvars bevaras över gränsen i båda riktningarna.
\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#Tar en sync-funktion och returnerar en async-funktion som omsluter den. Kan användas som antingen en direkt omslutning eller en dekorator:
\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(): ...\nVärdena för Threadlocals och contextvars bevaras över gränsen i båda riktningarna.
\nSynkroniseringsfunktioner brukar skrivas med antagandet att de alla körs i huvudtråden, så sync_to_async() har två trådningslägen:
thread_sensitive=True (standard): Synkroniseringsfunktionen körs i samma tråd som alla andra thread_sensitive funktioner. Detta kommer att vara huvudtråden, om huvudtråden är synkron och du använder async_to_sync()-omslaget.
thread_sensitive=False: Synkroniseringsfunktionen körs i en helt ny tråd som sedan stängs när anropet har slutförts.
Trådkänsligt läge är ganska speciellt och gör en hel del arbete för att köra alla funktioner i samma tråd. Observera dock att det förlitar sig på användning av async_to_sync() över det i stacken för att korrekt köra saker på huvudtråden. Om du använder asyncio.run() eller liknande kommer den att falla tillbaka till att köra trådkänsliga funktioner i en enda, delad tråd, men detta kommer inte att vara huvudtråden.
Anledningen till att detta behövs i Django är att många bibliotek, särskilt databasadaptrar, kräver att de nås i samma tråd som de skapades i. Även en hel del befintlig Django-kod förutsätter att allt körs i samma tråd, t.ex. middleware som lägger till saker i en begäran för senare användning i vyer.
\nI stället för att införa potentiella kompatibilitetsproblem med den här koden valde vi istället att lägga till det här läget så att all befintlig Django sync-kod körs i samma tråd och därmed är helt kompatibel med async-läget. Observera att synkroniseringskoden alltid kommer att vara i en annan tråd än någon asynkron kod som anropar den, så du bör undvika att skicka råa databashandtag eller andra trådkänsliga referenser runt.
\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.
I praktiken innebär denna begränsning att du inte bör skicka egenskaper hos databasens connection-objekt när du anropar sync_to_async(). Om du gör det kommer det att utlösa trådsäkerhetskontrollerna:
# 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.\nIstället bör du kapsla in all databasåtkomst i en hjälpfunktion som kan anropas med sync_to_async() utan att förlita sig på anslutningsobjektet i den anropande koden.