# Dokumentasi Django 5.2.8

# Dukungan asinkronus

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.

Kami 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 asinkron

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()`).

Catatan

Django menggunakan `asgiref.sync.iscoroutinefunction` untuk menguji jika tampilan anda asinkron atau tidak. Jika anda menerapkan metode sendiri dari mengembalikan coroutine, pastikan anda menggunakan `asgiref.sync.markcoroutinefunction` sehingga fungsi ini mengembalikan `True`.

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.

Keuntungan utama adalah kemampuan melayani ratusan hubungan tanpa menggunakan rangkaian Python. Ini mengijinkan anda menggunakan aliran pelan, jajak pendapat panjang, dan jenis tanggapan seru lainnya.

Jika anda ingin menggunakan ini, anda akan butuh mengembangkan Django menggunakan ASGI instead.

Peringatan

Anda hanya akan mendapatkan keuntungan dari tumpukan permintaan asinkron-sepenuhnya jika anda memiliki middleware tidak sinkron dimuat ke situs anda. Jika ada potongan dari middleware sinkron, kemudian Django harus menggunakan urutan per permintaan untuk ditiru dengan aman lingkungan sinkron untuknya.

Middleware dapat dibangun untuk mendukung konteks both sync dan async. Beberapa middleware Django dibangun seperti ini, tetapi tidak semua. Untuk melihat middleware Django apa harus beradaptasi, anda dapat menyalakan pencatatan pencari kesalahan untuk pencatat `django.request` dan mencari pesan catatan tentang "Asynchronous handler adapted for middleware ...".

Dalam 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.

Jika 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

    results = await sync_to_async(sync_function, thread_sensitive=True)(pk=123)

Jika 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.

### Decorator

Decorator berikut dapat digunakan dengan fungsi tampilan sinkron dan asinkron:

- `cache_control()`

- `never_cache()`

- `no_append_slash()`

- `csp_override()`

- `csp_report_only_override()`

- `csrf_exempt()`

- `csrf_protect()`

- `ensure_csrf_cookie()`

- `requires_csrf_token()`

- `sensitive_variables()`

- `sensitive_post_parameters()`

- `gzip_page()`

- `condition()`

- `conditional_page()`

- `etag()`

- `last_modified()`

- `require_http_methods()`

- `require_GET()`

- `require_POST()`

- `require_safe()`

- `vary_on_cookie()`

- `vary_on_headers()`

- `xframe_options_deny()`

- `xframe_options_sameorigin()`

- `xframe_options_exempt()`

Sebagai contoh:

    from django.views.decorators.cache import never_cache

    @never_cache
    def my_sync_view(request): ...

    @never_cache
    async def my_async_view(request): ...

### Permintaan & ORM

Dengan beberapa pengecualian, Django dapat menjalankan permintaan ORM asinkron juga:

    async for author in Author.objects.filter(name__startswith="A"):
        book = await author.books.afirst()

Rincian catatan dapat ditemukan dakam Asynchronous queries, tapi singkatnya:

- Semua 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:

    async def make_book(*args, **kwargs):
        book = Book(...)
        await book.asave(using="secondary")

    async def make_book_with_tags(tags, *args, **kwargs):
        book = await Book.objects.acreate(...)
        await book.tags.aset(tags)

Transaksi 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 via the `CONN_MAX_AGE` setting, should also be disabled in async mode. Instead, use your database backend's built-in connection pooling if available, or investigate a third-party connection pooling option if required.

### Penampilan

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.

Ini 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.

Bagaimanapun, 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.

Anda 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.

### Handling disconnects

Untuk 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):
        try:
            # Do some work
            ...
        except asyncio.CancelledError:
            # Handle disconnect
            raise

Anda dapat juga handle client disconnects in streaming responses.

## Keamanan asinkronus

DJANGO_ALLOW_ASYNC_UNSAFE

Bagian 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.

Jika 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.

Jika anda menggunakan cangkang IPython, anda dapat meniadakan putaran kegiatan ini dengan menjalankan:

    %autoawait off

sebagai 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

Jika 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.

Peringatan

Jika Anda mengaktifkan pilihan ini dan ada akses bersamaan ke bagian asinkron-tidak aman dari Django, anda mungkin mengalami kehilangan atau kerusakan data. Berhati-hatilah dan jangan gunakan ini di lingkungan produksi.

Jika anda buth melakukan ini dari dalam Python, lakukan dengan `os.environ`:

    import os

    os.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true"

## fungsi adaptasi asingkronus

Penting 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()`

async_to_sync(async_function, force_new_loop=False)

Mengambil fungsi asinkron dan mengembalikan fungsi sinkronisasi yang membungkusnya. Dapat digunakan sebagai pembungkus langsung atau dekorator

    from asgiref.sync import async_to_sync

    async def get_data(): ...

    sync_get_data = async_to_sync(get_data)

    @async_to_sync
    async def get_other_data(): ...

Fungsi 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.

Nilai threadlocal dan contextvar dipertahankan melintasi batas di kedua arah.

`async_to_sync()` is essentially a more powerful version of the `asyncio.run()` function in Python's standard library. As well as ensuring threadlocals work, it also enables the `thread_sensitive` mode of `sync_to_async()` when that wrapper is used below it.

### `sync_to_async()`

sync_to_async(sync_function, thread_sensitive=True)

Mengambil fungsi sinkronisasi dan mengembalikan fungsi asinkron yang membungkusnya. Dapat digunakan sebagai pembungkus langsung atau dekorator

    from asgiref.sync import sync_to_async

    async_function = sync_to_async(sync_function, thread_sensitive=False)
    async_function = sync_to_async(sensitive_sync_function, thread_sensitive=True)

    @sync_to_async
    def sync_function(): ...

Nilai threadlocal dan contextvar dipertahankan melintasi batas di kedua arah.

Fungsi 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.

Peringatan

`asgiref` versi 3.3.0 mengubah nilai awalan parameter `thread_sensitive` menjadi `True`. Ini adalah standar yang lebih aman, dan dalam banyak kasus berinteraksi dengan Django nilai yang benar, tapi pastikan untuk mengevaluasi penggunaan `sync_to_async()` jika memperbarui `asgiref` dari versi sebelumnya.

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.

Daripada 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.

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
    >>> import asyncio
    >>> from asgiref.sync import sync_to_async
    >>> from django.db import connection
    >>> # In an async context so you cannot use the database directly:
    >>> connection.cursor()
    django.core.exceptions.SynchronousOnlyOperation: You cannot call this from
    an async context - use a thread or sync_to_async.
    >>> # Nor can you pass resolved connection attributes across threads:
    >>> await sync_to_async(connection.cursor)()
    django.db.utils.DatabaseError: DatabaseWrapper objects created in a thread
    can only be used in that same thread. The object with alias 'default' was
    created in thread id 4371465600 and this is thread id 6131478528.

Sebaliknya, Anda harus mengenkapsulasi semua akses database dalam fungsi pembantu yang dapat dipanggil dengan `sync_to_async()` tanpa bergantung pada objek koneksi dalam suasana panggilan.