Comment exécuter des scripts Python dans les macros de LibreOffice Calc ?

Oui. LibreOffice Calc peut exécuter du code Python comme une macro au sein du processus LibreOffice, et une macro Basic de LibreOffice peut également appeler une fonction Python via le système de scripts de LibreOffice. Si votre objectif est de lire ou de modifier des cellules dans la feuille de calcul ouverte, une macro Python exécutée dans le même processus est généralement le point de départ le plus simple. Utilisez un appel Basic-to-Python lorsqu'une macro Basic existante doit déléguer une tâche à une fonction Python réutilisable.

Ces méthodes diffèrent de l'exécution d'un script Python système classique via une commande shell. Un processus Python externe normal ne reçoit pas automatiquement l'objet document de Calc. Pour accéder au classeur, exécutez une macro Python via LibreOffice ou connectez un processus externe à une instance de LibreOffice via UNO.

Que signifie « exécuter du code Python dans une macro Calc » ?

LibreOffice prend en charge plusieurs langages de script grâce à son système de script. Dans une macro Python, LibreOffice fournit un objet de contexte UNO qui permet au script d'accéder au document courant et à ses feuilles. Une macro Python est une fonction appartenant à un .pymodule ; le g_exportedScriptstuple du module identifie les fonctions que LibreOffice doit afficher comme des macros exécutables.

Une macro Python peut s'exécuter directement depuis le menu des macros de Calc. Elle n'a pas besoin d'être appelée par Basic. Si vous possédez déjà une macro Basic et souhaitez qu'elle appelle Python, le fournisseur de scripts de LibreOffice ou le Session.ExecutePythonScriptservice plus récent ScriptForge peuvent faire le lien entre les deux langages.

Quelle approche choisir ?

• Utilisez directement une macro Python lorsque la tâche est principalement réalisée en Python et nécessite le document Calc courant. Cela évite une transition entre les langages et facilite le débogage grâce à un script unique.
• Appelez Python depuis Basic lorsque vous avez déjà du code Basic, des boutons ou des événements de document qui doivent rester en place, et que vous souhaitez qu'une fonction d'assistance Python effectue un calcul ou une opération sur les données ciblée.
• Utilisez un processus Python externe si vous avez besoin d'un environnement de développement distinct ou de packages Python non inclus dans LibreOffice. Configurez une connexion UNO explicite ; ne présumez pas qu'un script lancé depuis un terminal puisse accéder à la feuille de calcul ouverte.

Par exemple, un petit outil de nettoyage de tableur peut être entièrement écrit sous forme de macro Python. Si un bouton « Basique » existant génère déjà un rapport, conservez sa macro et faites-la appeler une fonction Python qui calcule le total du rapport.

Comment créer une macro Python qui modifie les cellules d'une calculatrice Calc ?

LibreOffice stocke les scripts Python personnels dans le profil utilisateur, les scripts globaux dans le répertoire d'installation et les scripts de document avec le document. Pour un premier test, un script personnel est pratique car il est accessible depuis n'importe quel document LibreOffice ouvert par le même utilisateur. Cependant, il n'est pas inclus dans un fichier ODS ; une autre personne ne le recevra donc pas automatiquement avec la feuille de calcul.

Dans l'Aide de LibreOffice, sous « Organisation et emplacement des scripts Python », trouvez le dossier de scripts Python personnels de votre système. %APPDATA%\LibreOffice\4\user\Scripts\pythonSous Windows, ce dossier se trouve généralement à cet emplacement, tandis que ~/.config/libreoffice/4/user/Scripts/pythonsous Linux, il se trouve à cet emplacement également. Le profil lui-même peut varier ; utilisez l'emplacement indiqué pour votre installation plutôt que de créer un second répertoire de profil au hasard.

Créez un fichier nommé calc_tools.pydans le dossier des scripts Python personnels, puis ajoutez cet exemple simple :

def double_a1(args=None):
    doc = XSCRIPTCONTEXT.getDocument()
    sheet = doc.getCurrentController().getActiveSheet()

    source = sheet.getCellRangeByName("A1")
    target = sheet.getCellRangeByName("B1")
    target.setValue(source.getValue() * 2)

g_exportedScripts = (double_a1,)

Cette fonction lit la valeur numérique de la cellule A1 de la feuille active et écrit le double de cette valeur dans la cellule B1. XSCRIPTCONTEXTElle est fournie à une macro Python de LibreOffice lors de son exécution ; il ne s’agit pas d’une variable globale Python classique lorsque le même fichier est ouvert en dehors de LibreOffice. La fonction publique est répertoriée g_exportedScriptsafin qu’elle apparaisse dans le sélecteur de macros.

Enregistrez le fichier, puis ouvrez ou retournez dans Calc et choisissez Outils > Macros > Exécuter les macros . Selon la version de LibreOffice ou la traduction de la plateforme, l'intitulé du menu peut être au singulier. Sélectionnez Mes macros > calc_tools > double_a1 et exécutez-la. Saisissez d'abord un nombre dans la cellule A1, puis vérifiez que la cellule B1 contient le double de cette valeur. Si le module n'apparaît pas, vérifiez que l'extension du fichier est .pycorrecte, que le fichier se trouve dans le dossier Python du profil approprié et que la prise en charge des scripts Python est installée. Redémarrer LibreOffice après l'ajout d'un nouveau module peut permettre d'actualiser la liste des scripts.

Comment une macro Basic peut-elle appeler une fonction Python ?

Pour effectuer un appel Basic vers Python, placez un module Python dans votre dossier de scripts personnels et appelez sa fonction via le service ScriptForge Session. Cet exemple additionne deux valeurs en Python et écrit le résultat dans la cellule B1 de la feuille Calc active.

Dans calc_tools.py, définissez la fonction :

def add_values(first, second):
    return float(first) + float(second)

g_exportedScripts = (add_values,)

Créez ensuite une macro de base dans Calc et utilisez-la :

Sub RunPythonHelper()
    Dim session As Object
    Dim result As Variant
    Dim sheet As Object

    session = CreateScriptService("Session")
    result = session.ExecutePythonScript( _
        session.SCRIPTISPERSONAL, _
        "calc_tools.py$add_values", _
        12, 30)

    sheet = ThisComponent.CurrentController.getActiveSheet()
    sheet.getCellRangeByName("B1").setValue(result)
End Sub

Exécutez RunPythonHelperla macro depuis le sélecteur de macros de base. Si l'appel réussit, B1 doit afficher 42. La référence du script suit le format suivantmodule.py$function_name ; pour un module situé dans un sous-dossier ou un autre emplacement de stockage, utilisez la syntaxe et la constante d'emplacement documentées pour cette version de ScriptForge. Utilisez des types de données pour les arguments et les valeurs de retour compatibles avec les deux langages, tels que les nombres, les chaînes de caractères et les séquences simples.

CreateScriptServiceLes assistants de session ScriptForge documentés sont disponibles dans les versions récentes de LibreOffice, mais les noms de menus et les composants inclus peuvent différer dans les versions plus anciennes ou celles fournies par la distribution. Si ce service est indisponible, utilisez la méthode UNO de LibreOffice, qui récupère un XScriptscript à partir de son URI et l'exécute. Évitez de copier un fragment de code destiné à un autre emplacement de macro sans modifier son paramètre d'emplacement.

Le code Python doit-il être personnel, partagé ou intégré ?

Pour un travail d'équipe, définissez la méthode d'accès au code et sa fiabilité avant de créer un classeur autour d'une macro personnelle. Si la logique Python doit accompagner la feuille de calcul, testez le stockage des macros et les alertes de sécurité sur les mêmes versions de LibreOffice utilisées par vos destinataires. Pour un déploiement géré, un administrateur peut créer des packages de scripts pour les utilisateurs ou distribuer une extension conformément aux contrôles logiciels habituels de l'organisation.

Pourquoi la macro pourrait-elle être manquante ou ne pas fonctionner ?

• L'option ou le module Python est absent. Sur certaines distributions GNU/Linux, le framework de script Python de LibreOffice est un paquet optionnel. Consultez les instructions d'installation de LibreOffice de votre distribution si les macros Python n'apparaissent pas dans la boîte de dialogue des macros.
• Le script est enregistré dans le mauvais profil. LibreOffice peut utiliser plusieurs profils utilisateur. Vérifiez le chemin d'accès au profil de l'installation en cours et enregistrez le module dans son Scripts/pythonrépertoire.
• Cette fonction n'est pas exportée. Ajoutez-la g_exportedScriptspour une fonction que vous souhaitez exécuter depuis le sélecteur de macros. Assurez-vous que la syntaxe du tuple inclut la virgule finale pour un tuple à un seul élément.
• Ce script s'exécute en dehors de LibreOffice. XSCRIPTCONTEXT Il existe pour une macro lancée par LibreOffice, et non lorsque le même fichier est ouvert par la commande système python. Utilisez l'exécuteur de macros ou configurez une connexion UNO documentée.
• La sécurité des macros bloque le code intégré. Consultez les paramètres de sécurité des macros de LibreOffice et n'autorisez que le code provenant d'une source fiable. Abaisser le niveau de sécurité global n'est pas une solution de dépannage rapide et efficace.
• Un module importé ne peut pas accéder au contexte du document. LibreOffice XSCRIPTCONTEXTne transmet pas ce contexte aux modules importés. Transmettez l'objet document ou feuille nécessaire aux fonctions d'assistance au lieu de supposer que les modules importés lisent cette variable globale.
• Aucune sortie n'est visible dans la console. La sortie standard de Python n'est pas disponible lorsqu'une macro est exécutée depuis le menu Outils > Macros. Pour obtenir un retour d'information, écrivez le résultat dans une cellule, utilisez un service de boîte de dialogue LibreOffice ou enregistrez-le dans un fichier.

Comment vérifier le résultat en toute sécurité ?

Effectuez un test avec une copie du tableur et des données d'entrée connues. Vérifiez que la macro Python apparaît bien dans l'exécuteur, exécutez-la une fois et comparez la cellule de sortie avec un résultat calculé manuellement. Pour un appel Basic vers Python, testez une entrée simple et vérifiez que la valeur renvoyée est bien enregistrée dans la feuille prévue. Évitez d'utiliser des scripts qui suppriment des feuilles, écrasent de grandes plages de données ou exécutent des commandes système.

Une fois le test concluant, déterminez comment le script sera installé sur d'autres ordinateurs et documentez les bibliothèques Python requises ou les versions de LibreOffice nécessaires. L'environnement Python intégré à LibreOffice est celui utilisé pour les macros intégrées ; les paquets installés pour un interpréteur Python système distinct peuvent ne pas être disponibles. Si vous avez besoin de paquets provenant d'un autre interpréteur, utilisez la méthode de processus externe/UNO et configurez cette connexion de manière appropriée.

Références officielles

• Aide LibreOffice : Création de scripts Python avec ScriptForge
• Aide LibreOffice : Exécuter des scripts Python depuis Basic
• Aide LibreOffice : Programmation avec des scripts Python
• Aide LibreOffice : Organisation et emplacement des scripts Python
• Aide LibreOffice : Lecture et écriture de valeurs dans des plages de valeurs
• Kit de développement logiciel LibreOffice : interface XScript