Scripts Python

Un script Python (« Script Serveur (Python) ») exécute du code sur le serveur sans développer d'application. Le code tourne dans un environnement restreint (RestrictedPython). Seule une sélection de fonctions est disponible.

Prérequis

• Les scripts Python sont désactivés par défaut. Activez-les pour tout le bench, dans common_site_config.json. La clé server_script_enabled d'un fichier site_config.json n'a pas d'effet.

  bench set-config -g server_script_enabled 1
  

• Vous avez le rôle Gestionnaire de script. Seul ce rôle peut créer, modifier ou supprimer un script.

Créer un script

1. Ouvrez la recherche (Ctrl+K) et saisissez « Script Serveur (Python) ».
2. Cliquez sur Ajouter.
3. Choisissez le Type de script.
4. Remplissez les champs propres à ce type (voir le tableau ci-dessous).
5. Saisissez le code dans le champ Script.
6. Enregistrez.

À l'enregistrement, Dokos compile le script. Une erreur de syntaxe s'affiche dans une fenêtre « Compilation warning ». Cochez Désactivé pour arrêter un script sans le supprimer.

Types de script

Événements de document

Le champ Evénement déclencheur propose ces valeurs :

Dans un script d'événement, frappe.db.commit() et frappe.db.rollback() ne sont pas disponibles. La transaction du document reste maîtrisée par Dokos.

Scripts planifiés

Le champ Fréquence de l'événement accepte : Tous, Toutes les heures, Quotidien, Hebdomadaire, Mensuel, Annuel, les variantes « - Long » (file d'attente longue) et Cron. À l'enregistrement, Dokos crée ou met à jour la tâche planifiée correspondante. Cocher Désactivé arrête cette tâche.

Scripts API

Le nom saisi dans Méthode d'API devient l'URL /api/method/<méthode>.

• Sans Autoriser les utilisateurs invités, un visiteur non connecté reçoit une erreur d'autorisation.
• Activer la limite d'usage limite le nombre d'appels. Par défaut : 5 requêtes (Limite de requêtes) par période de 86 400 secondes (Fenêtre temporelle (Secondes)).
• Renvoyez la réponse dans frappe.response["message"]. Une valeur placée dans frappe.flags remplace aussi message.

Fonctions disponibles

Les scripts Python ont accès à une version complète des fonctions de lecture et d'écriture. Les principales :

frappe.utils n'expose qu'une sélection de fonctions de frappe.utils.data. Les imports (import) sont interdits. Les noms qui commencent par _ sont inaccessibles.

Exemples

Fermer une tâche selon sa description

• Type de script : Evénement déclencheur
• Type de document de référence : ToDo
• Evénement déclencheur : Avant l'enregistrement

if doc.description and "terminé" in doc.description:
    doc.status = "Closed"

Bloquer l'enregistrement

• Evénement déclencheur : Avant l'enregistrement

if doc.priority == "High" and not doc.date:
    frappe.throw("Une tâche de priorité haute doit avoir une date d'échéance.")

frappe.throw affiche le message et annule l'enregistrement.

Créer une tâche après l'insertion d'un document

• Type de document de référence : Note (exemple)
• Evénement déclencheur : Après l'insertion

frappe.get_doc({
    "doctype": "ToDo",
    "allocated_to": frappe.session.user,
    "description": f"Relire la note : {doc.title}",
    "reference_type": doc.doctype,
    "reference_name": doc.name,
}).insert()

Créer une API

• Type de script : API
• Méthode d'API : taches_ouvertes

user = frappe.form_dict.get("user") or frappe.session.user
frappe.response["message"] = frappe.db.count("ToDo", {"allocated_to": user, "status": "Open"})

Appel : GET /api/method/taches_ouvertes?user=jean.dupont@exemple.fr renvoie {"message": 3} (exemple fictif).

Restreindre une liste par une requête d'autorisation

• Type de script : Requête d'autorisation
• Type de document de référence : ToDo

if user != "Administrator":
    conditions = f"`tabToDo`.allocated_to = {frappe.db.escape(user)}"

La variable conditions contient un filtre SQL ajouté à chaque lecture de la liste. Ici, chaque utilisateur ne voit que les tâches qui lui sont attribuées.