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

• Argomenti: tutte le parole chiave passate ai metodi come argomenti sono in formato tuttominuscolo.

• 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.

Esecuzione di script Python in LibreOffice

A seconda di quello che volete ottenere, potete 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. Potete usare anche la shell Python dell'estensione APSO per eseguire interattivamente gli script.

• Esecuzione degli script separatamente dal processo di LibreOffice: gli script in Python sono eseguiti da un processo esterno che, usando un socket, si connette al processo di LibreOffice in esecuzione.

Se pensate 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, potete scegliere la vostra 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, aprite qualsiasi componente di LibreOffice e accedete a Strumenti - Macro - Organizza macro - Python.

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

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

Ora potete iniziare a digitare i comandi in Python e la shell visualizzerà l'output corrispondente dopo l'esecuzione di ogni riga di codice.

Per iniziare ad usare la libreria ScriptForge, dovrete importare il metodo CreateScriptService, con il quale potrete accedere ai servizi forniti dalla libreria. Gli esempi seguenti usano il servizio Basic per visualizzare una finestra con un messaggio di errore.

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

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

Ora potrete iniziare ad 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 contenti script di Python

Potete creare il vostri file in Python e modificarli con il vostro editor di testo preferito. In seguito potete richiamarli da qualsiasi componente di LibreOffice.

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

Ora potete creare un file di testo all'interno della vostra cartella degli script in Python, ad esempio sf_test.py, e iniziare a scrivere il vostro script.

Il prossimo è un semplice esempio che ricava un valore numerico da una cella di Calc e lo aumenta di 1. È sufficiente digitare il codice seguente nel file 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, )
  

Questo esempio crea la funzione increment_cell. Fate 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:

1. Create o aprite un file Calc.

2. Inserite dei valori numerici nella cella "A1" del foglio corrente.

3. Accedete a Strumenti - Macro - Esegui macro .

4. Selezionate Macro personali - sf_test all'interno del selettore delle macro. Quindi scegliete la funzione increment_cell dall'elenco Nome macro.

5. Fate clic su Esegui. Osservate come il valore nella cella "A1" venga incrementato di 1.

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

1. Innanzitutto aprite APSO accedendo a Strumenti - Macro - Organizza marco - Python.

2. Nell'elenco delle macro spostatevi su Macro personali - sf_test - increment_cell.

3. Fate clic su Execute.

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 aprite la shell di Python di APSO e digitate:

    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 dovrete aggiungere la sottocartella "program" al percorso ottenuto come risultato. Questa è la cartella base dalla quale eseguirete gli script in Python da un processo separato.

Per esempio, supponete di ottenere /usr/lib/libreoffice/ come risultato dell'esecuzione del precedente codice Python. Dovrete quindi considerare /usr/lib/libreoffice/program quale percorso di esecuzione dei vostri script in Python.

Avvio di LibreOffice con le impostazioni del socket

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

Aprite il prompt dei comandi del vostro sistema operativo, passate alla cartella program all'interno della vostra cartella di installazione di LibreOffice e digitate:

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

Il comando precedente avvierà LibreOffice con un canale di comunicazione aperto, in modo che altri processi possano scambiare messaggi con esso.

Fate attenzione che l'esempio precedente apre il centro di avvio di LibreOffice. Se volete aprire un componente specifico, ad esempio Writer, potete aggiungere al comando l'opzione --writer, come segue.

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

Annotate i parametri host e port, che in questo esempio sono rispettivamente localhost e 2021.

Eseguire una shell di Python esterna

Avviate la shell di Python dalla cartella program all'interno del percorso di installazione di LibreOffice. Per capire come individuare il percorso di installazione seguite i passaggi precedenti.

In Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

In Windows:

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

$ python.exe

Questo aprirà la shell di Python e potrete iniziare a digitare i comandi che saranno eseguiti da LibreOffice. Ma prima dovrete impostare la connessione con il socket.

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

Leggere più avanti la sezione Impostazione di PYTHONPATH in caso di errori d'importazione di scriptforge.py o di uno.py.

La seconda riga del codice qui sopra definisce le impostazioni host e port in modo che la shell di Python possa comunicare con il processo di LibreOffice in esecuzione aperto con le stesse impostazioni del socket.

Ora potete 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'istallazione 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 di Python:

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

La posizione di questi file sarà diversa per ogni sistema operativo e metodo di installazione di LibreOffice.