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 Penampilan), 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\nPenampilan). A wide range of async-native Python libraries can\nalso be integrated.
Tampilan apapun dapat menyatakan sinkron dengan membuat bagian nya dapat dipanggil mengembalikan coroutine - umumnya, ini dilakukan dengan menggunakan async def. Untuk tampilan berdasarkan-fungsi, ini berarti menyatakan keseluruhan tampilan menggunakan async def. Untuk tampilan berdasarkan-kelas, ini berarti menyatakan penangan metode HTTP, seperti get() dan post() sama async def (bukan itu __init__(), atau as_view()).
Dibawah peladen WSGI , tampilan asinkron akan berjalan sendiri, mutar satu kali acara. Ini berarti anda dapat menggunakan fitur asinkron, seperti permintaan asinkron HTTP bersamaan, tanpa masalah apapun, tetapi anda tidak akan mendapatkan keuntungan dari tumpukan tugas asinkron.
\nKeuntungan utama adalah kemampuan melayani ratusan hubungan tanpa menggunakan rangkaian Python. Ini mengijinkan anda menggunakan aliran pelan, jajak pendapat panjang, dan jenis tanggapan seru lainnya.
\nJika anda ingin menggunakan ini, anda akan butuh mengembangkan Django menggunakan ASGI instead.
\n\nDalam suasana ASGI dan WSGI, anda masih dapat dengan aman menggunakan dukungan asinkron untuk menjalankan kode secara bersamaan daripada berurutan. Ini sangat berguna ketika berhubungan dengan API luar atau penyimpanan data.
\nJika anda ingin memanggil bagian dari Django yang masih sinkronis, anda butuh membungkusnya dalam panggilan sync_to_async(). Sebagai contoh:
from asgiref.sync import sync_to_async\n\nresults = await sync_to_async(sync_function, thread_sensitive=True)(pk=123)\nJika anda secara tidak sengaja mencoba memanggil bagian dari Django yaitu hanya-sinkron dari tampilan asinkron, anda akan membangkitkan asynchronous safety protection Django untuk melindungi data anda dari kerusakan.
\nDecorator berikut dapat digunakan dengan fungsi tampilan sinkron dan asinkron:
\nconditional_page()
xframe_options_deny()
xframe_options_sameorigin()
xframe_options_exempt()
Sebagai contoh:
\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()\nRincian catatan dapat ditemukan dakam Asynchronous queries, tapi singkatnya:
\nSemua metode QuerySet yang dapat menyebabkan sebuah permintaan SQL untuk muncul memiliki asinkron a-prefixed berbeda.
async for didukung pada semua QuerySets (termasuk keluaran values() dan 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)\nTransaksi belum berjalan di suasana asinkron. Jika anda memiliki potongan kode yang butuh perilaku transaksi, kami menganjurkan anda menulis potongan sebagai fungsi sinkron tunggal dan memanggil dia menggunakan 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.
\nAnda harus melakukan pengujian penampilan sendiri untuk melihat pengaruh apa ASGI melawan WSGI miliki pada kode anda. Di beberapa kasus, ada kemungkinan penampilan meningkat bahkan untuk basis kode yang murni sinkron dibawah ASGI karena semua kode penangan-permintaan masih berjalan asinkron. Secara umum anda hanya ingin mengadakan suasana ASGI jika anda memiliki kode asinkron di proyek anda.
\nUntuk permintaan berumur-panjang, klien mungkin memutuskan sebelum tampilan mengembalikan tanggapan. Di kasus ini, asyncio.CancelledError akan dimunculkan dalam tampilan. Anda dapat menangkap kesalahan ini dan menangani itu jika anda butuh melakukan pembersihan:
async def my_view(request):\n try:\n # Do some work\n ...\n except asyncio.CancelledError:\n # Handle disconnect\n raise\nAnda dapat juga 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.
\nJika anda mencoba menjalankan apapun dari bagian ini dari antrian dimana ada running event loop, anda akan mendapatkan kesalahan SynchronousOnlyOperation. Catat bahwa anda tidak harus di dalam fungsi asinkron secara langsung untuk memunculkan kesalahan ini. Jika anda telah memanggil fungsi sinkron secara langsung dari fungsi asinkron, tanpa menggunakan sync_to_async() atau semacamnya, kemudian itu dapat juga muncul. Ini karena kode anda masih berjalan dalam urutan dengan putaran kegiatan aktif, meskipun itu mungkin tidak di nyatakan sebagai kode asinkron.
Jika anda mengalami kesalahan ini, anda harus memperbaiki kode anda untuk tidak memanggil kode menyinggung dari konteks asinkron. Sebaiknya, tulis kode anda yang berbicara ke fungsi tidak-aman-asinkron sendiri, fungsi sinkron, dan memanggil itu menggunakan asgiref.sync.sync_to_async() (atau cara lain apapun dari menjalankan kode sinkron di antrian sendiri).
Konteks asinkron dapat dibebankan kepada anda dengan lingkungan dimana anda menjalankan kode Django anda. Sebagai contoh, buku catatan Jupyter dan cangkang interaktif IPython keduanya secara terbuka menyediakan putaran kegiatan aktif sehingga lebih mudah berinteraksi dengan API asinkron.
\nJika anda menggunakan cangkang IPython, anda dapat meniadakan putaran kegiatan ini dengan menjalankan:
\n%autoawait off\nsebagai sebuah perintah pada prompt IPython. Ini akan mengizinkan anda menjalankan kode sinkron tanpa membangkitkan kesalahan SynchronousOnlyOperation; bagaimanapun, anda juga tidak dapat untuk await API asinkron. Untuk menyalakan putaran kegiatan kembali, jalankan:
%autoawait on\nJika anda berada di lingkungan selain IPython (atau anda tidak dapat mematikan autoawait di IPython untuk beberapa alasan), anda certain tidak ada kemungkinan kode anda dijalankan secara bersamaan, dan anda absolutely butuh menjalankan kode sinkron dari konteks asinkron, kemudian anda dapat meniadakan peringatan dengan menyetel variabel lingkungan DJANGO_ALLOW_ASYNC_UNSAFE ke nilai apapun.
Jika anda buth melakukan ini dari dalam Python, lakukan dengan os.environ:
import os\n\nos.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true"\nPenting untuk menyesuaikan gaya panggilan saat menelepon kode sinron dari konteks asinkron, atau sebaliknya. Untuk ini ada dua fungsi adaptor, dari modul asgiref.sync: async_to_sync() dan sync_to_async(). Mereka digunakan untuk transisi antara gaya panggilan sambil menjaga kompatibilitas.
Fungsi adaptor ini banyak digunakan di Django. Paket asgiref itu sendiri adalah bagian dari proyek Django, dan itu dipasang secara otomatis sebagai ketergantungan saat anda memasang Django dengan pip.
async_to_sync()Link to this heading#Mengambil fungsi asinkron dan mengembalikan fungsi sinkronisasi yang membungkusnya. Dapat digunakan sebagai pembungkus langsung atau 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(): ...\nFungsi asinkron dijalankan di putaran kegiatan untuk antrian saat ini, jika ada. Jika tidak ada putaran kegiatan saat ini, putaran kegiatan baru akan diputar secara khusus untuk pemanggilan asinkron tunggal dan dimatikan lagi setelah selesai. Dalam situasi apa pun, fungsi asinkron akan dijalankan pada antrian yang berbeda dengan kode panggilan.
\nNilai threadlocal dan contextvar dipertahankan melintasi batas di kedua arah.
\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#Mengambil fungsi sinkronisasi dan mengembalikan fungsi asinkron yang membungkusnya. Dapat digunakan sebagai pembungkus langsung atau 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(): ...\nNilai threadlocal dan contextvar dipertahankan melintasi batas di kedua arah.
\nFungsi sinkronisasi cenderung ditulis dengan asumsi semuanya berjalan di antrian utama, jadi sync_to_async() memiliki dua mode antrian:
thread_sensitive=True (awalan): fungsi sinkronisasi akan berjalan di antrian yang sama dengan semua fungsi thread_sensitive lainnya. Ini akan menjadi antrian utama, jika antrian utama sinkron dan anda menggunakan pembungkus async_to_sync().
thread_sensitive=False: fungsi sinkronisasi akan berjalan di antrian baru yang kemudian ditutup setelah pemanggilan selesai.
Suasana peka utas cukup istimewa, dan melakukan banyak pekerjaan untuk menjalankan semua fungsi di antrian yang sama. Perhatikan, bahwa itu bergantung pada penggunaan async_to_sync() di atasnya dalam tumpukan untuk menjalankan berbagai hal dengan benar di antrian utama. Jika Anda menggunakan asyncio.run() atau yang serupa, fungsi ini akan kembali menjalankan fungsi antrian-sensitif dalam satu antrian bersama, tetapi ini tidak akan menjadi antrian utama.
Alasan ini diperlukan di Django adalah bahwa banyak perpustakaan, khususnya adaptor berdasarkan data, mengharuskan mereka diakses di antrian yang sama dengan tempat mereka dibuat. Juga banyak kode Django yang ada menganggap semuanya berjalan di antrian yang sama, mis. middleware menambahkan sesuatu ke permintaan untuk digunakan nanti dalam tampilan.
\nDaripada memperkenalkan potensi masalah kompatibilitas dengan kode ini, kami memilih untuk menambahkan suasana ini sehingga semua kode sinkronisasi Django yang ada berjalan di antrian yang sama dan dengan demikian sepenuhnya kompatibel dengan suasana asinkron. Perhatikan bahwa kode sinkronisasi akan selalu berada dalam antrian berbeda dengan kode asinkron apa pun yang memanggilnya, jadi Anda harus menghindari meneruskan pegangan database mentah atau acuan sensitif antrian lainnya.
\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.
Dalam praktiknya, pembatasan ini berarti bahwa anda tidak boleh melewatkan fitur objek connection basisdata saat memanggil sync_to_async(). Melakukannya akan memicu antrian pemeriksaan keamanan:
# 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.\nSebaliknya, Anda harus mengenkapsulasi semua akses database dalam fungsi pembantu yang dapat dipanggil dengan sync_to_async() tanpa bergantung pada objek koneksi dalam suasana panggilan.