Importar módulos Python

Os scritps Python do LibreOffice podem ser pessoais, partilhados ou embutidos em documentos. São armazenados nos vários locais descritos em Organização e locais dos scripts Python. Para importar módulos Python, a sua localização deve ser obtida do Python no tempo de execução.

Este mecanismo é ilustrado para módulos do sistema, e para módulos de documentos. O tratamento de exceções foi omitido para clareza. Os termos biblioteca ou diretório, scripts ou módulos são intercambiáveis. Uma macro Python refere-se a uma função dentro de um módulo.

Note que o diretório local <Perfil do utilizador>/Scripts/python/pythonpath é sempre percorrido ao executar uma macro Python a partir de <Perfil do utilizador>/Scripts/python.

Importar módulos do sistema de arquivos

LibreOffice Basic libraries contain classes, routines and variables, Python modules contain classes, functions and variables. Common pieces of reusable Python or UNO features must be stored in My macros within (User Profile)/Scripts/python/pythonpath. Python libraries help organize modules in order to prevent module name collisions. Import uno.py inside shared modules.

Módulos do utilizador ou partilhados

Os scripts Python - pessoais e partilhados - podem ser importados assim que as suas pastas forem incluídas no caminho de execução do Python. Consulte Obtendo informação da sessão para mais informações referentes à Classe Session omitida.


        # -*- coding: utf-8 -*-
        from __future__ import unicode_literals
        import sys
            
        user_lib = Session().UserPythonScripts  # Localização dos scripts de utilizador
        if not user_lib in sys.path:
            sys.path.insert(0, user_lib)  # Adicionar ao caminho de pesquisa
        import screen_io as ui  # o módulo 'screen_io.py' encontra-se na pasta user_lib
        # O seu código começa a partir daqui

Este exemplo Python expõe uma variável local, XSCRIPTCONTEXT, para um módulo importado:


        # -*- coding: utf-8 -*-
        from __future__ import unicode_literals
        import uno, sys
            
        share_lib = Session.SharedPythonScripts()  # Localização dos scripts partilhados
        if not share_lib in sys.path:
            sys.path.insert(0, share_lib)  # Adicionar ao caminho de pesquisa
        from IDE_utils import ScriptContext  # 'IDE_utils.py' localiza-se com Python scripts partilhados.
        XSCRIPTCONTEXT = ScriptContext(uno.getComponentContext)
        # O seu código começa a partir daqui

Módulos de instalação para aplicações

Ao contrário dos scripts pessoais e partilhados, os scripts instalados do LibreOffice podem ser importados a qualquer momento. Junto com os módulos uno e unohelper do LibreOffice, podem ser importados diretamente outros scripts presentes no diretório <caminho_instalação>/program, tal como o módulo msgbox.

Com a consola 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"))

Importação de módulo de documentos

Mostra-se abaixo como importar um documento com um módulo Python embutido. O tratamento de erros não é considerado. O caminho em tempo de execução do Python é atualizado quando o documento é aberto, e antes do seu encerramento. Consulte Macros acionadas por eventos para saber como associar macros Python a eventos de documento.


        # -*- coding: utf-8 -*-
        from __future__ import unicode_literals
            
        import sys, uno
            
        def OnDocPostOpenLoadPython():
            """ Preparar importação de módulos Python quando o doc. for carregado """
            PythonLibraries.loadLibrary('lib/subdir')  # Adicionar diretório ao caminho de pesquisa
            PythonLibraries.loadLibrary('my_gui', 'screen_io')  # Adicionar dir. e importar screen_io
            
        def OnDocQueryCloseUnloadPython():
            """ Limpar PYTHON_PATH quando doc. for fechado """
            PythonLibraries.unloadLibrary('my_gui')  # Limpeza do caminho de execução do Python
            # Note: imported modules remain loaded in this example.
            
        class PythonLibraries():
            """ Carregador da biblioteca Python e importador de módulos
            
            adaptado de 'Bibliothèque de fonctions' de Hubert Lambert
            em https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213"""
            def isImportedModule(module_name: str) -> bool:
                """ Verificar lista de módulos de tempo de execução """
                return (module_name in sys.modules.keys())
            def isLoadedLibrary(lib_name: str) -> bool:
                """ Verificar conteúdo de PYTHON_PATH """
                return (lib_name in sys.path)
            def loadLibrary(lib_name: str, module_name=None):
                """ adicionar o diretório ao PYTHON_PATH, importa o módulo nomeado """
                doc = XSCRIPTCONTEXT.getDocument()
                url = uno.fileUrlToSystemPath(
                    '{}/{}'.format(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):
                """ remover o diretório de PYTHON_PATH """
                sys.path.remove(lib_name)
            
        g_exportedScripts = (OnDocPostOpenLoadPython, OnDocQueryCloseUnloadPython)

Obter informação da sessão

Programação com scripts Python

Organização e localização de scripts Python

Consulte Criar um recetor em Python para exemplos de macros acionadas por eventos.