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 : tous les arguments de mot-clé transmis aux méthodes sont en minuscules.

• 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 LibreOffice pour plus d'informations sur les scripts Python avec LibreOffice.

Exécution de scripts Python sur LibreOffice

En fonction de vos objectifs, vous pouvez choisir l'une des approches suivantes pour exécuter des scripts Python dans LibreOffice :

• Exécuter des scripts dans le processus LibreOffice actuel : les scripts Python sont exécutés depuis le processus LibreOffice 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 les scripts séparément du processus LibreOffice : les scripts Python sont exécutés à partir d'un processus externe qui se connecte à un processus LibreOffice actif à l'aide d'un socket.

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

Exécution de scripts depuis le processus LibreOffice

Utilisation de l'extension APSO

Le moyen le plus simple de démarrer avec les scripts Python dans LibreOffice consiste à installer l'extension APSO. Après l'avoir installée, ouvrez n'importe quel composant LibreOffice 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 LibreOffice.

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 sf_test.py, et commencer à taper vos scripts.

Voici un exemple simple qui obtient la valeur numérique d'une cellule Calc et l'incrémente de 1. Tapez simplement le code suivant dans le fichier sf_test.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 qui indique quelles fonctions seront affichées dans LibreOffice en tant que scripts utilisateur.

Pour exécuter ce script depuis un document Calc :

1. Créez ou ouvrez un fichier Calc.

2. Saisissez une valeur numérique dans la cellule "A1" de la feuille active.

3. Allez dans Outils - Macros - Exécuter des macros .

4. Choisissez Mes macros - sf_test dans le sélecteur de bibliothèque. Choisissez ensuite la fonction increment_cell sous la liste Nom de la macro.

5. 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 :

1. Ouvrez d'abord APSO en allant dans Outils - Macros - Organiser les scripts Python.

2. Dans la liste des macros, accédez à Mes macros - sf_test - increment_cell.

3. Cliquez sur Exécuter.

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

Déterminer le chemin d'installation

La première étape pour exécuter des scripts à partir d'un processus distinct consiste à rechercher le dossier dans lequel LibreOffice est installé. Il existe plusieurs façons de le faire, mais ScriptForge fournit un moyen rapide d'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)
  

La sortie du code ci-dessus est le répertoire de base dans lequel LibreOffice est installé. Vous devez maintenant ajouter le sous-dossier "program" au chemin résultant. Il s'agit du dossier de base à partir duquel vous exécuterez les scripts Python à partir d'un processus distinct.

Par exemple, supposons que vous obteniez /usr/lib/libreoffice/ comme résultat de l'exécution du code Python ci-dessus. Ensuite, vous devez considérer /usr/lib/libreoffice/program comme chemin pour exécuter vos scripts Python.

Démarrer LibreOffice avec les paramètres de socket

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

Ouvrez l'invite de commande de votre système d'exploitation, accédez au dossier du programme de votre répertoire d'installation LibreOffice et saisissez :

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

La commande ci-dessus démarrera LibreOffice 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 LibreOffice. Si vous souhaitez ouvrir un composant spécifique, par exemple Writer, vous pouvez ajouter l'indicateur --writer à la commande, comme suit.

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

Prenez note des paramètres host et port, qui dans cet exemple sont localhost et 2021, respectivement.

Exécution d'un shell Python externe

Démarrez le shell Python à partir du dossier program dans le chemin d'installation LibreOffice. Suivez les étapes ci-dessus pour savoir comment trouver le chemin d'installation.

Sous Linux/Mac OS :

$ cd /usr/lib/libreoffice/program

$ python

Sous Windows :

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

$ python.exe

Cela ouvrira le shell Python et vous pourrez maintenant commencer à saisir des commandes qui seront exécutées par LibreOffice. Mais vous devez d'abord configurer la connexion socket.

    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 deuxième ligne de code ci-dessus définit les paramètres host et port afin que le shell Python puisse communiquer avec un processus LibreOffice en cours ouvert avec les mêmes paramètres de socket.

Vous pouvez maintenant exécuter d'autres commandes Python et elles pourront communiquer avec le processus LibreOffice. 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 LibreOffice.