Асинхронная поддержка

Декораторы

Следующие декораторы могут использоваться как с синхронными, так и с асинхронными функциями представлений:

• cache_control()
• never_cache()
• no_append_slash()
• 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()

Например:

from django.views.decorators.cache import never_cache


@never_cache
def my_sync_view(request): ...


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

Запросы и ORM

С некоторыми исключениями Django может выполнять запросы ORM асинхронно:

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

Подробные заметки можно найти в Асинхронные запросы, но коротко:

• Все QuerySet методы, вызывающие SQL-запрос, имеют асинхронный вариант с префиксом a.
• async for поддерживается для всех QuerySet (включая вывод от values() и values_list().)

Django также поддерживает некоторые асинхронные методы модели, использующие базу данных:

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)

Транзакции пока не работают в асинхронном режиме. Если у вас есть фрагмент кода, которому необходимы транзакции, мы рекомендуем вам написать его как отдельную синхронную функцию и вызвать её с помощью sync_to_async().

Производительность

При выполнении в режиме, не соответствующем представлению (например, асинхронное представление под WSGI или традиционное синхронное представление под ASGI), Django должен эмулировать другой стиль вызова, чтобы ваш код мог выполняться. Эта смена контекста приводит к небольшой потере производительности примерно в миллисекунду.

Это также верно для middleware. Django попытается минимизировать количество переключений между синхронным и асинхронным режимами. Если у вас ASGI-сервер, но весь ваш middleware и представления синхронны, он переключится только один раз, прежде чем войдёт в стек middleware.

Однако, если вы поместите синхронный middleware между ASGI-сервером и асинхронным представлением, ему придётся переключиться в синхронный режим для middleware и затем обратно в асинхронный режим для представления. Django также удержит синхронный поток открытым для распространения исключений middleware. Это может быть незаметно вначале, но добавление этой пени в виде одного потока на запрос может аннулировать любое преимущество асинхронной производительности.

Вы должны провести собственные тесты производительности, чтобы увидеть, какое влияние ASGI по сравнению с WSGI оказывает на ваш код. В некоторых случаях может быть увеличение производительности даже для чисто синхронного кода под ASGI, потому что код обработки запросов всё ещё выполняется асинхронно. В общем, вы захотите включить ASGI-режим только если у вас есть асинхронный код в вашем проекте.

Обработка разрывов соединения

Для долгоживущих запросов клиент может разорвать соединение до того, как представление вернёт ответ. В этом случае в представлении будет поднято исключение asyncio.CancelledError. Вы можете поймать эту ошибку и обработать её, если вам нужно выполнить какие-либо действия по очистке:

async def my_view(request):
    try:
        # Do some work
        ...
    except asyncio.CancelledError:
        # Handle disconnect
        raise

Вы также можете обрабатывать разрывы соединения в потоковых ответах.

async_to_sync()

async_to_sync(async_function, force_new_loop=False)

Принимает асинхронную функцию и возвращает синхронную функцию, которая её оборачивает. Может использоваться как прямой обёртчик, так и как декоратор:

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

Асинхронная функция выполняется в цикле событий текущего потока, если он есть. Если текущего цикла событий нет, создаётся новый цикл событий специально для единичного асинхронного вызова и снова закрывается после его завершения. В любом случае асинхронная функция будет выполняться в другом потоке по сравнению с вызывающим кодом.

Значения threadlocals и contextvars сохраняются через границу в обоих направлениях.

async_to_sync() по сути является более мощной версией функции asyncio.run() в стандартной библиотеке Python. Помимо обеспечения работы threadlocals, она также включает режим thread_sensitive для sync_to_async(), когда этот обёртчик используется ниже.

sync_to_async()

sync_to_async(sync_function, thread_sensitive=True)

Принимает синхронную функцию и возвращает асинхронную функцию, которая её оборачивает. Может использоваться как прямой обёртчик, так и как декоратор:

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

Значения threadlocals и contextvars сохраняются через границу в обоих направлениях.

Синхронные функции, как правило, написаны в предположении, что они все выполняются в основном потоке, поэтому sync_to_async() имеет два режима работы с потоками:

• thread_sensitive=True (по умолчанию): синхронная функция будет выполняться в том же потоке, что и все другие thread_sensitive функции. Это будет основной поток, если основной поток является синхронным и вы используете обёртку async_to_sync().
• thread_sensitive=False: синхронная функция будет выполняться в новом потоке, который затем закрывается после завершения вызова.

Режим чувствительный к потокам довольно специфичен и выполняет большую работу для выполнения всех функций в одном потоке. Однако обратите внимание, что он зависит от использования async_to_sync() выше в стеке для правильного выполнения операций в основном потоке. Если вы используете asyncio.run() или аналогичное, он вернётся к выполнению потокозависимых функций в одном общем потоке, но это не будет основной поток.

Причина, по которой это необходимо в Django, заключается в том, что многие библиотеки, особенно адаптеры баз данных, требуют, чтобы к ним обращались в том же потоке, в котором они были созданы. Кроме того, много существующего кода Django предполагает, что всё выполняется в одном потоке, например, middleware добавляет вещи в запрос для последующего использования в представлениях.

Вместо того, чтобы вносить потенциальные проблемы совместимости с этим кодом, мы решили добавить этот режим, чтобы весь существующий синхронный код Django выполнялся в одном потоке и, таким образом, полностью совместим с асинхронным режимом. Обратите внимание, что синхронный код всегда будет в другом потоке по сравнению с любым асинхронным кодом, который его вызывает, поэтому вы должны избегать передачи сырых дескрипторов баз данных или других чувствительных к потокам ссылок.

На практике это ограничение означает, что вы не должны передавать функции базы данных connection при вызове sync_to_async(). Это вызовет проверки безопасности потоков:

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

Вместо этого вы должны инкапсулировать все обращения к базе данных внутри вспомогательной функции, которую можно вызывать с помощью sync_to_async() без обращения к объекту подключения в вызывающем коде.