Come eseguire script Python nelle macro di LibreOffice Calc

Sì. LibreOffice Calc può eseguire codice Python come macro all'interno del processo di LibreOffice, e una macro di LibreOffice Basic può anche richiamare una funzione Python tramite il framework di scripting di LibreOffice. Se il tuo obiettivo è leggere o modificare le celle nel foglio di calcolo aperto, una macro Python in-process è solitamente il punto di partenza più semplice. Utilizza una chiamata da Basic a Python quando una macro Basic esistente deve delegare un'attività a una funzione Python riutilizzabile.

Questi approcci sono diversi dall'avvio di un normale script Python di sistema tramite un comando shell. Un normale processo Python esterno non riceve automaticamente l'oggetto documento di Calc. Per accedere alla cartella di lavoro, è necessario eseguire una macro Python tramite LibreOffice o connettere esplicitamente un processo esterno a un'istanza di LibreOffice tramite UNO.

Cosa significa "eseguire Python all'interno di una macro di Calc"?

LibreOffice supporta diversi linguaggi di scripting tramite il suo framework di scripting. In una macro Python, LibreOffice fornisce un oggetto contesto UNO che consente allo script di accedere al documento corrente e ai relativi fogli. Una macro Python è una funzione all'interno di un .pymodulo; la tupla del modulo g_exportedScriptsidentifica le funzioni che LibreOffice deve visualizzare come macro eseguibili.

Una macro Python può essere eseguita autonomamente dal menu macro di Calc. Non è necessario che venga richiamata da Basic. Se si dispone già di una macro Basic e si desidera che richiami Python, Session.ExecutePythonScriptè possibile utilizzare il provider di script di LibreOffice o il più recente servizio ScriptForge per fare da ponte tra i due linguaggi.

Quale approccio dovresti scegliere?

• Utilizza direttamente una macro Python quando l'attività è prevalentemente in Python e richiede il documento Calc corrente. In questo modo si evita un passaggio di linguaggio e il debug risulta più semplice se eseguito in un unico script.
• È opportuno richiamare Python da Basic quando si dispone già di codice Basic, pulsanti o eventi del documento che devono rimanere al loro posto e si desidera che una funzione di supporto Python esegua un calcolo o un'operazione sui dati specifica.
• Utilizza un processo Python esterno quando hai bisogno di un ambiente di sviluppo separato o di pacchetti Python non inclusi in LibreOffice. Configura una connessione UNO esplicita; non dare per scontato che uno script avviato da terminale possa accedere al foglio di calcolo aperto.

Ad esempio, un piccolo strumento per la pulizia di un foglio di calcolo può essere scritto interamente come una macro Python. Se un pulsante Basic esistente esegue già un report, è possibile mantenere la macro del pulsante e farla richiamare una funzione Python che calcola il totale del report.

Come si crea una macro Python per modificare le celle di Calc?

LibreOffice memorizza gli script Python personali nel profilo utente, gli script a livello di applicazione nella directory di installazione e gli script di documento insieme al documento stesso. Per un primo test, uno script personale è comodo perché è disponibile in qualsiasi documento LibreOffice aperto dallo stesso utente. Tuttavia, non viene condiviso con un file ODS, quindi un altro utente non lo riceverà automaticamente insieme al foglio di calcolo.

Nella Guida di LibreOffice, alla voce "Organizzazione e posizione degli script Python", è possibile trovare la cartella degli script Python personali per il proprio sistema. Le posizioni più comuni includono [ percorso %APPDATA%\LibreOffice\4\user\Scripts\python] su Windows e [percorso ~/.config/libreoffice/4/user/Scripts/python] su Linux. Il percorso effettivo può variare; si consiglia di utilizzare la posizione documentata per la propria installazione anziché creare una seconda directory di profilo a caso.

Crea un file con questo nome calc_tools.pynella cartella degli script Python personali, quindi aggiungi questo semplice esempio:

def double_a1(args=None):
    doc = XSCRIPTCONTEXT.getDocument()
    sheet = doc.getCurrentController().getActiveSheet()

    source = sheet.getCellRangeByName("A1")
    target = sheet.getCellRangeByName("B1")
    target.setValue(source.getValue() * 2)

g_exportedScripts = (double_a1,)

Questa funzione legge il valore numerico nella cella A1 del foglio attivo e ne scrive il doppio nella cella B1. XSCRIPTCONTEXTViene fornita a una macro Python di LibreOffice in fase di esecuzione; non è una normale variabile globale Python quando lo stesso file viene aperto al di fuori di LibreOffice. La funzione pubblica è elencata in g_exportedScriptsmodo da apparire nel selettore di macro.

Salva il file, quindi apri o torna a Calc e scegli Strumenti > Macro > Esegui macro . A seconda della versione di LibreOffice o della traduzione della piattaforma, l'etichetta del menu potrebbe essere singolare. Seleziona Le mie macro > calc_tools > double_a1 ed eseguila. Inserisci prima un numero in A1, quindi verifica che B1 contenga il valore raddoppiato. Se il modulo non viene visualizzato, verifica che l'estensione del file sia .py .py, che il file si trovi nella cartella Python del profilo corretto e che il supporto per gli script Python sia installato. Riavviare LibreOffice dopo aver aggiunto un nuovo modulo può aiutare ad aggiornare l'elenco degli script.

Come può una macro Basic richiamare una funzione Python?

Per effettuare una chiamata da Basic a Python, inserisci un modulo Python nella cartella degli script personali e richiama la sua funzione tramite Sessionil servizio di ScriptForge. Questo esempio somma due valori in Python e scrive il risultato nella cella B1 del foglio Calc corrente.

In calc_tools.py, definisci la funzione:

def add_values(first, second):
    return float(first) + float(second)

g_exportedScripts = (add_values,)

Quindi crea una macro di base in Calc e usala:

Sub RunPythonHelper()
    Dim session As Object
    Dim result As Variant
    Dim sheet As Object

    session = CreateScriptService("Session")
    result = session.ExecutePythonScript( _
        session.SCRIPTISPERSONAL, _
        "calc_tools.py$add_values", _
        12, 30)

    sheet = ThisComponent.CurrentController.getActiveSheet()
    sheet.getCellRangeByName("B1").setValue(result)
End Sub

Eseguire RunPythonHelperdal selettore di macro Basic. Se la chiamata ha esito positivo, B1 dovrebbe visualizzare 42. Il riferimento allo script segue il formato module.py$function_name; per un modulo in una sottocartella o in un'altra posizione di archiviazione, utilizzare la sintassi e la costante di posizione documentate per quella versione di ScriptForge. Mantenere gli argomenti e i valori di ritorno su tipi di dati che entrambi i linguaggi possono rappresentare in modo pulito, come numeri, stringhe e sequenze semplici.

CreateScriptServiceLe funzioni di supporto per le sessioni di ScriptForge documentate sono disponibili nelle versioni moderne di LibreOffice, ma i nomi dei menu e i componenti inclusi possono differire nelle versioni precedenti o in quelle distribuite tramite pacchetti. Se questo servizio non è disponibile, utilizzare il metodo del provider di script UNO documentato da LibreOffice, che ottiene un XScriptURI da uno script e lo richiama. Evitare di copiare un frammento di codice per una posizione di macro diversa senza modificarne l'impostazione della posizione.

Il codice Python deve essere personale, condiviso o incorporato?

Per un flusso di lavoro di team, prima di creare una cartella di lavoro basata su una macro personale, è necessario stabilire come i destinatari otterranno e considereranno attendibile il codice. Se la logica Python deve accompagnare il foglio di calcolo, è opportuno testare l'archiviazione delle macro e le richieste di sicurezza del documento sulle stesse versioni di LibreOffice utilizzate dai destinatari. Per la distribuzione gestita, un amministratore può creare pacchetti di script per gli utenti o distribuire un'estensione seguendo i normali controlli software dell'organizzazione.

Perché la macro potrebbe mancare o non funzionare?

• L'opzione o il modulo Python non è presente. In alcune distribuzioni GNU/Linux, il framework di scripting Python di LibreOffice è un pacchetto opzionale. Se le macro Python non compaiono nella finestra di dialogo delle macro, consulta le istruzioni di installazione di LibreOffice nella tua distribuzione.
• Lo script è stato salvato nel profilo errato. LibreOffice può utilizzare più profili utente. Verifica il percorso del profilo per l'installazione in esecuzione e salva il modulo nella relativa Scripts/pythondirectory.
• La funzione non è esportata. Aggiungila g_exportedScriptsper una funzione che intendi eseguire dal selettore di macro. Assicurati che la sintassi della tupla includa la virgola finale per una tupla con un solo elemento.
• Lo script viene eseguito al di fuori di LibreOffice. XSCRIPTCONTEXT Esiste per una macro avviata da LibreOffice, non quando lo stesso file viene avviato con il pythoncomando di sistema. Utilizzare l'esecutore di macro o configurare una connessione UNO documentata.
• La sicurezza delle macro blocca il codice incorporato. Esamina le impostazioni di sicurezza delle macro di LibreOffice e abilita il codice solo da fonti attendibili. Abbassare il livello di sicurezza globale non è una scorciatoia efficace per la risoluzione dei problemi.
• Un modulo importato non può vedere il contesto del documento. I documenti di LibreOffice XSCRIPTCONTEXTnon vengono passati ai moduli importati. Passa l'oggetto documento o foglio necessario alle funzioni di supporto invece di aspettarti che i moduli importati leggano quello globale.
• Non viene visualizzato alcun output nella console. L'output standard di Python non è disponibile quando si esegue una macro dal menu Strumenti > Macro. Per ottenere un feedback, è possibile scrivere il risultato in una cella, utilizzare un servizio di dialogo di LibreOffice o registrare l'output in un percorso file specifico.

Come si verifica il risultato in modo sicuro?

Eseguite un test con una copia del foglio di calcolo e un input noto. Verificate che la macro Python sia presente nell'esecutore, eseguite il test una volta e confrontate la cella di output con un risultato calcolato manualmente. Per una chiamata da Basic a Python, testate un input semplice e verificate che il valore restituito venga scritto nel foglio previsto. Evitate di iniziare con script che eliminano fogli, sovrascrivono intervalli di grandi dimensioni o eseguono comandi del sistema operativo.

Una volta che il test funziona, decidete come installare lo script sugli altri computer e documentate le librerie Python necessarie o i presupposti relativi alla versione di LibreOffice. L'ambiente Python integrato in LibreOffice è quello utilizzato per le macro in-process; i pacchetti installati per un interprete Python di sistema separato potrebbero non essere disponibili. Se avete bisogno di pacchetti da un altro interprete, utilizzate l'approccio external-process/UNO e configurate la connessione in modo specifico.

Riferimenti ufficiali

• Guida di LibreOffice: Creazione di script Python con ScriptForge
• Guida di LibreOffice: Chiamare script Python da Basic
• Guida di LibreOffice: Programmazione con script Python
• Guida di LibreOffice: Organizzazione e posizione degli script Python
• Guida di LibreOffice: Lettura e scrittura di valori in intervalli
• SDK di LibreOffice: interfaccia XScript