Creazione di script in Python con ScriptForge

Differenze tra Basic e Python

La libreria ScriptForge è disponibile sia per Basic che per Python. La maggior parte dei servizi, metodi e proprietà funziona in modo identico in entrambi i linguaggi di programmazione. Tuttavia, a causa delle differenze di funzionamento tra i due linguaggi, gli utenti di ScriptForge devono conoscere alcune caratteristiche della libreria quando utilizzano Python:

Nomi dei metodi e delle proprietà: in Python, tutti i metodi e le proprietà possono essere usati nei formati tuttominuscolo, InizialiMaiuscole o camelCase (notazione a cammello).
Arguments: All keyword arguments passed on to methods are lowercased.
Date: tutti gli oggetti data sono passati e restituiti come oggetti datetime.datetime nativi di Python.
Matrici: le matrici unidimensionali sono passate e restituite come tuple (che sono oggetti immutabili). Le matrici bidimensionali sono passate e restituite come tuple di tuple.
None: la parola chiave None di Python è equivalente a Null, Empty o Nothing in Basic.
Oggetti UNO: tutte le strutture UNO vengono scambiate tra Basic e Python senza alcuna modifica.
Debug: ogni volta che si verifica un errore negli script di Python che usano ScriptForge, il messaggio di errore fornito dallo stack di esecuzione di Python visualizza la riga di codice che ha causato l'errore. In Basic i messaggi di errore non visualizzano questa informazione.

Per maggiori informazioni sulla creazione di script in Python con LibreOfficeDev visitate la Guida agli script Python di LibreOfficeDev.

Modificare gli script Python in una IDE

Durante la digitazione in Python è possibile ottenere dei suggerimenti (relativi ai metodi e alle proprietà pubbliche dei servizi di ScriptForge) nelle IDE che supportano tali elementi. Visivamente, mentre si modifica uno script definito dall'utente:

posizionandosi sull'istanza di un oggetto, un metodo o una proprietà, viene visualizzata la sua descrizione dettagliata.
un "." dopo l'istanza di un oggetto visualizza un casella di scelta che elenca tutte le interfacce disponibili.
delle parentesi dopo il nome di un metodo avviano il completamento automatico del codice visualizzando i suoi argomenti.

I suggerimenti per la digitazione sono visualizzati quando si modificano i metodi e le proprietà usando le lettere maiuscole o minuscole in modo appropriato.

Esecuzione di script Python in LibreOfficeDev

A seconda di quello che si vuole ottenere, è possibile scegliere uno dei seguenti approcci per eseguire script Python in LibreOfficeDev:

Esecuzione di script all'interno del processo corrente di LibreOfficeDev: gli script in Python sono eseguiti all'interno del processo di LibreOfficeDev usando il menu Strumenti - Macro - Esegui macro o l'estensione APSO per chiamare gli script dell'utente memorizzati nella cartella degli script in Python. È possibile usare anche la shell Python dell'estensione APSO per eseguire interattivamente gli script.
Run Scripts separately from the LibreOfficeDev process: Python scripts are executed from an external process that connects to an ongoing LibreOfficeDev process using a pipe or a socket.

Se si pensa di eseguire gli script dall'interno del processo di LibreOfficeDev, consigliamo l'installazione dell'estensione APSO (Alternative Script Organizer for Python). E comunque, per sviluppare script in Python all'esterno di LibreOfficeDev, è possibile scegliere la propria IDE per Python preferita.

Esecuzione di script dall'interno del processo di LibreOfficeDev

Usando l'estensione APSO

Il modo più semplice per iniziare a programmare script in Python in LibreOfficeDev è quello di installare l'estensione APSO. Dopo averla installata, aprire qualsiasi componente di LibreOfficeDev e accedere a Strumenti - Macro - Organizza macro - Python.

Nella finestra principale di APSO accedere a Menu - Python Shell.

In alternativa è possibile aprire APSO usando la combinazione di tasti predefinita Alt + Maiusc + F11.

Ora si può iniziare a digitare i comandi in Python; la shell visualizzerà l'output corrispondente dopo l'esecuzione di ogni riga di codice.

Per iniziare a usare la libreria ScriptForge è necessario importare il metodo CreateScriptService, con il quale si potrà accedere ai servizi forniti dalla libreria. Gli esempi seguenti usano il servizio Basic per visualizzare una finestra informativa.


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

Per eseguire l'esempio precedente, inserire una riga alla volta nella shell di Python, premendo il tasto Invio dopo avere digitato ogni singola riga.

Ora sarà possibile iniziare a eseguire i comandi Python usando qualsiasi servizio di ScriptForge. Per esempio, il seguente frammento di codice usa il servizio UI per creare un documento Writer vuoto.


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

Creazione di file contenenti script di Python

È possibile creare i propri file in Python e modificarli con l'editor di testo preferito. Li si potrà richiamare in seguito da qualsiasi componente di LibreOfficeDev.

Il primo passo consiste nell'individuare dove sono memorizzati i propri script utente. A tale scopo fare riferimento alla pagina della guida in linea Organizzazione e posizione degli script Python.

Now you can create a text file inside your Python user scripts folder, for instance my_script.py, and start typing your scripts.

Next is a simple example that gets the numeric value from a Calc cell and increments it by 1. Simply type the following code into my_script.py file.


    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, )

Questo esempio crea la funzione increment_cell. Fare attenzione che g_exportedScripts è una tupla che indica quali funzioni saranno visualizzate in LibreOfficeDev come script dell'utente.

Per eseguire questo script all'interno di un documento di Calc:

Creare o aprire un file Calc.
Inserire dei valori numerici nella cella "A1" del foglio corrente.
Accedere a Strumenti - Macro - Esegui macro .
Choose My Macros - my_script in the library selector. Then choose the increment_cell function under the Macro Name list.
Fare clic su Esegui. Osservare come il valore nella cella "A1" venga incrementato di 1.

È possibile usare anche APSO per eseguire gli script in Python in maniera simile:

Innanzitutto aprire APSO accedendo a Strumenti - Macro - Organizza marco - Python.
In the macro list, navigate to My Macros - my_script - increment_cell.
Fare clic su Esegui.

Eseguire gli script separatamente dal processo di LibreOfficeDev

Determinare il percorso di installazione

Il primo passo per eseguire degli script da un processo separato consiste nell'individuare la cartella in cui è installato LibreOfficeDev. Esistono diversi possibili metodi, ma ScriptForge fornisce un sistema immediato per identificare il percorso di installazione. A tale scopo aprire la shell di Python di APSO e digitare:


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

L'output del codice precedente è la cartella base in cui è installato LibreOfficeDev. Ora bisognerà aggiungere la sottocartella "program" al percorso ottenuto come risultato. Questa è la cartella base dalla quale si eseguiranno gli script in Python da un processo separato.

Si supponga, per esempio, di ottenere /usr/lib/libreoffice/ come risultato dell'esecuzione del precedente codice Python. Bisognerà quindi considerare /usr/lib/libreoffice/program quale percorso di esecuzione dei propri script in Python.

Start LibreOfficeDev with pipe or socket settings

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

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

On Linux or macOS:

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

In 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;'

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

Note that the previous example opens LibreOfficeDev 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 name, or host and port parameters, which in this example are aPipeName, or localhost and 2021, respectively.

Eseguire una shell di Python esterna

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

On Linux or macOS:

$ cd /usr/lib/libreoffice/program

$ python

In 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 LibreOfficeDev. But first you need to set up the pipe or the socket connection. The ScriptForge() statement below must precede the very first call to CreateScriptService().

Run either:


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


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

Read the section Setting PYTHONPATH below in case of errors importing scriptforge.py or uno.py.

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

Ora è possibile eseguire altri comandi di Python e questi saranno in grado di comunicare con il processo di LibreOfficeDev. Per esempio:


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

Setting PYTHONPATH

A seconda della configurazione del proprio sistema operativo sarà necessario impostare la variabile d'ambiente PYTHONPATH al fine di importare la libreria scriptforge.py, che a sua volta richiede l'importazione della libreria uno.py.

Usare lo strumento di ricerca dei file del sistema operativo per determinare in quale cartella sono situati questi due file.

Per esempio, in un'installazione predefinita di Ubuntu entrambi i file si trovano in:

scriptforge.py: si trova in /usr/lib/libreoffice/program
uno.py: si trova in /usr/lib/python3/dist-packages

In this case, set the environment variable PYTHONPATH as follows before starting the Python interpreter:

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

The location of these files will be different for each operating system and LibreOfficeDev installation method.

La libreria ScriptForge

Guida agli script Python di LibreOfficeDev

Avviare il software LibreOfficeDev con parametri