Progettare e sviluppare applicazioni in Python

    From The Document Foundation Wiki
    This page is a translated version of the page Macros/Python Design Guide and the translation is 100% complete.

    Introduzione

    Questa pagina è rivolta ai programmatori di macro in Python che desiderano progettare o collaborare allo sviluppo di applicazioni per LibreOffice. I programmatori in Python, sia principali, sia esperti, possono trarre dei benefici da questa pagina di linee guida per lo sviluppo. Una presentazione dell'uso di Python all'interno di LibreOffice è disponibile nella Guida a Python.

    Coloro che si candidano a collaborare con il progetto LibreOffice possono far riferimento a questo Wiki per essere coinvolti.

    Questa pagina presume che abbiate un ragionevole conoscenza di Python, così come dovreste avere una certa familiarità con le applicazioni della suite LibreOffice. Contiene alcuni esempi di codice in Python e sono anche descritti brevemente degli esempi del suo utilizzo nelle estensioni di LibreOffice.

    Documentazione

    corsi o guide online

    Bibliografia online

    Unified Modeling Language (UML)

    Sono disponibili numerosi strumenti basati su UML. Qui di seguito trovate un elenco arbitrario che privilegia le applicazioni compatibili, libere e open source, indicando le lingue in cui sono disponibili.

    • ArgoUML : ArgoUML è eseguibile su qualisiasi piattaforma Java ed è disponibile in dieci lingue (Inglese americano, inglese del Regno Unito, francese, tedesco, italiano, portoghese, spagnolo, russo, norvegese Bokmål e cinese).
    • StarUML : StarUML viene proposto per macOS 10.10+, Windows 7+ e Ubuntu, Debian, Red Hat e Fedora (64 o 32-bit). StarUML ha una ricca dotazione di funzioni ed è disponibile solo in inglese.
    • Umbrello : Umbrello è multilingua e si trova per distribuzioni GNU/Linux, Windows (64 o 32-bit) e macOS.

    Un elenco più esteso di strumenti per l'(Unified Modeling Language (UML) è disponibile su Wikipedia.

    Il manuale StarOffice Programmer's Tutorial illustra dettagliatamente i documenti di LibreOffice con l'aiuto di diagrammi UML.

    I Software Design Pattern sono descritti su Wikipedia, alcuni accompagnati da esempi in Python.

    Introduzione

    Gestione degli script Python con librerie

    Per lo sviluppo di macro in Basic, LibreOffice è dotato di un Ambiente di sviluppo integrato (IDE) che ne consente la modifica, il debug e cose simili. La scrittura di macro in Python richiede dei passaggi di configurazione aggiuntivi al fine di poter disporre dell'IDE prescelta. In compenso avrete a disposizione un'esperienza di progettazione più flessibile, basata sulle vostre preferenze e abitudini di sviluppo in Python. Qui di seguito sono riportate le linee guida per la configurazione dell'IDE, adatte agli utenti che vanno dai principianti a quelli avanzati.

    Per Python non è disponibile la gestione delle librerie e delle macro equivalente a quella per Basic. Comunque è possibile gestire i tradizionali moduli e funzioni di Python, mentre la realizzazione di pacchetti in Python si traduce, almeno in parte, nella creazione di estensioni per LibreOffice o di pacchetti UNO. In questa pagina i termini moduli e librerie interscambiabili sono tra loro, così come i termini funzioni e macro. Dovreste preferire la terminologia di Python al fine di adeguarvi meglio alle sue abitudini culturali.

    Gli script per LibreOffice possono essere di tre tipi distinti: possono essere personali, condivisi o incorporati nei documenti. A seconda del loro tipo e della piattaforma, vengono memorizzati in diversi percorsi descritti in dettaglio nell'articolo sul wiki di AOO Python as a macro language.

    Per gestire gli script in Python potete sia usare le librerie di Windows, sia fare ricorso alle scorciatoie dei file manager di GNU/Linux. Perciò i file .py possono essere organizzati usando un semplice drag & drop. Una descrizione di dove si trovano le cartelle all'interno del vostro ambiente, in modo da aiutarvi nell'impostazione delle librerie o delle scorciatoie per il file manager, si può trovare nell'articolo sul wiki di AOO Python as a macro language.

    I progetti in Python possono essere organizzati per IDE in una libreria sequenziale di Windows, come illustrato.

    Menu alternativo per l'organizzazione degli script in Python

    L'estensione indispensabile Alternative Python Script Organizer fa leva sulla gestione degli script in Python. Installandola otterrete una maggior integrazione degli script in Python all'interno di LibreOffice. Una volta riavviato LibreOffice, controllate che nel menu Strumenti sia presente in sottomenu Macro - Organizza gli script in Python.

    Questa estensione propone varie azioni al fine di gestire gli script in Python. Il pulsante Execute esegue la macro selezionata. Le azioni disponibili dal pulsante del Menu dipendono dall'elemento selezionato:

    La finestra di dialogo di Alternative Python Script Organizer
    • Creare una macro o una libreria nel caso selezioniate un contenitore personale, condiviso o interno al documento
    • Modificare, rinominare, eliminare una macro o libreria
    • Incorporare in un documento una macro presente in un contenitore personale o condiviso
    • Sostituire una libreria incorporata in un documento con un modulo di Python presente nella piattaforma
    • Esportare una libreria incorporata in un documento come modulo di Python
    • effettuare il Debug della macro selezionata
    • Eseguire la console interattiva di Python, conosciuta anche come interprete di Python

    Nella sezione Debug potete trovare maggiori informazioni riguardanti l'organizzazione degli script e dei pacchetti in Python.

    La pagina Assegnazione degli script in LibreOffice illustra come usare gli script nelle applicazioni della suite LibreOffice.

    Sviluppo

    Molte applicazioni fanno uso di Python, sia nativamente o in base a delle specifiche. LibreOffice incorpora il suo interprete di Python che permette di usare le API Universal Network Objects (UNO). Il linguaggio Python possiede il suo inteprete che può essere usato in parallelo a quello di LibreOffice. Entrambi condividono una base comune e sono estendibili, perciò forniscono sia delle funzionalità identiche tra loro, sia alcune diverse. Il Python nativo non comprende l'interfaccia alle API UNO di LibreOffice. Al contrario la versione di LibreOffice non si comporta completamente come la versione nativa di Python e non estende le sue funzionalità esattamente allo stesso modo della versione nativa di Python. In ogni caso, né la versione di LibreOffice, Nè la versione nativa facilita lo sviluppo di applicazioni in Python per Writer, Calc, Impress, Draw, Base o Math.

    LibreOffice esiste nelle versioni a 32 o 64 bit. L'Ambiente di sviluppo integrato (IDE) che lo accompagna deve essere eseguito nello stesso contesto, a 32 o 64 bit. Esistono numerose IDE, da quelle più semplici come IDLE, anche se discutibile, ad altre più elaborate come PyCharm o PyDev per Eclipse. L'elenco che segue è deliberatamente focalizzato su strumenti che sono liberi, open source, multipiattaforma e possibilmente multilingua. Di seguito il capitolo Debug usa Pyzo e PyCharm solamente a scopo illustrativo. Un elenco di IDE per Python è disponibile sul sito Python.org. Su Wikipedia è disponibile una comparazione degli Ambienti di sviluppo integrati (IDE) per numerosi linguaggi.

    • Integrated Development and Learning Environment (IDLE) supporta versioni a 32 e 64 bit. È disponibile per molte piattaforme. IDLE è lo strumento raccomandato per imparare Python.
    • Geany lavora a 32 o 64 bit ed è disponibile in 43 lingue differenti. Funziona su GNU/Linux, *BSD, macOS, AIX v5.3, Solaris Express e Windows. Geany è leggero, si adatta a piccoli progetti e supporta l'interprete Python di LibreOffice.
    • Liclipse
    • secondo questo post, sembra possibile il debug usando Aptana
    • PyCharm (nella versione libera) supporta le piattaforme Gnu/Linux, macOS e Windows. È disponibile a 32bit e apparentemente si adatta anche a 64bit. Oltre a numerose funzioni che accompagnano nello sviluppo in Python, PyCharm possiede un debugger per Python che è compatibile con LibreOffice.
    • Pyzo è disponibile per Linux, OS X e Windows in 10 lingue differenti. Possono essere configurati diversi interpreti di Python, sia a 32bit sia a 64bit. Pyzo offre delle funzioni di debug.

    Qui di seguito trovate un elenco delle funzioni disponibili in questi IDE, alcune delle quali non si trovano nell'IDE di LibreOffice Basic.

    Esplorare del codice sorgente, evidenziare la sintassi

    L'esplorazione dei sorgenti e l'evidenziazione della sintassi di IDLE, Geany e PyCharm facilitano la modifica degli script. Geany e PyCharm supportano il raggruppamento del codice. Il navigato delle classi di IDLE non supporta le classi interne o incorporate.

    Completamento automatico del codice

    Il completamento del codice assiste nella modifica degli script Python in IDLE, Geany e PyCharm.

    Debug

    Il capitolo sottostante sul Debug entra maggiormente nei dettagli di questo argomento.

    Linee guida per il codice (PEP)

    L'IDE PyCharm visualizza dei controlli di conformità alle Python Enhancement Proposal (PEP).

    l'Assistente alle convenzioni di programmazione di PyCharm

    Le convenzioni e le raccomandazioni per la programmazione in Python sono disponibili nella porzione più a destra dell'editor. Queste sono particolarmente utili per i programmatori inesperti.

    Sviluppo guidato dai test (TDD) - bozza

    </Unit testing>

    Controllo di versione

    In PyCharm è disponibile un visualizzatore della cronologia locale del codice sorgente, come illustrato qui di seguito:

    Cronologia degli aggiornamenti locali al codice sorgente

    Sono visualizzate simultaneamente due copie del modulo Python apso.py, rispettivamente denominate v0.8.3 e v0.8.7. Le differenze tra le versioni sono evidenziate con precisione.

    PyCharm supporta altre soluzioni per il controllo di versione (VCS) come Git, GitHub, Mercurial, Perforce o Subversion.

    Debug

    All'interno di LibreOffice

    Xray - Metodi di un oggetto di testo di Writer
    MRI - Proprietà, metodi, servizi e interfacce di un documento di Writer
    Object Inspector - proprietà, metodi, servizi supportati e interfacce di 'StarDesktop'

    Con l'aiuto dell'estensione Alternative Python Script Organizer potete modificare e fare il debug di macro in Python direttamente all'interno di LibreOffice. Potete gestire le librerie e i moduli, ed anche selezionare il vostro editor preferito, senza uscire da LibreOffice.

    Lo sviluppo all'esterno di LibreOffice è altrettanto fattibile, quindi diventa possibile anche il debug. La programmazione e l'esecuzione di test da remoto usando un'Integrated Development Environment (IDE) fornisce ulteriori funzioni, dettagliate qui di seguito.

    Queste tre estensioni consentono ai programmatori di avere dei benefici in entrambi i contesti. Possono essere usate indipendentemente dal linguaggio di programmazione, sia che si tratti di LibreOffice Basic, Python, JavaScript o BeanShell. Tutte e tre estendono l'introspezione delle API della suite LibreOffice.

    Estensioni utili

    Al momento della progettazione, non è sempre chiaro quali servizi sono effettivamente supportati da un oggetto UNO. In ogni caso esistono delle estensioni che aiutano gli sviluppatori a ispezionare arbitrariamente degli oggetti UNO, però queste non sono dispinibili nel catalogo delle estensioni, fatta eccezione di MRI. Queste sono realizzate sulla base delle capacità di riflessione delle API di LibreOffice.

    • X-Ray ispeziona gli oggetti delle API di LibreOffice. Visualizza proprietà, metodi, servizi e interfacce fornite da ciascuna variabile oggetto. X-Ray è disponible in francese, inglese, tedesco, spagnolo, ceco, polacco e russo. X-Ray è scritto in Basic.
    • MRI (My Reflection and Introspection) è uno strumento di introspezione di oggetti UNO, scritto in Python. Le sue caratteristiche sono simili a quelle di X-Ray. MRI è disponibile solamente in inglese. Nota: la copia di MRI presente nel catalogo delle estensioni non è aggiornata.
    • Object Inspector L'estensione Object Inspector visualizza all'interno di una finestra, una struttura ad albero con tutte le funzionalità supportate da un oggetto UNO come: i servizi, le interfacce ed i loro rispettivi metodi e proprietà. Object Inspector è scritto in Java ed è disponibile solamente in inglese.
    • APSO L'estensione Alternate Python Script Organizer integra bene l'introspezione degli oggetti nel suo debugger. Fa uso sia di X-Ray, sia di MRI.

    Utilizzo delle macro in Python

    In LibreOffice le macro in Python vengono salvate in diversi percorsi e sono di diverso tipo, come spiegato in Python as a macro language. Gli script possono essere personali, condivisi, salvati come estensioni, integrati in pacchetti o incorporati nei documenti. Queste diversità comportano differenti usi o limitazioni.

    • In un documento ciascun modulo è autonomo, non è possibile importare moduli.
    per aggirare questo ostacolo, fate riferimento a Importazione dei moduli Python della guida online/locale
    • da un modulo Python incorporato, è possibile richiamare un'estensione scritta in Basic o Python.
    • gli script in Python che si trovano in <user>\python\pythonpath possono essere importati dai moduli incorporati o dagli script che sono in <user>\python.
    • Nessun supporto per Basic da parte dell'IDE: X-Ray non presente
    la presenza di Basic dipende dal tipo di collegamento stabilito con l'IDE.
    • Python e Java sono supportati quando vengono invocati da un'IDE: si possono usare MRI e Object Inspector.

    Qui trovate come usare Mri in una macro in Python:

    import uno
    def mri(target):
        ctx = uno.getComponentContext()
        mri = ctx.ServiceManager.createInstanceWithContext(
            "mytools.Mri",ctx)
        mri.inspect(target)
        
    if __name__ == '__main__':
        def Mri_test():
            document = XSCRIPTCONTEXT.getDocument()
            mri(document)
     
        Mri_test()

    Fermare una macro in esecuzione con X-Ray :

    import uno
    from com.sun.star.uno import RuntimeException as _rtex
    
    def xray(myObject):
      try:
        sm = uno.getComponentContext().ServiceManager
        mspf = sm.createInstanceWithContext("com.sun.star.script.provider.MasterScriptProviderFactory", uno.getComponentContext())
        scriptPro = mspf.createScriptProvider("")
        xScript = scriptPro.getScript("vnd.sun.star.script:XrayTool._Main.Xray?language=Basic&location=application")
        xScript.invoke((myObject,), (), ())
        return
      except:
         raise _rtex("\nLa libreria Basic di Xray non è installata", uno.getComponentContext())
    
    # ___________  esempio di utilizzo  _______________ 
    
    def demoXray(): 
      """ esempio : uso di xray in un documento di Writer """ 
      
      xTextDoc = XSCRIPTCONTEXT.getDocument() 
      xText = xTextDoc.Text 
      xray(xText)
      xray("La dimostrazione è terminata") 
    
    g_exportedScripts = demoXray,

    Visualizzare oggetti UNO in una struttura ad albero usando Object Inspector :

    import uno
    def inspectObject( obj, title="Object Inspector" ):
    	ctx = uno.getComponentContext()
    	oi = ctx.ServiceManager.createInstanceWithContext("org.openoffice.InstanceInspector", ctx)
    	if oi is None:  # es. InstanceInspector non è installato o è disattivato
    		return  # esce silenziosamente
    	oi.inspect( obj, title )
    def exObjInspector():
    	doc = XSCRIPTCONTEXT.getDocument()
    	dsk = XSCRIPTCONTEXT.getDesktop()
    	inspectObject(doc)
    	inspectObject(dsk, title="StarDesktop")

    Da una IDE tramite l'interprete Python di LibreOffice

    Sviluppare macro in Python all'interno di un'IDE richiede che venga usato l'interprete di LibreOffice. La versione nativa Python è fornita dell'interprete IDLE che non è compatibile con gli oggetti UNO. Mentre selezionando un'IDE per Python i programmatori beneficiano di numerose funzionalità come: un navigatore delle classi, l'evidenziazione della sintassi, il completamento automatico del codice, il rispetto forzato degli standard di scrittura del codice, lo sviluppo basato sui test, funzioni di debug, il controllo di versione e molte altre.

    L'impostazione dell'interprete Python di LibreOffice in Geany, PyCharm o Pyzo è illustrata in Elementi base per Python.

    Al fine di eseguire uno script da <user>\python o from <user>\python\pythonpath, dev'essere stabilita una comunicazione tra la IDE e LibreOffice. Gli oggetti UNO non sono raggiungibili senza questo tramite. Una volta che la comunicazione è attiva, la IDE e LibreOffice lavorano assieme. Ai seguenti collegamenti trovate documenti che illustrano questo processo:

    Il modulo IDE_utils prende in prestito da queste risorse e mette a disposizione di LibreOffice un modo semplice per abilitare le macro in Python usando un'IDE.

    Uso di script Python

    • ...richiamare pacchetti in Python...

    Esecuzione esterna con Geany

    Geany inizializza l'apertura di una finestra all'interno di LibreOffice. l'IDE di Geany invoca la funzione info(), che utilizza il metodo dell'API ..awt.createMessageBox definito nell'SDK. Lo script dell'utente si chiama SysInfo.py.

    Geany esegue la funzione info() che chiama il metodo dell'API ..awt.createMessageBox() definito nell'SDK - Il nome dello script è <user>\SysInfo.py

    Debug con PyZo

    PyUNO Workspace è un plugin per l'IDE Pyzo e fornisce un oggetto di introspezione per le API PyUNO e LibreOffice UNO:

    Pyzo in esecuzione e fermo all'interno di <user>\..\IDE_utils.py
    Pyzo in esecuzione e fermo all'interno di <user>\..\IDE_utils.py

    Debug con PyCharm

    Il debugger di PyCharm visualizza gli oggetti UNO, le classi e gli oggetti di Python:

    Visualizzazione di oggetti UNO, classi e variabili di Python

    Debug con APSO

    L'estensione Alternative Python Script Organizer, mediante l'uso di xRay o MRI, permette l'esecuzione passo passo ed anche il tracciamento e la visualizzazione dello stack di esecuzione e l'introspezione di oggetti UNO.

    la finestra di debug di APSO

    Output nelle Console

    Gli script in Python possono essere prototipati usando la shell di Python e il suo meccanismo REPL (Read Execute Print Loop - ciclo di lettura, esecuzione e stampa). L'estensione Alternative Python Script Organizer integra questa funzione, che fa parte dell'interprete Python di LibreOffice.

    la console di APSO

    Console interattiva di Python

    La console interattiva di Python, chiamata anche interprete Python o shell Python, mette a disposizione dei programmatori un modo veloce per eseguire i comandi e provare il codice senza dover creare un file. L'introspezione degli oggetti UNO, così come la documentazione dei moduli Python di LibreOfficeDev può essere ottenuta da terminale. La guida in linea di LibreOffice illustra come eseguire la console interattiva di Python.

    la shell di Python

    Console su Windows

    Per impostazione predefinita, in Windows non c'è uno stdout (standard output). Ciò che viene inviato dalla funzione “print” non sarà visibile in nessun posto. Per avere una console da usare come stdout:

    • Avviate LibreOffice usando soffice.com invece di soffice.exe:

    Le istruzioni print() contenute negli script in Python compaiono nella console fino a quanto LibreOffice non viene chiuso. In assenza della console, le istruzioni print() restano silenti.

    fonte: Proper console mode for LibreOffice on Windows

    Questa funzione è disponibile dalla versione 6.3 di LibreOffice. Per le versioni precedenti, seguite queste istruzioni:

    1. Chiudete LibreOffice.
    2. Scaricate Visual Studio Express 2010 C++ (si presume che possa funzionare anche con altre versioni) e installatelo.
    3. Aprite la console di Visual Studio.
    4. Digitate:

    editbin.exe /subsystem:console "C:\Program Files\LibreOffice 5\program\soffice.exe"
    editbin.exe /subsystem:console "C:\Program Files\LibreOffice 5\program\soffice.bin"

    cf. EditBin guida di riferimento su TechNet

    Ora, quando aprite LibreOffice, verrà visualizzata una console. Questa sarà lo stdout per il comando “print”, così, se fate uso del modulo traceback, potrete intercettate gli errori di Python mentre LO è in esecuzione.

    import traceback
    […]
    try:
        […]
        except:
            traceback.print_exc()

    Ciononostante, gli errori di sintassi non saranno riportati.

    fonte: [Python] Errors report - Debugging configuration

    Gestione delle eccezioni - bozza

    Realizzare finestra di Dialogo - bozza

    cf. UNODiT UNO Dialog Tools Di seguito trovate alcuni riferimenti per iniziare:

    Macro guidate dagli eventi

    Localizzazione

    Comandi del dispatcher - bozza

    Programmazione basata sull'interfaccia in *Office, Christopher Bourez (2015)

    Creare estensioni - bozza

    Estensioni

    Sviluppare estensioni

    Gestore delle estensioni

    Creazione di pacchetti di componenti UNO - test di componenti in Python

    Accettare eventi creati dai controlli di una finestra di dialogo

    Creare un Service

    Creare un'estensione per Calc

    Creare un'estensione

    Varie - bozza

    Importare moduli nei Documenti

    cf. Importazione dei moduli Python nella guida in linea

    Pacchetti Python o estensioni di LibreOffice

    (cf. al momento esiste solo una bozza in francese)

    Proprietà statiche o metodi

    Q: Qual è il comportamento dell'attributo globale in Python?

    Usare Git con PyCharm - bozza