Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
Développeurs

Tâches en arrière-plan

Lancer un traitement long avec frappe.enqueue_task pour que l'utilisateur suive sa progression, l'annule ou le relance depuis la barre latérale.

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.

StatutSignification
En file d'attenteLa tâche attend un worker
En coursUn worker exécute la tâche
TerminéLa fonction s'est terminée sans erreur
ÉchecLa 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.

ActionPropriétaire de la tâcheResponsable système
Voir la tâcheOuiToutes les tâches
Annuler une tâche en file d'attenteOuiOui
Annuler une tâche en coursSi allow_user_cancellationOui
RecommencerSi allow_user_retryOui
Voir la méthode, les arguments et l'exceptionNonOui

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ètreDéfautEffet
methodFonction ou chemin de la fonction
task_nameChemin de la méthodeNom affiché à l'utilisateur
queue"default"File : short, default ou long
timeoutNoneDurée maximale en secondes
ref_doctype, ref_docnameNoneDocument lié à la tâche. attach_file y joint ses fichiers
deduplicate, job_idFalse, NoneÉvite deux jobs avec le même job_id
enqueue_after_commitTrueMet en file après le commit
nowFalseExécute la tâche tout de suite, dans le processus courant (tests)
on_success, on_failureNoneFonctions appelées après un succès ou un échec
retry_on, max_retries(), 0Relance automatique sur ces exceptions, au plus max_retries fois
show_progress_barTrueAffiche la barre de progression
allow_user_cancellationTrueLe propriétaire peut arrêter la tâche en cours
allow_user_retryTrueLe propriétaire peut relancer la tâche
at_front, at_front_when_starvedFalsePlace 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éthodeEffet
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.