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

Декораторы

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

• 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()

Например:

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

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

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

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

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

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

Проведите собственное тестирование производительности, чтобы определить, как 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 предполагают выполнение в одном потоке — например, промежуточное ПО может добавлять данные в запрос для последующего использования в представлениях.

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

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

# 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(), не используя объект подключения в вызывающем коде.