Créer des scripts Python avec ScriptForge

Différences entre Basic et Python

La bibliothèque ScriptForge est disponible pour Basic et Python. La plupart des services, méthodes et propriétés fonctionnent de manière identique dans les deux langages de programmation. Cependant, en raison des différences dans le fonctionnement de chaque langage, les utilisateurs de ScriptForge doivent être conscients de certaines caractéristiques de la bibliothèque lors de l'utilisation de Python :

Méthodes et noms de propriétés : en Python, toutes les méthodes et propriétés peuvent être utilisées dans les formats minuscules, ProperCased ou camelCased.
Arguments: All keyword arguments passed on to methods are lowercased.
Dates : tous les objets de date sont transmis et renvoyés sous la forme d'objets Python natifs datetime.datetime.
Matrices : les matrices unidimensionnelles sont passées et renvoyées sous forme de tuples (qui est un objet immuable). Les matrices à deux dimensions sont transmises et renvoyées sous forme de tuples de tuples.
Aucun : le mot-clé None de Python est équivalent à Null, Empty ou Nothing de Basic.
Objets UNO : toutes les structures UNO sont échangées entre Basic et Python sans aucun changement.
Débogage : chaque fois qu'une erreur se produit dans les scripts Python qui utilisent ScriptForge, le message d'erreur fourni par la pile d'exécution Python affiche la ligne de code qui a déclenché l'erreur. Dans Basic, les messages d'erreur n'affichent pas ces informations.

Consultez l'Aide sur les scripts Python de LibreOfficeDev pour plus d'informations sur les scripts Python avec LibreOfficeDev.

Édition de scripts Python dans les EDI

Les conseils de saisie Python - relatifs aux méthodes et propriétés publiques des services ScriptForge - peuvent être obtenus à partir des EDI qui prennent en charge cette fonctionnalité. Visuellement, lors de l'édition d'un script utilisateur :

le survol d'une instance d'objet, d'une méthode ou d'une propriété affiche sa description détaillée.
un « . » après une instance d’objet affiche une liste déroulante répertoriant toutes les interfaces disponibles.
les crochets après un nom de méthode démarrent la complétion du code en affichant ses arguments.

Des aides à la saisie sont affichés lors de l'édition de méthodes et de propriétés avec des lettres majuscules/minuscules appropriées.

Exécution de scripts Python sur LibreOfficeDev

Selon ce que vous souhaitez réaliser, vous pouvez choisir l'une des approches suivantes pour exécuter des scripts Python dans LibreOfficeDev :

Exécuter des scripts dans le processus LibreOfficeDev actuel : les scripts Python sont exécutés depuis le processus LibreOfficeDev en utilisant le menu Outils - Macros - Exécuter la macro ou l'extension APSO pour appeler des scripts utilisateurs stockés dans le dossier scripts Python. Vous pouvez également utiliser le shell APSO Python pour exécuter de manière interactive des scripts Python.
Exécuter des scripts séparément du processus LibreOfficeDev : Les scripts Python sont exécutés à partir d'un processus externe qui se connecte à un processus LibreOfficeDev en cours à l'aide d'un pipe ou d'un socket.

Si vous prévoyez d'exécuter des scripts depuis le processus LibreOfficeDev, il est recommandé d'installer l'extension APSO (Alternative Script Organizer for Python). En revanche, pour développer des scripts Python en dehors de LibreOfficeDev, vous pouvez utiliser votre EDI Python préféré.

Exécution de scripts depuis le processus LibreOfficeDev

Utilisation de l'extension APSO

Le moyen le plus simple de démarrer avec les scripts Python dans LibreOfficeDev consiste à installer l'extension APSO. Après l'avoir installée, ouvrez n'importe quel composant LibreOfficeDev et allez dans Outils - Macros - Organiser les scripts Python.

Dans la fenêtre principale d'APSO, allez dans Menu - Python Shell.

Vous pouvez également ouvrir APSO en utilisant le raccourci par défaut Alt+Maj+F11.

Vous pouvez maintenant commencer à saisir des commandes Python et le shell imprimera la sortie correspondante après l'exécution de chaque ligne de code.

Pour commencer à utiliser la bibliothèque ScriptForge, vous devez importer la méthode CreateScriptService, avec laquelle vous pourrez accéder aux services fournis par la bibliothèque. L'exemple ci-dessous utilise le service Basic pour afficher une boîte de message.


        from scriptforge import CreateScriptService
        bas = CreateScriptService("Basic")
        bas.MsgBox("Hello!")

Pour exécuter l'exemple ci-dessus, saisissez chaque ligne dans le shell Python, une par une, en appuyant sur la touche Entrée après avoir saisi chaque ligne de code.

Vous pouvez maintenant commencer à exécuter des commandes Python à l'aide de l'un des services ScriptForge. Par exemple, l'extrait de code ci-dessous utilise le service UI pour créer un document Writer vierge.


        ui = CreateScriptService("UI")
        doc = ui.CreateDocument("Writer")

Création de fichiers de script Python

Vous pouvez créer vos propres fichiers Python et les modifier avec votre éditeur de texte préféré. Vous pourrez ensuite les appeler à partir de n'importe quel composant LibreOfficeDev.

La première étape consiste à localiser l'emplacement de stockage de vos scripts utilisateur. Pour cela, reportez-vous à la page d'aide Organisation et emplacement des scripts Python.

Vous pouvez maintenant créer un fichier texte dans votre dossier de scripts utilisateur Python, par exemple mon_script.py, et commencer à saisir vos scripts.

Voici un exemple simple qui récupère la valeur numérique d'une cellule Calc et l'incrémente de 1. Il suffit de saisir le code suivant dans le fichier mon_script.py.


    from scriptforge import CreateScriptService
    doc = CreateScriptService("Calc")
    
    def increment_cell(args=None):
        value = doc.GetValue("A1")
        value += 1
        doc.SetValue("A1", value)
    
    g_exportedScripts = (increment_cell, )

Cet exemple crée la fonction increment_cell. Notez que g_exportedScripts est un tuple indiquant les fonctions qui seront affichées dans LibreOfficeDev en tant que scripts utilisateur.

Pour exécuter ce script à l'intérieur d'un document Calc :

Créez ou ouvrez un fichier Calc.
Saisissez une valeur numérique dans la cellule "A1" de la feuille active.
Allez dans Outils - Macros - Exécuter des macros .
Choisissez Mes macros - mon_script dans le sélecteur de bibliothèques. Puis choisissez la fonction increment_cell dans la liste Nom des macros.
Cliquez sur Exécuter. Notez que la valeur de la cellule "A1" a été incrémentée de 1.

Vous pouvez également utiliser APSO pour exécuter des scripts Python de la même manière :

Ouvrez d'abord APSO en allant dans Outils - Macros - Organiser les scripts Python.
Dans la liste des macros, naviguez jusque Mes macros - mon_script - increment_cell.
Cliquez sur Exécuter.

Exécution de scripts séparément du processus LibreOfficeDev

Déterminer le chemin d'installation

La première étape pour exécuter des scripts depuis un processus distinct consiste à trouver le dossier où LibreOfficeDev est installé. Il y a plusieurs façons de procéder, mais ScriptForge offre une solution rapide pour identifier votre chemin d'installation. Pour cela, ouvrez le shell Python d'APSO et saisissez :


      from scriptforge import CreateScriptService
      fs = CreateScriptService("FileSystem")
      fs.FileNaming = "SYS"
      inst_dir = fs.InstallFolder
      print(inst_dir)

Le résultat du code ci-dessus correspond au répertoire racine où LibreOfficeDev est installé. Vous devez maintenant ajouter le sous-dossier « program » au chemin résultant. Il s'agit du répertoire racine à partir duquel vous exécuterez les scripts Python depuis un processus distinct.

Par exemple, supposez que vous obtenez /usr/lib/libreoffice/ comme résultat de l'exécution du code Python ci-dessus. Vous devez alors considérer /usr/lib/libreoffice/program comme le chemin pour exécuter les scripts Python.

Démarrez LibreOfficeDev avec les paramètres pipe ou socket

Pour exécuter des scripts Python à partir d'un processus séparé, vous devez démarrer LibreOfficeDev avec quelques options supplémentaires qui spécifient le nom du pipe ou le nom d'hôte et le port par lesquels le processus externe communiquera avec le processus du composant LibreOfficeDev.

Ouvrez l'invite de commandes de votre système d'exploitation, naviguez jusqu'au dossier du programme de votre répertoire d'installation LibreOfficeDev et saisissez :

On Linux or macOS:

libreoffice --accept='pipe,name=aPipeName;urp;'

Sous Windows :

soffice.exe --accept='socket,host=localhost,port=2021;urp;'

as a Flatpak:

flatpak run org.libreOffice.LibreOffice accept='socket,host=localhost,port=2021;urp;'

Chacune des commandes ci-dessus démarrera LibreOfficeDev avec un canal de communication ouvert afin que d'autres processus puissent échanger des messages avec lui.

Notez que l'exemple précédent ouvre le centre de démarrage LibreOfficeDev. Si vous souhaitez ouvrir un composant spécifique, par exemple Writer, vous pouvez ajouter l'option --writer à la commande, comme suit.

./soffice --writer --accept='socket,host=localhost,port=2021;urp;'

Notez les paramètres name, ou host et port, qui dans cet exemple sont respectivement aPipeName, ou localhost et 2021.

Exécuter un shell Python externe

Lancez l'interpréteur Python depuis le dossier program situé dans votre répertoire d'installation LibreOfficeDev. Suivez les étapes ci-dessus pour savoir comment trouver votre répertoire d'installation.

On Linux or macOS:

$ cd /usr/lib/libreoffice/program

$ python

Sous Windows :

$ cd C:\\Program Files\\LibreOffice\\program\

$ python.exe

Cela ouvrira le shell Python et vous pourrez commencer à saisir des commandes qui seront exécutées par LibreOfficeDev. Mais vous devez d'abord configurer la connexion pipe ou socket. L'instruction ScriptForge() ci-dessous doit précéder le premier appel à CreateScriptService().

Exécutez l'un des deux :


   from scriptforge import ScriptForge, CreateScriptService
   ScriptForge(pipe='aPipeName')


    from scriptforge import ScriptForge, CreateScriptService
    ScriptForge(hostname='localhost', port=2021)

Lisez la section Configuration de PYTHONPATH ci-dessous en cas d'erreurs lors de l'import de scriptforge.py ou uno.py.

La seconde ligne de code ci-dessus définit les paramètres pipe ou host et port de façon à ce que le shell Python puisse communiquer avec un processus LibreOfficeDev en cours ouvert avec les mêmes paramètres pipe ou socket.

Vous pouvez désormais exécuter d'autres commandes Python qui pourront communiquer avec le processus LibreOfficeDev. Par exemple :


    ui = CreateScriptService("UI")
    bas = CreateScriptService("Basic")
    doc = ui.OpenDocument("~/Documents/myFile.ods")
    bas.MsgBox(doc.DocumentType)

Paramétrer PYTHONPATH

En fonction de la configuration de votre système d'exploitation, vous devrez définir la variable d'environnement PYTHONPATH afin d'importer la bibliothèque scriptforge.py, ce qui nécessite à son tour d'importer la bibliothèque uno. py.

Utilisez l'outil de recherche de fichiers de votre système d'exploitation pour déterminer le répertoire où se trouvent ces deux fichiers.

Par exemple, sur une installation Ubuntu par défaut, les deux fichiers peuvent se trouver à l'emplacement :

scriptforge.py: situé dans /usr/lib/libreoffice/program
uno.py: situé dans /usr/lib/python3/dist-packages

Dans ce cas, définissez la variable d'environnement PYTHONPATH comme suit avant de démarrer l'interpréteur Python :

export PYTHONPATH=/usr/lib/libreoffice/program:/usr/lib/python3/dist-packages

L'emplacement de ces fichiers sera différent pour chaque système d'exploitation et méthode d'installation de LibreOfficeDev.

La bibliothèque ScriptForge

Aide des scripts LibreOfficeDev Python

Démarrage du logiciel LibreOfficeDev avec des paramètres