Macro/Elementi base per Python

TDF LibreOffice Document Liberation Project Blog comunitari Weblate Nextcloud Redmine Ask LibreOffice Donazione

• Pagina principale
• Sviluppo
• Design
• Controllo qualità
• Eventi
• Documentazione
• Sito web
• Traduzione
• Accessibilità
• Commerciale
• Inclusione
• Aiuto

• Macro
• Macro generiche
• Macro per Writer
• Macro per Calc
• Macro per Impress
• Macro per Draw
• Macro per Base
• Macro per Math
• Basic/Python

Introduzione

Questa pagina illustra i passaggi necessari a sviluppare macro per LibreOffice in Python all'interno di un Ambiente di Sviluppo Integrato (IDE). Vengono illustrate le configurazioni e le impostazioni di una serie ristretta di IDE libere e open source (FOSS). La scrittura e il debu di macro in Python all'interno di LibreOffice richiede unicamente l'estensione Alternative Python Script Organizer (APSO). Nel caso la usiate, potete saltare il contenuto del capitolo Avvio, Connessione & Arresto.

( ... Documenti, Configurazione, Ispezione degli oggetti... )

Pacchetti utili di LibreOffice

• LibreOffice 7.x
• LibreOffice Portable 6.x, winPenPack LibreOffice 6.x
• per Linux sono disponibili delle immagini AppImage, Flatpak o Snap

Per coloro che intendono analizzare la compatibilità:

• Apache OpenOffice 4.x, Apache OpenOffice Portable 4.x, winPenPack Apache OpenOffice 4.x
• OpenOffice.org Portable 3.2 (in francese)

Impostazione del progetto su di un'IDE

Ogni IDE richiede una configurazione o delle impostazioni differenti.

Geany

Gli interpreti di Python incorporati in Libreoffice o OpenOffice hanno bisogno di essere definiti esplicitamente nella finestra di dialogo Progetto - Proprietà - Bcompila di Geany:

• 

  MacOS - scheda Compila delle Proprietà del Progetto.

• 

  GNU/Linux - scheda Compila delle Proprietà del Progetto.

• 

  Windows - scheda Compila delle Proprietà del Progetto.

Valori di esempio:

• MacOS
  • P1. Compila = /Applications/LibreOffice.app/Contents/Resources/python -m py_compile "%f"
  • E1. Esegui = /Applications/LibreOffice.app/Contents/Resources/python "%f"
• Linux
  • P1. Compila = opt/openoffice4/program/python -m py_compile "%f"
  • E1. Esegui = opt/openoffice4/program/python "%f"
• Windows
  • comandi per Python
    • 1. Compila = "D:\Program Files\LibreOffice 5\program\python" -m py_compile "%f"
    • 2. Esegui = "D:\Program Files\LibreOffice 5\program\python"
  • Comandi per l'esecuzione
    • 1. Esegui = "D:\Program Files\LibreOffice 5\program\python" "%f"
    • 2. Test delle unità = "D:\Program Files\LibreOffice 5\program\python" -m unittest discover

Pyzo

La finestra di dialogo per la configurazione in Pyzo degli interpreti Python incorporati, richiamata dal menu Shell - Edit shell configurations...:

PyCharm

La configurazione dell'interprete Python per LibreOffice nella finestra delle impostazioni predefinite di PyCharm:

Cosa c'è in una Macro

Una macro in Python per LibreOffice può avere il seguente aspetto:

import uno
def my_1st_macro():
    # Non può essere eseguita direttamente in Anaconda, Geany, KDevelop, PyCharm o altre IDE.
    doc = XSCRIPTCONTEXT.getDocument()
    doc.getText().setString("Hello World!")

g_exportedScripts = my_1st_macro,

L'esecuzione di cui sopra richiede la creazione di un ponte tra la IDE e LibreOffice. Dopodichè gli oggetti UNO diventano accessibili.

Per addivenire a ciò può essere necessario eseguire cinque passaggi:

1. Avviare LibreOffice come servizio
2. Connettersi a un servizio
3. creare un Adattatore XSCRIPTCONTEXT
4. Eseguire la macro
5. Fermare il servizio LibreOffice

Anche se gli esempi disponibili su internet non fanno ricorso tutti questi passaggi, il loro studio mette in luce delle linee guida di programmazione dalle quali il modulo IDE_utils prende spunto al fine di integrarsi nelle IDE senza problemi.

Avvio, Connessione, Adattamento, Esecuzione e Arresto

La seguente tabella elenca alcuni esempi di macro in Python disponibili pubblicamente per (Libre/Open)Office Python. Viene indicato se fanno uso dei passaggi di Avvio, Connessione, Adattamento, Esecuzione e Arresto.

Esempi di codice

Descrizione	Avvio	Connessione	Adattamento	Esecuzione Debug	Arresto
a. modulo officehelper.py per LibreOffice e OpenOffice	x	x
b. Office.bridge.py Un poste per le IDE con un XSCRIPTCONTEXT rivisitato, Febbraio 2017 (in francese)		x	x	x
c. Programmazione orientata all'Interfaccia in OpenOffice / LibreOffice: automatizzare i lavori d'ufficio con macro in Python, Settembre 2013		x		x
d. unopy.py esecuzione di macro per LibreOffice con PyCharm, Gennaio 2014 (in giapponese)		x	x	x
e. ooutils.py - Avviare, Arrestare e Connettere OpenOffice con Python, Dicembre 2008	x	x		x	x
f. Python UNO-bridge, Ottobre 2008		x

Abilitazione dell'IDE

Sulla base di queste risorse, i requisiti per l'abilitazione di Python nelle IDE si può riassumere come segue:

• i passaggi di avvio, connessione, adattamento, esecuzione e arresto sono opzionali
• supporta diverse piattaforme, cioè essenzialmente Linux, MacOS e Windows
• on-demand startup --options
• consentire connessioni tramite pipe e/o socket
• programmazione disaccoppiata facendo uso di injection
• fornitura di servizi di pooling, pooling relativo al contesto
• e principio KISS

Proposta del modulo IDE_utils: La classe Runner() come gestore del contesto è responsabile pe l'avvio e l'arresto delle istanze di soffice. Un file opzionale di configurazione Runners.json contiene le coppie servizio-opzioni che definiscono i servizi da avviare e il loro stato di esecuzione. Una funzione connect() fa da interfaccia tra le istanze dell'IDE in uso e di LibreOffice. Un oggetto ScriptContext() viene iniettato come XSCRIPTCONTEXT incorporato. Le scorciatoie start() e stop() richiamano le funzioni di Runner(). La struttura del modulo risulta del tipo:

#!  # IDE_utils.py
import officehelper
RUNNERS = 'Runners.json'

class Runner(soffice=None): pass
class ScriptContext(): pass

_ctx = officehelper.bootstrap()
XSCRIPTCONTEXT = ScriptContext(_ctx)

def connect(host='localhost', port=2002, pipe=None): pass
def start(soffice=None): pass
def _stop(): pass

Potete ottenere IDE_utils.py da GitLab.

Uso raccomandato

import uno
def my_1st_macro(): pass  # Il vostro codice va qui

g_exportedScripts = my_1st_macro,  # Macro pubblicate

if __name__ == '__main__':
    from IDE_utils import Runner, XSCRIPTCONTEXT
    with Runner() as jesse_owens:  # Avvia/Arresta, Connetti/Adatta
        my_1st_macro  # Run

L'esempio qui sopra dovrebbe essere il vostro modo preferito per usare IDE_utils. Dato che l'avvio e l'arresto di un servizio potrebbe non essere adatto a tutte le situazioni, questi passaggi sono opzionali. Lo stesso modulo permette la personalizzazione dello stato di esecuzione dei servizi di LibreOffice - o OpenOffice. "La Guida introduttiva" fornisce una descrizione dettagliata di 3 diversi modi di usare IDE_utils:

• Ricorrere al meccanismo predefinito di (Libre/Open)Office per Python bootstrap(),
• Lasciare che gli oggetti Runner() e ScriptContext() si assumano la responsabilità dei passaggi di avvio, connessione, adattamento, esecuzione e arresto,
• decidere quando dare corso ai passaggi di avvio, connessione, adattamento, esecuzione e arresto.

Esaminare (bozza)

Ricavare e impostare le proprietà dei documenti

Analizzare un documento alla ricerca di informazioni sulle API

MRI, xRay e ObjectInspector

Ascoltare (bozza)

...intercettare eventi relativi ai documenti, al ponte URP...