Contenuto

# Importazione dei moduli Python

Gli script Python di LibreOffice si presentano in tre varietà distinte: personali, condivisi o incorporati nei documenti. Sono memorizzati in posizioni variabili descritte nel capitolo Organizzazione e posizione degli script Python. Per importare moduli, Python deve conoscere la loro posizione al tempo di esecuzione.

Questo meccanismo viene illustrato per i moduli basati sul file system e quelli basati su documento. Per questioni di chiarezza la gestione delle eccezioni viene omessa. I termini libreria o cartella (o directory), script o moduli sono utilizzati in modo intercambiabile. Una macro Python si riferisce a una funzione all'interno di un modulo.

Da notare che quando si esegue una macro Python da <User Profile>/Scripts/python, la cartella locale <User Profile>/Scripts/python/pythonpath viene sempre esaminata.

## Importazione di moduli dal file system

Le librerie di LibreOffice Basic contengono classi, routine e variabili, i moduli Python contengono classi, funzioni e variabili. Le parti comuni delle funzioni Python o UNO riutilizzabili devono essere memorizzate in Macro personaliall'interno del percorso (Profilo utente)/Scripts/python/pythonpath. Le librerie Python aiutano a organizzare i moduli in modo da evitare conflitti di nome. Importate uno.py dentro i moduli condivisi.

### Moduli condivisi o personali

Gli script Python personali e condivisi possono essere importati una volta che le loro cartelle sono incluse nel percorso del tempo di esecuzione Python. Per maggiori dettagli sulla Classe di sessione omessa, consultare il capitolo Ottenere informazioni sulla sessione.

            # -*- coding: utf-8 -*-
            from __future__ import unicode_literals
            import sys

            user_lib = Session().UserPythonScripts  # Posizione degli script personali
            if not user_lib in sys.path:
                sys.path.insert(0, user_lib)  # Aggiunta al percorso di ricerca
            import screen_io as ui  # il modulo 'screen_io.py' si trova nella cartella user_lib
            # Il proprio codice segue qui

Questo esempio Python mette in contatto una variabile XSCRIPTCONTEXT locale con un modulo importato:

            # -*- coding: utf-8 -*-
            from __future__ import unicode_literals
            import uno, sys

            share_lib = Session.SharedPythonScripts()  # Posizione degli script condivisi
            if not share_lib in sys.path:
                sys.path.insert(0, share_lib)  # Aggiunta al percorso di ricerca
            from IDE_utils import ScriptContext  # 'IDE_utils.py' risiede con gli script Python condivisi.
            XSCRIPTCONTEXT = ScriptContext(uno.getComponentContext)
            # Il proprio codice segue qui

### Installazione di moduli per le applicazioni

A differenza degli script personali e condivisi, gli script di installazione di LibreOffice possono essere importati in qualunque momento. Accanto ai moduli Python di LibreOffice uno e unohelper, possono essere importati direttamente altri script presenti nella cartella <installation_path>/program, come il modulo msgbox.

Con shell Python:

>>> import msgbox, uno

>>> myBox = msgbox.MsgBox(uno.getComponentContext())

>>> myBox.addButton("okay")

>>> myBox.renderFromButtonSize()

>>> myBox.numberOflines = 2

>>> print(myBox.show("A small message",0,"Dialog title"))

## Importazione dei moduli del documento

Sotto viene illustrata l'importazione di un modulo Python incorporato in un documento. La gestione degli errori non è argomentata. Il percorso del tempo di esecuzione (runtime) Python viene aggiornato quando il documento è stato aperto e prima della chiusura. Per sapere come associare le macro Python agli eventi del documento, consultare il capitolo Macro controllate da eventi.

            # -*- coding: utf-8 -*-
            from __future__ import unicode_literals

            import sys, uno, zipimport

            def OnDocPostOpenLoadPython(event = None):
                """ Preparare l'importazione dei moduli Python quando il doc. viene caricato """
                PythonLibraries.loadLibrary('lib/subdir')  # Aggiunta della cartella al percorso di ricerca
                PythonLibraries.loadLibrary('my_gui', 'screen_io')  # Aggiunta cartella e importazione screen_io

            def OnDocQueryCloseUnloadPython(event = None):
                """ Ripulitura di PYTHON_PATH quando il doc. viene chiuso """
                PythonLibraries.unloadLibrary('my_gui')  # Ripulitura percorso runtime di Python
                # Nota: in questo esempio i moduli importati rimangono caricati.

            class PythonLibraries():
                """ Caricatore di librerie e importatore di moduli Python

                adattato da 'Bibliothèque de fonctions' di Hubert Lambert
                all'indirizzo https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213 """
                def isImportedModule(module_name: str) -> bool:
                    """ Check dell'elenco dei moduli al tempo di esecuzione """
                    return (module_name in sys.modules.keys())
                def isLoadedLibrary(lib_name: str) -> bool:
                    """ Check del contenuto PYTHON_PATH """
                    url = uno.fileUrlToSystemPath(
                        f'{doc.URL}/Scripts/python/{lib_name}' )
                    return (url in sys.path)
                def loadLibrary(lib_name: str, module_name=None):
                    """ aggiunta cartella a PYTHON_PATH, importazione module specificato """
                    doc = XSCRIPTCONTEXT.getDocument()
                    url = uno.fileUrlToSystemPath(
                        f'{doc.URL}/Scripts/python/{lib_name}' )
                    if not url in sys.path:
                        sys.path.insert(0, url)
                    if module_name and not module_name in sys.modules.keys():
                        return zipimport.zipimporter(url).load_module(module_name)
                def unloadLibrary(lib_name: str):
                    """ rimozione cartella da PYTHON_PATH """
                    doc = XSCRIPTCONTEXT.getDocument()
                    url = uno.fileUrlToSystemPath(
                        f'{doc.URL}/Scripts/python/{lib_name}' )
                    sys.path.remove(url)

            g_exportedScripts = (OnDocPostOpenLoadPython, OnDocQueryCloseUnloadPython)

Argomenti correlati

Ottenere informazioni sulla sessione

Programmare con script Python

Organizzazione e posizione degli script Python

Per visualizzare esempi di macro controllate da eventi, consultare il capitolo Creazione di un listener Python.