Macros/Python Design Guide/it

= 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

 * ovviamente Python.org
 * Learn Python the hard way non così difficile come afferma
 * Python - Apache OpenOffice
 * Tutorial su Real Python, Programmazione in Python su Wikibooks
 * Awesome Functional Python

corsi o guide online

 * Learning Python,
 * Learn Python - tutorial interattivo gratuito su Python
 * su Real Python,
 * Programmazione in Python su Wikibooks

Bibliografia online

 * The Hitchhiker's Guide to Python!, Kenneth Reitz, Aprile 2018
 * Object-Oriented Programming in Python, Novembre 2017 in PDF
 * OpenOffice.org 3.1 Developer's Guide, versione online, ed esempi, 2009
 * StarOffice (Basic) Programmer's Tutorial, Maggio 2000
 * Java LibreOffice Programming, Andrew Davison, Marzo 2017

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.

Un elenco più esteso di strumenti per l'(Unified Modeling Language (UML) è disponibile su Wikipedia.
 * 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.

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


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.



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:




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



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


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



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.

All'interno di LibreOffice


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 \python\pythonpath possono essere importati dai moduli incorporati o dagli script che sono in \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: Fermare una macro in esecuzione con X-Ray : Visualizzare oggetti UNO in una struttura ad albero usando Object Inspector :

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 \python o from \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:


 * Un ponte per un'IDE con XSCRIPTCONTEXT rivisitato, febbraio 2017 (in francese)
 * Programmazione orientata alle interfacce in OpenOffice / LibreOffice : automatizzare i lavori d'ufficio con macro in Python, dicembre 2015
 * Creazione di macro per LibreOffice con PyCharm (impostazioni di sistema) settembre 2013 (dal giapponese)
 * Avviare, fermare e collegare OpenOffice a Python, dicembre 2008
 * Python UNO-bridge, ottobre 2008

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.



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 \..\IDE_utils.py

Debug con PyCharm
Il debugger di PyCharm visualizza gli oggetti UNO, le classi e gli oggetti 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.



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.

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.

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: [https://technet.microsoft.com/en-us/library/xd3shwhf(v=vs.100).aspx cf. EditBin guida di riferimento su TechNet]
 * 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:

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. Ciononostante, gli errori di sintassi non saranno riportati.

fonte: [Python Errors report - Debugging configuration]

Gestione delle eccezioni - bozza

 * Gestione delle eccezioni

Realizzare finestra di Dialogo - bozza
[https://github.com/kelsa-pi/unodit cf. UNODiT UNO Dialog Tools] Di seguito trovate alcuni riferimenti per iniziare:

Progettare le finestre di dialogo

 * ulteriori dettagli : .. Viewing intermediate results

Macro guidate dagli eventi

 * UNODiT strumenti per le finestre di dialogo UNO
 * Uso delle finestre nei componenti
 * pagine di aiuto relative agli eventi:
 * Basic: macro controllate da eventi, eventi Funzione CreateUnoListener
 * Writer: eventi degli oggetti
 * generale: eventi dei Controlli o dei Formulari
 * pagine sugli eventi delle API:
 * com.sun.star.document servizio Events, DocumentEvent, XDocumentEventBroadcaster
 * altro: aggiornare automaticamente l'indice con uno script, [Calc Event-Listeners & Handlers], eseguire automaticamente una macro richiamandola dal codice, .. script python per monitorare l'evento OnSave, Un esempio in Python di finestra dialogo con 2 pulsanti, Python...MouseClick su ListBox, Finestra di dialogo in Python, [Python [UI ] Ricaricare una finestra/widget], Eseguire una macro in python quando viene modificato il contenuto di una cella, HowTo .. una macro in Python per Calc
 * funzione di Basic Access2Base Application.Events, Rendere persistente in un documento una modifica registrata da un evento, ..una macro in Python per Calc
 * .Net Come attivare un evento OnLoad per un documento di LibreOffice Writer usando VB.Net/C#

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'estensione per Calc

 * Realizzare un'estensione per Calc, Hubert Lambert, novembre 2016 (in francese)
 * Conversione di coordinate geografiche o cartografiche, pk1157 & alter, gennaio 2011

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?