Tâches en arrière-plan
Tâches en arrière-plan
frappe.enqueue_task lance une fonction dans un worker, comme frappe.enqueue. En plus, elle crée un document Tâche en arrière-plan (Background Task) que l'utilisateur suit dans l'interface : statut, progression, étape, résultat.
Ce que voit l'utilisateur
Le bouton Tâches en arrière-plan de la barre latérale ouvre la liste des tâches récentes de l'utilisateur. Le bouton est masqué quand l'utilisateur n'a aucune tâche. Un message s'affiche à chaque changement de statut.
| Statut | Signification |
|---|---|
| En file d'attente | La tâche attend un worker |
| En cours | Un worker exécute la tâche |
| Terminé | La fonction s'est terminée sans erreur |
| Échec | La fonction a levé une exception |
| Annulé | Un utilisateur a arrêté la tâche |
Dans la liste, le bouton Annuler arrête une tâche en file d'attente ou en cours. Le bouton Recommencer relance une tâche en échec ou annulée, avec les mêmes arguments. Voir toutes les tâches ouvre la liste complète.
| Action | Propriétaire de la tâche | Responsable système |
|---|---|---|
| Voir la tâche | Oui | Toutes les tâches |
| Annuler une tâche en file d'attente | Oui | Oui |
| Annuler une tâche en cours | Si allow_user_cancellation | Oui |
| Recommencer | Si allow_user_retry | Oui |
| Voir la méthode, les arguments et l'exception | Non | Oui |
Les Paramètres des journaux suppriment les tâches de plus de 7 jours (valeur par défaut), avec leurs fichiers joints.
Lancer une tâche
import frappe
def recalculer_prix(liste_prix):
task = frappe.get_current_task()
articles = frappe.get_all("Item Price", filters={"price_list": liste_prix}, pluck="name")
for i, nom in enumerate(articles, start=1):
frappe.get_doc("Item Price", nom).save()
task.publish_progress(i / len(articles) * 100, stage=f"Article {i} sur {len(articles)}")
return {"articles": len(articles)}
frappe.enqueue_task(
"mon_app.prix.recalculer_prix",
task_name="Recalcul des prix",
queue="long",
liste_prix="Standard Selling",
)
Les arguments nommés qui ne sont pas des options de enqueue_task vont à la fonction (ici liste_prix). Ils doivent être sérialisables en JSON pour que Recommencer fonctionne.
Par défaut, Dodock met la tâche en file après le commit de la transaction en cours (enqueue_after_commit=True). La valeur renvoyée par la fonction devient le résultat de la tâche.
Paramètres de enqueue_task
| Paramètre | Défaut | Effet |
|---|---|---|
method | Fonction ou chemin de la fonction | |
task_name | Chemin de la méthode | Nom affiché à l'utilisateur |
queue | "default" | File : short, default ou long |
timeout | None | Durée maximale en secondes |
ref_doctype, ref_docname | None | Document lié à la tâche. attach_file y joint ses fichiers |
deduplicate, job_id | False, None | Évite deux jobs avec le même job_id |
enqueue_after_commit | True | Met en file après le commit |
now | False | Exécute la tâche tout de suite, dans le processus courant (tests) |
on_success, on_failure | None | Fonctions appelées après un succès ou un échec |
retry_on, max_retries | (), 0 | Relance automatique sur ces exceptions, au plus max_retries fois |
show_progress_bar | True | Affiche la barre de progression |
allow_user_cancellation | True | Le propriétaire peut arrêter la tâche en cours |
allow_user_retry | True | Le propriétaire peut relancer la tâche |
at_front, at_front_when_starved | False | Place le job en tête de file |
enqueue_task renvoie le document Tâche en arrière-plan.
Méthodes dans la fonction
frappe.get_current_task() renvoie la tâche en cours, ou None hors d'une tâche.
| Méthode | Effet |
|---|---|
publish_progress(percent, stage=None) | Envoie la progression (0 à 100) et l'étape. Au plus un envoi toutes les 0,2 seconde, sauf à 100 % |
update_stage(stage) | Envoie une étape sans pourcentage |
store_result(result) | Enregistre un résultat en JSON |
attach_file(file_name, content, is_private=True, doctype=None, docname=None) | Joint un fichier à la tâche (ou au document de référence) et renvoie son URL |
def exporter_clients():
task = frappe.get_current_task()
contenu = generer_csv() # fonction de votre application
url = task.attach_file("clients.csv", contenu.encode())
return {"fichier": url}
Fonctions de rappel
Dodock enregistre le chemin de on_success et on_failure. Utilisez une fonction de module, pas une fonction locale ni un lambda.
Dodock passe à la fonction, par nom, les arguments qu'elle déclare parmi : task, result (succès), exception (échec) et les arguments de la tâche.
def apres_succes(task, result):
frappe.sendmail(
recipients=[task.user],
subject=f"{task.task_name} : terminé",
message=f"{result['articles']} articles recalculés.",
)
def apres_echec(task, exception):
frappe.log_error(title=f"{task.task_name} en échec")
Une erreur dans une fonction de rappel ne change pas le statut de la tâche. Dodock l'enregistre dans le Journal des Erreurs.
Annulation
Pour une tâche en cours, l'annulation envoie à RQ une commande d'arrêt du job. Le traitement s'arrête au milieu de la fonction. Si la fonction écrit des données sans les valider en une seule transaction, passez allow_user_cancellation=False.