Macro/Elementi base per Python

    From The Document Foundation Wiki
    This page is a translated version of the page Macros/Python Basics and the translation is 100% complete.
    Other languages:

    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

    Per coloro che intendono analizzare la compatibilità:

    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:

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

    Pyzo - Shell - Shell configurations...

    PyCharm

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

    PyCharm - Impostazioni predefinite - Interprete del progetto

    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.

    Gestione dei Documenti (bozza)

    Apertura di un documento

    Creazione di un documento

    Salvataggio di un documento

    Chiusura di un documento

    Un convertitore di uso generale

    Rilevazione e segnalazione di bug

    Esaminare (bozza)

    Esaminare LibreOffice

    Proprietà di configurazione

    Impostazioni dei percorsi

    Ricavare e impostare le proprietà dei documenti

    Segnalare le proprietà dei file del Sistema Operativo

    Impostare le proprietà del documento

    Analizzare un documento alla ricerca di informazioni sulle API

    MRI, xRay e ObjectInspector

    Ascoltare (bozza)

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