Pour une application web, il y a souvent du code à exécuter en plus du processus de transformation des requêtes HTTP en réponses HTTP. Pour certaines fonctionnalités, il peut être avantageux d’exécuter du code en dehors du cycle de requête-réponse.
\nC’est là qu’entrent en jeu les tâches d’arrière-plan.
\nLes tâches d’arrière-plan peuvent décharger le cycle de requête-réponse pour exécuter du code en dehors de ce cycle, potentiellement à une date ultérieure. Cela permet de garder les requêtes rapides, de réduire la latence et d’amélioration le ressenti des utilisateurs. Par exemple, une utilisatrice ne devrait pas avoir besoin d’attendre qu’un courriel soit envoyé avant que sa page termine de charger.
\nL’infrastructure des tâches de Django facilite la définition et la mise en file d’attente de ce genre de travail. Mais elle ne fournit pas de mécanisme d’exécution de ces tâches. L’exécution réelle doit être gérée par une infrastructure extérieure à Django, telle qu’un processus ou service séparé. À ce titre, un moteur de tâches capable de les exécuter sur ce service externe doit être choisi et configuré.
\nLorsque du code doit être exécuté en arrière-plan, Django crée une tâche Task, qui est stockée dans une file d’attente. Cette tâche contient toutes les métadonnées utiles à son exécution, de même qu’un identifiant unique pour que Django puisse plus tard obtenir son résultat.
Un processus de travail ira piocher de nouvelles tâches à exécuter dans la file d’attente. Lorsqu’une nouvelle tâches est ajoutée, le processus réserve la tâche, l’exécute, et enregistre son statut et son résultat dans la file d’attente. Ces processus s’exécutent en dehors du cycle de requête-réponse.
\nLe moteur de tâches détermine comment et où les tâches sont stockées en vue de leur exécution et comment elles sont exécutées. Différents moteurs de tâches possèdent différentes caractéristiques et options de configuration, ce qui peut influer sur la performance et la fiabilité de votre application. Django est livré avec des moteurs intégrés, mais ceux-ci sont uniquement pour du développement ou des tests.
\nDjango gère la définition des tâches, leur validation, mise en file d’attente, et gestion de leurs résultats, pas leur exécution, donc les configurations de production ont besoin d’un moteur ou d’un processus de lancement qui exécute réellement ce qui se trouve en attente. Les options possibles sont énumérées sur la page Community Ecosystem.
\nLes moteurs de tâches sont configurés par le réglage TASKS de votre fichier de réglages. Même si la majorité des applications n’auront besoin que d’un seul moteur, il est possible d’en avoir plusieurs.
Il s’agit du moteur par défaut si aucun autre n’a été indiqué dans le fichier des réglages. Ce moteur ImmediateBackend exécute immédiatement les tâches en file d’attente, au lieu de le faire en arrière-plan. Cela permet notamment d’ajouter progressivement la fonctionnalité des tâches à une application, avant que l’infrastructure nécessaire ne soit mise en place.
Pour l’utiliser, définissez BACKEND à "django.tasks.backends.immediate.ImmediateBackend":
TASKS = {"default": {"BACKEND": "django.tasks.backends.immediate.ImmediateBackend"}}\nLe moteur ImmediateBackend peut aussi être utile pour les tests, afin d’éviter d’avoir à exécuter un processus d’exécution externe au lancement des tests.
Le moteur DummyBackend n’exécute pas du tout les tâches en liste d’attente, elle ne fait que stocker leur résultat en vue d’une utilisation ultérieure. Ces résultats de tâches restent toujours dans l’état READY (prête).
Ce moteur n’est pas conçu pour être utilisé en production, il n’est fourni que par commodité et destiné à être utilisé durant le développement et les tests.
\nPour l’utiliser, définissez BACKEND à "django.tasks.backends.dummy.DummyBackend":
TASKS = {"default": {"BACKEND": "django.tasks.backends.dummy.DummyBackend"}}\nLes résultats des tâches en file d’attente peuvent être obtenus à partir de l’attribut results:
>>> from django.tasks import default_task_backend\n>>> my_task.enqueue()\n>>> len(default_task_backend.results)\n1\nLes résultats stockés peuvent être effacés en utilisant la méthode clear():
>>> default_task_backend.clear()\n>>> len(default_task_backend.results)\n0\nAs mentioned at the beginning of this section, Django includes backends\nsuitable for development and testing only. Production systems should rely on\nbackends that supply a worker process and a durable queue implementation.\nAvailable third-party backends are listed on the Community Ecosystem page and the Tasks\nframework grid from Django Packages.
\nPour utiliser un moteur de tâches externe avec Django, indiquez son chemin d’importation Python dans la clé setting:BACKEND <TASKS-BACKEND> du réglage setting:TASKS, comme ceci :
\nTASKS = {\n "default": {\n "BACKEND": "path.to.backend",\n }\n}\nUn moteur de tâches est une classe héritant de BaseTaskBackend. Au minimum, elle doit implémenter BaseTaskBackend.enqueue(). Si vous construisez votre propre moteur, vous pouvez utiliser les moteurs de tâches intégrés comme référence d’implémentation. Vous trouverez le code dans le répertoire django/tasks/backends/ du code source de Django.
La prise en charge des moteurs de tâches asynchrones est en développement.
\nBaseTaskBackend possède des variantes asnychrones de toutes les méthodes de base. Par convention, les versions asynchrones de toutes les méthodes sont préfixées par a. Les arguments des deux variantes sont identiques.
Les moteurs peuvent être obtenus en utilisant le gestionnaire de connexion task_backends:
from django.tasks import task_backends\n\ntask_backends["default"] # The default backend\ntask_backends["reserve"] # Another backend\nLe moteur par défaut est disponible en tant que default_task_backend:
from django.tasks import default_task_backend\nLes tâches sont définies en utilisant le décorateur django.tasks.task() sur une fonction au niveau d’un module :
from django.core.mail import send_mail\nfrom django.tasks import task\n\n\n@task\ndef email_users(emails, subject, message):\n return send_mail(\n subject=subject, message=message, from_email=None, recipient_list=emails\n )\nLa valeur renvoyée par le décorateur est une instance Task.
Les attributs de Task peuvent être personnalisés via les paramètres du décorateur @task:
from django.core.mail import send_mail\nfrom django.tasks import task\n\n\n@task(priority=2, queue_name="emails")\ndef email_users(emails, subject, message):\n return send_mail(\n subject=subject, message=message, from_email=None, recipient_list=emails\n )\nPar convention, les tâches sont définies dans un fichier tasks.py, mais ceci n’est pas obligatoire.
Parfois, la tâche à exécuter peut avoir besoin de connaître le contexte dans lequel elle a été mise en file d’attente, et comment elle est exécutée. Elle peut pour cela accepter un argument context qui est une instance de TaskContext.
Pour recevoir le contexte de la tâche comme argument d’une fonction de tâche, passez takes_context au moment de sa définition :
import logging\nfrom django.core.mail import send_mail\nfrom django.tasks import task\n\nlogger = logging.getLogger(__name__)\n\n\n@task(takes_context=True)\ndef email_users(context, emails, subject, message):\n logger.debug(\n f"Attempt {context.attempt} to send user email. Task result id: {context.task_result.id}."\n )\n return send_mail(\n subject=subject, message=message, from_email=None, recipient_list=emails\n )\nAvant de mettre une tâche en file d’attente, il peut être nécessaire de modifier certains paramètres de la tâche. Par exemple, pour lui donner une priorité plus haute que la normale.
\nUne instance Task ne peut pas être modifiée directement. Mais on peut par contre créer une instance modifiée avec la méthode using(), l’originale restant intacte. Par exemple :
>>> email_users.priority\n0\n>>> email_users.using(priority=10).priority\n10\nPour ajouter une tâche dans le stockage de la file d’attente en vue de son exécution, appelez la méthode enqueue() sur elle. Si la tâche accepte des arguments, ils peuvent être transmis tels quels. Par exemple :
result = email_users.enqueue(\n emails=["user@example.com"],\n subject="You have a message",\n message="Hello there!",\n)\nCela renvoie un objet TaskResult, qui peut être utilisé ensuite pour récupérer le résultat de la tâche après qu’elle a terminé son exécution.
Pour mettre en file d’attente des tâches dans un contexte asynchrone, aenqueue() est disponible comme variante async de enqueue().
Comme les arguments et les valeurs de renvoi des tâches sont toutes sérialisées en JSON, elles doivent pouvoir être sérialisées en JSON :
\n>>> process_data.enqueue(datetime.now())\nTraceback (most recent call last):\n...\nTypeError: Object of type datetime is not JSON serializable\nLes arguments doivent aussi être capable de faire un cycle aller-retour par json.dumps()/ json.loads() sans changer de type. Par exemple, considérez cette tâche :
@task()\ndef double_dictionary(key):\n return {key: key * 2}\nSi le moteur ImmediateBackend a été configuré comme moteur par défaut :
>>> result = double_dictionary.enqueue((1, 2, 3))\n>>> result.status\nFAILED\n>>> result.errors[0].traceback\nTraceback (most recent call last):\n...\nTypeError: unhashable type: 'list'\nLa tâche double_dictionary échoue parce qu’après l’aller-retour JSON, le tuple (1, 2, 3) devient la liste [1, 2, 3], qui ne peut pas être utilisée comme clé de dictionnaire.
En général, les objets complexes tels que des instances de modèles ou des types Python comme datetime ou tuple ne peuvent pas être utilisés dans le système des tâches sans une conversion spécifique.
Pour la plupart des moteurs, les tâches sont exécutées dans un processus séparé, utilisant une connexion de base de données différente. Lorsqu’on utilise une transaction, sans attendre que celle-ci soit commitée, des processus d’exécution pourraient démarrer le traitement d’une tâche utilisant des objets auxquels elle ne peut pas encore accéder.
\nPar exemple, considérons cet exemple simplifié :
\n@task\ndef my_task(thing_num):\n Thing.objects.get(num=thing_num)\n\n\nwith transaction.atomic():\n Thing.objects.create(num=1)\n my_task.enqueue(thing_num=1)\nPour éviter le scénario où my_task s’exécute avant que Thing ne soit commité dans la base de données, utilisez transaction.on_commit(), en liant tous les arguments à destination de enqueue() via functools.partial():
from functools import partial\n\nfrom django.db import transaction\n\nwith transaction.atomic():\n Thing.objects.create(num=1)\n transaction.on_commit(partial(my_task.enqueue, thing_num=1))\nLors de la mise en file d’attente d’une tâche Task, vous obtenez une instance TaskResult. Cette instance permet ensuite de récupérer le résultat de la tâche depuis un autre endroit (par exemple une autre requête ou une autre tâche).
Chaque TaskResult possède un id unique, qui peut être utilisé ensuite pour récupérer le résultat une fois que le code qui a mis la tâche en file d’attente ait terminé son travail.
La méthode get_result() peut récupérer un résultat sur la base de son id:
# Later, somewhere else...\nresult = email_users.get_result(result_id)\nPour obtenir un résultat TaskResult, quel que soit le type de tâche dont il provient, utilisez la méthode get_result() sur le moteur :
from django.tasks import default_task_backend\n\nresult = default_task_backend.get_result(result_id)\nPour récupérer des résultats dans un contexte asynchrone, aget_result() est disponible comme variante async de get_result(), aussi bien pour le moteur que pour une tâche Task.
Certains moteurs, tels que le moteur intégré ImmediateBackend, ne prennent pas en charge get_result(). Si on appelle cette méthode avec ces moteurs, une erreur NotImplementedError sera générée.
Un objet TaskResult contient l’état d’exécution d’une tâche au moment où il est obtenu. Si la tâche se termine après que get_result() est appelée, l’objet ne se met pas à jour tout seul.
Pour actualiser les valeurs, appelez la méthode django.tasks.TaskResult.refresh():
>>> result.status\nRUNNING\n>>> result.refresh() # or await result.arefresh()\n>>> result.status\nSUCCESSFUL\nSi votre fonction de tâche renvoie quelque chose, on peut le récupérer à partir de l’attribut django.tasks.TaskResult.return_value:
>>> result.status\nSUCCESSFUL\n>>> result.return_value\n42\nSi la tâche n’a pas terminé son exécution, ou qu’elle a échoué, une exception ValueError est générée.
>>> result.status\nRUNNING\n>>> result.return_value\nTraceback (most recent call last):\n...\nValueError: Task has not finished yet\nSi la tâche échoue et produit une exception, soit dans le contexte de la tâche ou lors de son exécution, l’exception et la trace d’erreur sont enregistrés dans la liste django.tasks.TaskResult.errors.
Chaque élément de errors est un objet TaskError contenant des informations au sujet de l’erreur produite durant l’exécution :
>>> result.errors[0].exception_class\n<class 'ValueError'>\nNotez qu’il ne s’agit que du type de l’exception et ne contient pas d’autres valeurs. Les informations de trace d’erreur sont réduites à une chaîne qui peut être utile en vue du débogage :
\n>>> result.errors[0].traceback\nTraceback (most recent call last):\n...\nTypeError: Object of type datetime is not JSON serializable\n