Gestion du code asynchrone

New in Django 3.0.

Django a développé une prise en charge du code Python asynchrone (« async »), mais ne propose pas encore des vues ou des intergiciels asynchrones ; cela devrait arriver dans les prochaines versions.

Il existe une prise en charge restreinte pour d’autres parties de l’écosystème asynchrone ; en particulier, Django peut nativement converser avec ASGI, et apporte une prise en charge partielle de l’isolation de code asynchrone.

Isolation de code asynchrone

Certaines parties essentielles de Django ne sont pas capables d’opération de manière sûre dans un environnement asynchrone, car elles se basent sur un état global qui n’est pas compatible avec les coroutines. Ces parties de Django sont classées comme non sûres pour l’asynchrone (« async-unsafe ») et sont protégées contre l’exécution dans un environnement asynchrone. L’exemple principal est l’ORM (dialogue avec les bases de données), mais d’autres parties sont protégées de la même manière.

Si vous essayez d’exécuter l’une de ces parties depuis un fil d’exécution où une boucle événementielle s’exécute, vous obtiendrez une erreur SynchronousOnlyOperation. Notez que vous n’avez pas besoin d’être directement dans une fonction asynchrone pour déclencher cette erreur. Si vous avez appelé une fonction synchrone directement depuis une fonction asynchrone sans passer par un mécanisme comme sync_to_async() ou un pool d’exécution, cela peut alors aussi arriver, car votre code se trouve encore dans un contexte asynchrone.

SI vous obtenez cette erreur, vous devriez corriger votre code pour qu’il n’appelle pas le code de manière fautive depuis un contexte asynchrone ; ce peut être fait en plaçant le code communiquant avec la partie non prête pour l’asynchrone dans sa propre fonction synchrone et en l’appelant par asgiref.sync.sync_to_async(), ou toute autre méthode d’exécution de code synchrone dans un fil d’exécution adapté.

Si vous avez un impérieux besoin d’appeler ce code depuis un contexte asynchrone, par exemple si un environnement externe vous force à le faire, et que vous êtes certain qu’il n’y a aucun risque qu’il soit lancé de manière concurrente (par ex. dans un carnet Jupyter), vous pouvez désactiver l’avertissement avec la variable d’environnement DJANGO_ALLOW_ASYNC_UNSAFE.

Avertissement

Si vous activez cette option et qu’un accès concurrent se produit sur des parties de Django non adaptées à l’asynchrone, vous pourriez expérimenter des pertes ou des corruptions de données. Soyez très prudent et n’utilisez pas cela dans des environnements de production.

Si vous devez faire cela depuis du code Python, faites-le avec os.environ:

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

Fonctions d’adaptation asynchrone

Il est nécessaire d’adapter le style d’appel lors des appels de code synchrone depuis un contexte asynchrone ou vice versa. Il existe pour cela deux fonctions d’adaptation disponibles dans le paquet asgiref.sync: async_to_sync() et sync_to_async(). Elles sont utiles pour faire le passage entre des styles d’appel synchrones et asynchrones tout en préservant la compatibilité.

Ces fonctions d’adaptation sont largement utilisées dans Django. Le paquet asgiref lui-même fait partie du projet Django et il est automatiquement installé comme dépendance lorsqu’on installe Django avec pip.

async_to_sync()

async_to_sync(async_function, force_new_loop=False)

Enveloppe une fonction asynchrone et renvoie à la place une fonction synchrone. Peut être utilisée sous forme directe ou comme décorateur

from asgiref.sync import async_to_sync

sync_function = async_to_sync(async_function)

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

La fonction asynchrone est exécutée dans la boucle événementielle du fil d’exécution actuel, le cas échéant. S’il n’y a pas de boucle événementielle, un nouvelle boucle est générée spécifiquement pour la fonction asynchrone et arrêtée dès que la fonction est terminée. Quelle que soit la situation, la fonction asynchrone s’exécutera dans un fil d’exécution différent de celui du code appelant.

Les valeurs « threadlocals » et « contextvars » sont préservées de part et d’autres des exécutions.

async_to_sync() est fondamentalement une version plus puissante de la fonction asyncio.run() de la bibliothèque Python standard. En plus de s’assurer du fonctionnement de « threadlocals », elle active aussi le mode thread_sensitive de sync_to_async() lorsque cette dernière est utilisée en dessous d’elle.

sync_to_async()

sync_to_async(sync_function, thread_sensitive=False)

Enveloppe une fonction synchrone et renvoie à la place une fonction asynchrone (utilisable avec await). Peut être utilisée sous forme directe ou comme décorateur

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

Les valeurs « threadlocals » et « contextvars » sont préservées de part et d’autres des exécutions.

Les fonctions synchrones ont tendances à être écrites en partant du principe qu’elles s’exécutent toutes dans le fil d’exécution principal, ce qui fait que sync_to_async() dispose de deux modes d’exécution :

• thread_sensitive=False (par défaut) : la fonction synchrone sera exécutée dans un tout nouveau fil d’exécution qui sera ensuite détruit lorsque la fonction sera terminée.
• thread_sensitive=True: la fonction synchrone sera exécutée dans le même fil d’exécution que toutes les autres fonctions thread_sensitive, et ce fil sera le fil principal si celui-ci est synchrone et que vous utilisez la fonction enveloppeuse async_to_sync().

Le mode « thread-sensitive » est très spécial et fait beaucoup d’efforts pour exécuter toutes les fonctions dans le même fil d’exécution. Notez toutefois qu’il compte sur l’utilisation de async_to_sync() au-dessus de lui dans la pile d’appels pour lancer les choses correctement dans le fil d’exécution principal. Si vous utilisez asyncio.run() (ou alors d’autres options), il se limite à exécuter simplement les fonctions dépendantes du fil d’exécution dans un seul fil partagé (mais pas le fil d’exécution principal).

La raison de sa présence dans Django est que de nombreuses bibliothèques, particulièrement les adaptateurs de base de données, exigent que leur accès se fasse dans le même fil d’exécution dans lequel elles ont été créées ; une grande quantité de code existant dans Django présuppose qu’il s’exécute entièrement dans le même fil d’exécution (par ex. un intergiciel ajoutant des éléments à une requête pour utilisation ultérieure par une vue).

Plutôt que d’introduire des problèmes potentiels de compatibilité avec ce code, nous avons choisi d’ajouter ce mode afin que tout code synchrone existant dans Django soit exécuté dans le même fil d’exécution et reste donc pleinement compatible avec le mode asynchrone. Notez que le code synchrone sera toujours exécuté dans un fil d’exécution différent du code asynchrone appelant, ce qui implique que vous devez éviter de passer des pointeurs bruts de base de données ou d’autres références sensibles au fil d’exécution dans tout nouveau code que vous écrivez.