This page is a translated version of the page Macros/Python Design Guide and the translation is 100% complete.

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

Other languages:

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.

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 32^bit e apparentemente si adatta anche a 64^bit. 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 32^bit sia a 64^bit. 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.

IDLE - Evidenziazione della sintassi e navigatore delle classi.
Geany - Navigatore delle classi, evidenziazione della sintassi e raggruppamento del codice.
PyCharm - Colorazione del codice, navigatore del codice e analisi delle classi.

Completamento automatico del codice

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

IDLE - completamento dei moduli
IDLE - completamento delle funzioni
Geany - completamento dei metodi delle classi
PyCharm - completamento del codice

Debug

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

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

Geany esegue la funzione info() che richiama il metodo ..awt.createMessageBox() dell'API definita nell'SDK - il nome dello script è <user>\SysInfo.py
$Pyzo esecuzione e stop all'interno di <user>\..\IDE_utils.py$

Pyzo esecuzione e stop all'interno di <user>\..\IDE_utils.py
Ispezione di oggetti UNO e di classi e variabili in Python
Punti di interruzione, tracciamento dello stack e ispezione degli oggetti con APSO

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

</Unit testing>

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.

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.

Geany - proprietà del progetto - percorso base
Geany - proprietà del progetto - compila - esegui comandi
Pyzo - Shell - configurazione della Shell...
PyCharm - impostazioni predefinite - interprete del progetto

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:

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.

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

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.

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:

Chiudete LibreOffice.
Scaricate Visual Studio Express 2010 C++ (si presume che possa funzionare anche con altre versioni) e installatelo.
Aprite la console di Visual Studio.
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

Gestione delle eccezioni

Realizzare finestra di Dialogo - bozza

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#

Localizzazione

Comandi del dispatcher - bozza

I [comandi Dispatch] sono usati in combinazione al servizio com.sun.star.frame.DispatchHelper.

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

Creare estensioni - bozza

Sviluppare estensioni in Python con LOEclipse

Per creare un'estensione con Python è possibile usare Eclipse assieme al plugin LOEclipse.

Questo permette di sviluppare estensioni in Python da Eclipse e comprende la pacchettizzazione automatica delle estensioni, oltre ad un debugger per eseguire il debug delle estensioni direttamente in Eclipse.