Django telah mendukung untuk penulisan tampilan asinkron ("async"), bersama dengan tumpukan permintaan yang sepenuhnya diaktifkan asinkron jika anda berjalan dibawah ASGI. Tampilan asinkron akan masih dapat bekerja dibawah WSGI, tetapi dengandengan hukuman kinerja, dan tanpa kemampuan untuk memiliki permintaan berjalan lama yang efisien.
\nKami masih bekerja pada dukungan asinkron untuk ORM dan bagian lain Django. Anda dapat berharap untuk melihat ini dalam terbitan selanjutnya. Untuk sekarang, anda dapat menggunakan penyadur sync_to_async() untuk berinteraksi dengan bagian sinkron Django. Ada juga keseluruhan jangkauan dari pustaka asinkron-asli Python yang anda dapat gabungkan.
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): ...\nDengan beberapa pengecualian, Django dapat menjalankan permintaan ORM asinkron juga:
\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().)
Django juga mendukung beberapa metode model asinkron yang menggunakan basisdata:
\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.
Saat dijalankan dalam suasana yang tidak sesuai dengan tampilan (misalnya tampilan asinkron dibawah WSGI, atau tampilan sinkron tradisional dibwah ASGI), Django harus ditiru gaya panggilan lain mengizinkan kode anda berjalan. Peralihan konteks ini menyebabkan sedikit hukuman penampilan sekitar millidetik.
\nIni juga benar dari middleware. Django akan berusaha meminimalkan sejumlah jumlah konteks-beralih diantara sinkron dan asinkron. JIka anda memiliki peladen ASGI, tetapi semua middleware anda dan tampilan adalah sinkron, itu akan beralih sekali saja, sebelum dia memasuki tumpukan middleware.
\nBagaimanapun, jika anda menaruh middleware sinkron diantara peladen ASGI tampilan asinkron, dia harus berganti ke suasana sinkron untuk middleware dan kembali ke suasana asnkron untuk tampilan. Django juga akan menahan urutan sinkron membuka pengecualian middleware eksepsi perambatan. Ini mungkin tidak terlihat pertamanya, tetapi menambahkan hukuman ini dari satu urutan per permintaan dapat memindahkan keuntungan penampilan asinkron apapun.
\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.
\nBagian tertentu dari Django tidak dapat beroperasi dengan aman dalam lingkungan asinkron, karena mereka memiliki keadaan global yaitu tidak tidak mengetahui coroutine. Bagian dari Django ini dikelompokkan sebagai "async-unsafe", dan dilindungi dari dijalankan dalam lingkungan asinkron. ORM adalah contoh utama, tetapi ada bagian lain yang dilindungi dengan cara ini.
\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() pada dasarnya adalah versi yang lebih kuat dari fungsi asyncio.run() di pustaka standar Python. Selain memastikan threadlocal berfungsi, ini juga mengaktifkan suasana thread_sensitive dari sync_to_async() saat pembungkus tersebut digunakan di bawahnya.
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.
\nDalam 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.