Importar módulos Python

Os scritps Python do LibreOffice podem ser pessoais, compartilhados 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, sua localização deve ser conhecida em 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 se refere a uma função dentro de um módulo.

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

Importar módulos do sistema de arquivos

As bibliotecas BASIC do LibreOffice contém classes, rotinas e variáveis. Os módulos Python contém classes, funções e variáveis. Os trechos comuns de recursos reutilizáveis Python e UNO devem ser armazenados no contêiner Minhas Macros em (perfil do usuário)/Scripts/python/pythonpath. As bibliotecas Python ajudam a organizar os módulos para evitar colisão de nomes. Importe uno.py nos módulos compartilhados.

Módulos do usuário ou compartilhados

Scripts Python, pessoais e compartilhados, podem ser importados assim que suas pastas forem incluídas no caminho de execução do Python. Acesse a página Obtendo informação da sessão para mais informações referentes a Classe Session omitida.


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

Esse 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 compartilhados
        if not share_lib in sys.path:
            sys.path.insert(0, share_lib)  # Adiciona ao caminho de pesquisa
        from IDE_utils import ScriptContext  # 'IDE_utils.py' localiza-se com Python scripts compartilhados.
        XSCRIPTCONTEXT = ScriptContext(uno.getComponentContext)
        # Seu código começa a partir daqui

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

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

Com o interpretador 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 fechamento. Consulte Macros acionadas por eventos para saber como associar macros Python a eventos do 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 busca
            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 do Python runtime
            # Nota: módulos importados permanecem carregados neste exemplo
            
        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):
                """ adiciona 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):
                """ remove o diretório do PYTHON_PATH """
                sys.path.remove(lib_name)
            
        g_exportedScripts = (OnDocPostOpenLoadPython, OnDocQueryCloseUnloadPython)

Obter informação da sessão

Programando com scripts Python

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

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