非同期サポート

New in Django 3.0.

Django は非同期 ("async") Python の試験的サポートをしていますが、ビューやミドルウェアの非同期サポートはなされていません。今後のリリースでサポートされる予定です。

async エコシステムの他の部分のサポートは限定的です。つまり、 Django はネイティブで ASGI を話し、部分的に非同期安全性をサポートしています。

非同期安全性

Django の特定のキーパーツは、コルーチンが感知できないグローバルステートを持つため、非同期の環境では安全に操作できません。これらの Django のパーツは、"async-unsafe" として分類されており、非同期な環境での実行から保護されています。ORM は主な例ですが、この他にもこのように保護されているパーツがあります。

If you try to run any of these parts from a thread where there is a running event loop, you will get a SynchronousOnlyOperation error. Note that you don't have to be inside an async function directly to have this error occur. If you have called a synchronous function directly from an asynchronous function without going through something like sync_to_async() or a threadpool, then it can also occur, as your code is still running in an asynchronous context.

If you encounter this error, you should fix your code to not call the offending code from an async context; instead, write your code that talks to async-unsafe in its own, synchronous function, and call that using asgiref.sync.sync_to_async(), or any other preferred way of running synchronous code in its own thread.

もしこのコードを 絶対に 切実に非同期コンテキストから実行する必要がある場合 - 例えば、外部の環境に強制されていて、同時に実行される可能性が確実にない場合 (例: Jupyter notebook の中など)、環境変数 DJANGO_ALLOW_ASYNC_UNSAFE で警告を無効化できます。

警告

このオプションを有効にした上で、Djangoの async-unsafe パーツへ同時アクセスがあると、データが失われたり壊れたりする可能性があります。十分な注意を払い、本番環境では使用しないでください。

もし、これをPython内部から行いたい場合は、 os.environ:: を使用してください。

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

Async adapter functions

It is necessary to adapt the calling style when calling synchronous code from an asynchronous context, or vice-versa. For this there are two adapter functions, made available from the asgiref.sync package: async_to_sync() and sync_to_async(). They are used to transition between sync and async calling styles while preserving compatibility.

These adapter functions are widely used in Django. The asgiref package itself is part of the Django project, and it is automatically installed as a dependency when you install Django with pip.

async_to_sync()

async_to_sync(async_function, force_new_loop=False)

Wraps an asynchronous function and returns a synchronous function in its place. Can be used as either a direct wrapper or a decorator:

from asgiref.sync import async_to_sync

sync_function = async_to_sync(async_function)

@async_to_sync
async def async_function(...):
    ...

The asynchronous function is run in the event loop for the current thread, if one is present. If there is no current event loop, a new event loop is spun up specifically for the async function and shut down again once it completes. In either situation, the async function will execute on a different thread to the calling code.

Threadlocals and contextvars values are preserved across the boundary in both directions.

async_to_sync() is essentially a more powerful version of the asyncio.run() function available 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=False)

Wraps a synchronous function and returns an asynchronous (awaitable) function in its place. Can be used as either a direct wrapper or a decorator:

from asgiref.sync import sync_to_async

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

@sync_to_async
def sync_function(...):
    ...

Threadlocals and contextvars values are preserved across the boundary in both directions.

Synchronous functions tend to be written assuming they all run in the main thread, so sync_to_async() has two threading modes:

  • thread_sensitive=False (the default): the synchronous function will run in a brand new thread which is then closed once it completes.
  • thread_sensitive=True: the synchronous function will run in the same thread as all other thread_sensitive functions, and this will be the main thread, if the main thread is synchronous and you are using the async_to_sync() wrapper.

Thread-sensitive mode is quite special, and does a lot of work to run all functions in the same thread. Note, though, that it relies on usage of async_to_sync() above it in the stack to correctly run things on the main thread. If you use asyncio.run() (or other options instead), it will fall back to just running thread-sensitive functions in a single, shared thread (but not the main thread).

The reason this is needed in Django is that many libraries, specifically database adapters, require that they are accessed in the same thread that they were created in, and a lot of existing Django code assumes it all runs in the same thread (e.g. middleware adding things to a request for later use by a view).

Rather than introduce potential compatibility issues with this code, we instead opted to add this mode so that all existing Django synchronous code runs in the same thread and thus is fully compatible with asynchronous mode. Note, that synchronous code will always be in a different thread to any async code that is calling it, so you should avoid passing raw database handles or other thread-sensitive references around in any new code you write.