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 LibreOffice visitate la Guida agli script Python di LibreOffice.

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 LibreOffice

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

Esecuzione di script all'interno del processo corrente di LibreOffice: gli script in Python sono eseguiti all'interno del processo di LibreOffice 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.
Esecuzione di script separatamente dal processo di LibreOffice: gli script in Python vengono eseguiti da un processo esterno che si collega a un processo di LibreOffice in esecuzione usando una pipe o un socket.

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

Esecuzione di script dall'interno del processo di LibreOffice

Usando l'estensione APSO

Il modo più semplice per iniziare a programmare script in Python in LibreOffice è quello di installare l'estensione APSO. Dopo averla installata, aprire qualsiasi componente di LibreOffice 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 LibreOffice.

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.

Ora è possibile creare un file di testo all'interno della cartella degli script Python dell'utente, per esempio mio_script.py, e iniziare a scrivere script personalizzati.

Quello che segue è un semplice esempio che recupera il valore numerico da una cella di Calc e lo incrementa di 1. È sufficiente inserire il codice seguente nel file mio_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, )

Questo esempio crea la funzione increment_cell. Fare attenzione che g_exportedScripts è una tupla che indica quali funzioni saranno visualizzate in LibreOffice 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 .
Scegliere Macro personali - mio_script nel selettore della libreria. Quindi scegliere la funzione increment_cell nell'elenco Nome Macro.
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.
Nell'elenco delle marco, spostarsi su Macro personali - mio_script - increment_cell.
Fare clic su Esegui.

Eseguire gli script separatamente dal processo di LibreOffice

Determinare il percorso di installazione

Il primo passo per eseguire degli script da un processo separato consiste nell'individuare la cartella in cui è installato LibreOffice. 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 LibreOffice. 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.

Avviare LibreOffice con le impostazioni pipe o socket

Per eseguire gli script in Python da un processo separato, è necessario avviare LibreOffice con alcune opzioni aggiuntive che specificano il nome della pipe o dell'host e la porta tramite la quale il processo esterno comunicherà con il processo del componente di LibreOffice.

Aprire il prompt dei comandi del sistema operativo, passare alla cartella "program" all'interno della cartella di installazione di LibreOffice e digitare:

Su Linux e macOS:

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

In Windows:

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

come Flatpak:

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

Uno qualsiasi dei comandi precedenti avvierà LibreOffice con un canale di comunicazione aperto, in modo che altri processi possano scambiare messaggi con esso.

Va precisato che l'esempio precedente apre il Centro di avvio di LibreOffice. Se si desidera aprire uno specifico componente, per esempio Writer, è possibile aggiungere l'opzione --writer al comando, come mostrato di seguito.

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

È necessario annotare i parametri name, host e port, che in questo esempio sono rispettivamente aPipeName, localhost e 2021.

Eseguire una shell di Python esterna

Avviare l'interprete di Python all'interno della cartella program nel percorso di installazione di LibreOffice. Seguire i passi sopra riportati per imparare a trovare il percorso di installazione.

Su Linux o macOS:

$ cd /usr/lib/libreoffice/program

$ python

In Windows:

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

$ python.exe

Questo aprirà l'interprete Python e sarà possibile iniziare a digitare i comandi che saranno eseguiti da LibreOffice. Prima però è necessario impostare la connessione tramite pipe o socket. L'istruzione ScriptForge() riportata sotto deve precedere la prima chiamata a CreateScriptService().

Eseguire uno tra:


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


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

Leggere la sezione Impostazione di PYTHONPATH qui sotto nel caso di errori nell'importazione di scriptforge.py o uno.py.

La seconda riga del codice qui sopra definisce le impostazioni pipe o host e port in modo che l'interprete Python possa comunicare con un processo di LibreOffice in esecuzione, aperto con le stesse impostazioni per la pipe o il socket.

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


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

Impostazione di 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 questo caso, impostare la variabile d'ambiente PYTHONPATH come segue, prima di avviare l'interprete Python:

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

Il percorso di questi file varia in base al sistema operativo e al metodo di installazione di LibreOffice.

La libreria ScriptForge

Guida agli script Python di LibreOffice

Avviare il software LibreOffice con parametri