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 :

tip

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 :

tip

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.

tip

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.

For example, suppose you get /usr/lib/libreoffice/ as the result from running the Python code above. Then you need to consider /usr/lib/libreoffice/program as the path to run your Python scripts.

Start LibreOffice with socket settings

To run Python scripts from a separate process, you need to start LibreOffice with a few additional options that specify the hostname and port through which the external process will communicate with the LibreOffice component process.

Open the your operating system's command prompt, navigate to the program folder of your LibreOffice installation directory and type:

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

The command above will start LibreOffice with a communication channel open so that other processes can exchange messages with it.

Note that the previous example opens LibreOffice start center. If you want to open a specific component, for instance Writer, you can add the --writer flag to the command, as follows.

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

Take note of the host and port parameters, which in this example are localhost and 2021, respectively.

Running an External Python Shell

Start the Python shell from within the program folder inside your LibreOffice installation path. Follow the steps above to learn how to find your installation path.

On Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

On Windows:

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

$ python.exe

This will open the Python shell and now you can start typing commands that will be executed by LibreOffice. But first you need to set up the socket connection.


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

The second line of code above defines the host and port settings so that the Python shell can communicate with an ongoing LibreOffice process opened with the same socket settings.

Now you can run other Python commands and they will be able to communicate with the LibreOffice process. For example:


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