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 パフォーマンス), 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\nパフォーマンス). A wide range of async-native Python libraries can\nalso be integrated.
どのようなビューでも、呼び出し可能オブジェクトでコルーチンを返すようにすれば、非同期として宣言できます。その際には、一般的に async def を使います。関数ベースのビューの場合、async def を用いてビュー全体を宣言します。クラスベースのビューの場合、get() と post() などのメソッドを async def で宣言します (__init__() でも as_view() でもないことに注意)。
WSGI サーバーでは、非同期ビューは1回限りのイベントループで実行されます。つまり、非同期 HTTP リクエストなどの非同期機能を問題なく使用できるものの、非同期スタックのメリットは得られないことになります。
\n非同期スタックの主な利点とは、数百もの接続を Python のスレッドを使わずに処理できることです。これにより、低速ストリーミング、ロングポーリング、その他の便利なレスポンスタイプが使えます。
\nもしこれらを利用したい場合は、代わりに ASGI を使って Django をデプロイする必要があります。
\n\nASGI モードと WSGI モードの両方で、コードを逐次的ではなく並行して実行するために、非同期サポートを安全に使用できます。これは、外部 API やデータストアを扱う際に特に便利です。
\nまだ同期的な Django の機能を呼び出したい場合、次のように sync_to_async() でラップする必要があります。
from asgiref.sync import sync_to_async\n\nresults = await sync_to_async(sync_function, thread_sensitive=True)(pk=123)\n非同期ビューから、同期的な Django の機能を誤って呼び出そうとすると、Django の 非同期セーフティプロテクション が発動して、データが破損しないように保護されます。
\n以下のデコレータは、同期ビュー関数でも非同期ビュー関数でも使用できます。
\nconditional_page()
xframe_options_deny()
xframe_options_sameorigin()
xframe_options_exempt()
例:
\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()\n詳細については 非同期クエリ で参照できますが、簡単にまとめると次のようになります。
\nSQL クエリを発行するすべての QuerySet メソッドには、a という接頭辞が付いた非同期版があります。
async for は (values() と values_list() を含む) すべての QuerySet でサポートされている
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)\nトランザクションは非同期モードではまだ機能しません。もしトランザクションの動作が必要なコードがある場合は、そのコードを1つの同期的な関数として書いて、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.
\n自分のコード上での ASGI と WSGI の違いの影響を知るためには、自分自身でパフォーマンステストを行うべきです。場合によっては、純粋に同期的なコードベースを ASGI 上で実行した場合でも、性能が向上することがあります。これは、それでもリクエストハンドリングのコードはすべて非同期に実行されるためです。一般的には、ASGI モードを有効にする必要があるのは、プロジェクトに非同期のコードがあるときだけです。
\n長時間のリクエストの場合、ビューが応答を返す前にクライアントが切断することがあります。この場合、asyncio.CancelledErrorがビューで発生します。このエラーをキャッチし、クリーンアップが必要な場合にハンドリングできます:
\nasync def my_view(request):\n try:\n # Do some work\n ...\n except asyncio.CancelledError:\n # Handle disconnect\n raise\nまた、ストリーミングレスポンスでクライアントの切断をハンドリングする こともできます。
\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.
\n実行中のイベントループ があるスレッドからこれらのパーツを実行しようとすると、 SynchronousOnlyOperation エラーが発生します。このエラーは、非同期関数の内部でなくても発生することに注意してください。 sync_to_async() などを使わずに、非同期関数から直接同期関数を呼び出した場合にも発生します。これは、コードが同期コードとして宣言されていなくても、アクティブなイベントループを持つスレッドで実行されているためです。
このエラーが発生した場合は、問題のコードを非同期コンテキストから呼び出さないように修正する必要があります。代わりに、独自の同期関数それ自体の中で async-unsafe と通信するコードを書き、 asgiref.sync.sync_to_async() (または、自スレッド内で同期コードを実行するための他の方法) を使って呼び出します。
非同期コンテキストは、Django コードを実行している環境によって与えられる場合もあります。たとえば、Jupyter notebooks や IPython 対話シェルはともにアクティブなイベントループを透過的に提供してくれるため、非同期 API との対話がより簡単になります。
\nもし IPython shell を使用している場合は、次のコマンドでこのイベントループを無効化できます。
\n%autoawait off\nこれは IPython のプロンプトのコマンドです。これにより同期的なコードを SynchronousOnlyOperation エラーを起こさずに実行できるようになりますが、同時に、非同期 API を await することもできなくなります。イベントループを戻すには、次のコマンドを実行します。
%autoawait on\nIPython 以外の環境にいる場合 (または、何らかの理由で IPython で autoawait がオフにできない場合)、コードが並行して実行される可能性は 確実に ないため、同期コードは 絶対に 非同期コンテキストから実行する必要があります。このとき、警告は DJANGO_ALLOW_ASYNC_UNSAFE 環境変数を任意の値に設定することで無効化できます。
もし、これをPython内部から行いたい場合は、os.environ を使用してください。
import os\n\nos.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true"\n同期コードを非同期コンテキストから呼び出したり、その逆をするためには、呼び出しスタイルを調整する必要があります。このために asgiref.sync モジュールの async_to_sync() と sync_to_async() という2つのアダプター関数があります。これらは互換性を維持したまま呼び出しスタイル間を移行するために使われます。
これらのアダプター関数は Django で幅広く利用されています。asgiref パッケージ自体が Django プロジェクトの一部になっており、Django を pip でインストールしたときに自動的に依存関係としてインストールされます。
async_to_sync()Link to this heading#非同期関数を取り、それをラッピングした同期関数を返します。直接ラッパーとしてもデコレーターとしても使用できます。
\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(): ...\n非同期関数は、もし存在すれば、現在のスレッドのイベントループの中で実行されます。現在のイベントループが存在しない場合、1つの非同期呼び出しのために専用の新しいイベントループが生成され、完了したら再び破棄されます。どちらの状況でも、非同期関数はコードが呼び出されたスレッドとは異なるスレッドで実行されます。
\nthreadlocal とコンテキスト変数の値は双方向に境界を越えて保持されます。
\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#同期関数を取り、それをラッピングした非同期関数を返します。直接ラッパーとしてもデコレーターとしても使用できます。
\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(): ...\nthreadlocal とコンテキスト変数の値は双方向に境界を越えて保持されます。
\n同期関数はすべてメインスレッド内で実行されることを想定して書かれる傾向があるため、sync_to_async() には2種類の threading モードがあります。
thread_sensitive=True (デフォルト): 同期関数は他のすべての thread_sensitive 関数と同じスレッド内で実行されます。もしメインスレッドが同期的で async_to_sync() ラッパーを使用している場合、このスレッドはメインスレッドになるでしょう。
thread_sensitive=False: 同期関数は、まったく新しいスレッドで実行されます。そのスレッドは、その後呼び出しが完了すると閉じられます。
thread-sensitive モードは極めて特別なモードで、すべての関数が同一スレッドで実行されるようにするためにたくさんの仕事を行います。ただし、メインスレッドで正しく動作するように、スタック内での async_to_sync() の使用に依存している ことに注意してください。もし asyncio.run() や類似のメソッドを使用した場合、thread-sensitive な関数は単一の共有スレッドでの実行にフォールバックしますが、これはメインスレッドではありません。
Django でこれが必要な理由は、多くのライブラリ、特にデータベースアダプターが、自分が作られたのと同一スレッド内でのアクセスを必要とするためです。また、既存の多くの Django コードも、すべてが同一スレッドで実行されることを想定しています。たとえば、ビュー内で後で使用するためにリクエストに何かを追加するミドルウェアです。
\nこのコードによって潜在的な互換性の問題を引き起こす代わりに、私たちはこのモードを追加する選択をしました。これにより、既存のすべての Django の同期コードが同一スレッドで実行されるようになり、したがって、非同期モードと完全に互換になります。同期コードは、それを呼び出すすべての非同期コードとは常に 異なる スレッド内にあるため、生のデータベースハンドルや、その他 thread-sensitive な参照を渡すことは避ける必要があることに注意してください。
\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.
実用的には、この制限は、sync_to_async() を呼び出すときにデータベースの connection オブジェクトの機能を渡してはならないことを意味します。もしそうした場合、スレッド安全性のチェックがトリガーされます:
# 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.\n代わりに、呼び出しコード内の connection オブジェクトに依存せずに、sync_to_async() で呼び出すことができるヘルパー関数内にすべてのデータベースアクセスをカプセル化する必要があります。