Executar scripts Python do LibreOffice

Dependendo do que pretende fazer, você pode escolher uma das seguintes abordagens para executar scripts Python no LibreOffice:

Executar scripts dentro do processo atual do LibreOffice: Os scripts Python são executados a partir do processo do LibreOffice usando o menu Ferramentas - Macros - Executar Macro ou a extensão APSO para chamar scripts do usuário armazenados na pasta de scripts Python. Você também pode usar o shell Python do APSO para executar scripts Python de forma interativa.
Executar scripts separadamente do processo LibreOffice: Os scripts Python são executados a partir de um processo externo que se conecta a um processo LibreOffice em execução por meio de um pipe ou um socket.

Se você planeja executar scripts a partir do processo LibreOffice, recomenda-se instalar a extensão APSO (Alternative Script Organizer for Python). No entanto, para desenvolver scripts Python fora do LibreOffice, você pode escolher seu IDE Python preferido.

Executando scripts a partir do processo LibreOffice

Como usar a extensão APSO

A maneira mais fácil de começar a usar scripts em Python no LibreOffice é instalando a extensão APSO. Após a instalação, abra qualquer componente do LibreOffice e acesse Ferramentas - Macros - Organizar scripts Python.

Na janela principal do APSO, vá para Menu - Python Shell.

Como alternativa, você pode abrir o APSO usando o atalho padrão Alt + Shift + F11.

Agora você pode começar a digitar comandos em Python, e o shell exibirá o resultado correspondente após a execução de cada linha de código.

Para começar a usar a biblioteca ScriptForge, é necessário importar o método CreateScriptService, com o qual você poderá acessar os serviços oferecidos pela biblioteca. O exemplo abaixo utiliza o serviço Basic para exibir uma caixa de mensagem.


        from scriptforge import CreateScriptService
        bas = CreateScriptService("Basic")
        bas.MsgBox("Hello!")

Para executar o exemplo acima, digite cada linha no shell do Python, uma por uma, pressionando a tecla Enter após digitar cada linha de código.

Agora você pode começar a executar comandos Python usando qualquer um dos serviços do ScriptForge. Por exemplo, o trecho de código abaixo usa o serviço UI para criar um documento em branco no Writer.


        ui = CreateScriptService("UI")
        doc = ui.CreateDocument("Writer")

Criação de arquivos de script em Python

Você pode criar seus próprios arquivos Python e editá-los com o editor de texto de sua preferência. Posteriormente, você poderá chamá-los a partir de qualquer componente LibreOffice.

O primeiro passo é localizar onde seus scripts de usuário estão armazenados. Para isso, consulte a página de ajuda Organização e localização dos scripts Python.

Agora você pode criar um arquivo de texto na pasta de scripts do usuário do Python, por exemplo, my_script.py, e começar a digitar seus scripts.

A seguir, apresentamos um exemplo simples que obtém o valor numérico de uma célula do Calc e o incrementa em 1. Basta digitar o código a seguir no arquivo my_script.py.


    from scriptforge import CreateScriptService
    doc = CreateScriptService("Calc")
    
    def increment_cell(args=None):
        value = doc.GetValue("A1")
        value += 1
        doc.SetValue("A1", value)
    
    g_exportedScripts = (increment_cell, )

Este exemplo cria a função increment_cell. Observe que g_exportedScripts é uma tupla que indica quais funções serão exibidas no LibreOffice como scripts do usuário.

Para executar este script dentro de um documento do Calc:

Crie ou abra um arquivo do Calc.
Insira um valor numérico na célula "A1" da planilha atual.
Acesse Ferramentas - Macros - Executar macros .
Selecione Minhas macros - my_script no seletor da biblioteca. Em seguida, selecione a função increment_cell na lista Nome da macro.
Clique em Executar. Observe que o valor na célula "A1" foi incrementado em 1.

Você também pode usar o APSO para executar scripts em Python de maneira semelhante:

Primeiro, abra o APSO acessando Ferramentas - Macros - Organizar scripts Python.
Na lista de macros, acesse Minhas macros - my_script - increment_cell.
Clique em Executar.

Executar scripts separadamente do processo LibreOffice

Determinação do caminho de instalação

O primeiro passo para executar scripts em um processo separado é localizar a pasta onde o LibreOffice está instalado. Existem várias maneiras de fazer isso, mas o ScriptForge oferece uma maneira rápida de identificar o caminho de instalação. Para isso, abra o shell Python do APSO e digite:


      from scriptforge import CreateScriptService
      fs = CreateScriptService("FileSystem")
      fs.FileNaming = "SYS"
      inst_dir = fs.InstallFolder
      print(inst_dir)

O resultado do código acima é o diretório raiz onde LibreOffice está instalado. Agora, você precisa adicionar a subpasta “program” ao caminho resultante. Essa é a pasta raiz a partir da qual você executará os scripts Python em um processo separado.

Por exemplo, suponha que obtenha /usr/lib/libreoffice/ como resultado da execução do código Python acima. Nesse caso, deve considerar /usr/lib/libreoffice/program como o caminho para executar os seus scripts Python.

Inicie o LibreOffice com as configurações pipe ou socket

Para executar scripts Python a partir de um processo separado, é necessário iniciar o LibreOffice com algumas opções adicionais que especifiquem o nome do canal ou o nome do host e a porta através dos quais o processo externo irá comunicar com o processo do componente LibreOffice.

Abra a linha de comandos do seu sistema operacional, acesse a pasta do programa no diretório de instalação LibreOffice e digite uma das seguintes opções:

No Linux ou no macOS:

libreoffice --accept='pipe,name=aPipeName;urp;'

No Windows:

soffice.exe --accept='socket,host=localhost,port=2021;urp;'

como Flatpak:

flatpak run org.libreOffice.LibreOffice accept='socket,host=localhost,port=2021;urp;'

Qualquer um dos comandos acima iniciará o LibreOffice com um canal de comunicação aberto, para que outros processos possam trocar mensagens com ele.

Note que nos exemplos anteriores abrem a tela inicial do LibreOffice. Se desejar abrir um componente específico, por exemplo, o Writer, você pode adicionar a chave --writer ao comando como segue.

./soffice --writer --accept='socket,host=localhost,port=2021;urp;'

Tome nota do nome, ou dos parâmetros host e porta, que neste exemplo são aPipeName, ou localhost e 2021, respetivamente.

Executar um shell Python externo

Inicie o shell do Python a partir da pasta program dentro do caminho de instalação LibreOffice. Siga os passos acima para saber como localizar o seu caminho de instalação.

No Linux ou no macOS:

$ cd /usr/lib/libreoffice/program

$ python

No Windows:

$ cd C:\\Program Files\\LibreOffice\\program\

$ python.exe

Isto irá abrir o shell do Python e, a partir daí, poderá começar a introduzir comandos que serão executados pelo LibreOffice. Mas, primeiro, é necessário configurar a conexão pipe ou socket. A instrução ScriptForge() abaixo deve preceder a primeira chamada à função CreateScriptService().

Execute uma das seguintes opções:


   from scriptforge import ScriptForge, CreateScriptService
   ScriptForge(pipe='aPipeName')


    from scriptforge import ScriptForge, CreateScriptService
    ScriptForge(hostname='localhost', port=2021)

Leia a seção Definir PYTHONPATH abaixo, caso surjam erros ao importar scriptforge.py ou uno.py.

A segunda linha de código acima define as configurações pipe ou host e port, para que o shell Python possa comunicar com um processo LibreOffice em execução, aberto com as mesmas configurações de pipe ou socket.

Agora pode executar outros comandos Python, que poderão comunicar com o processo LibreOffice. Por exemplo:


    ui = CreateScriptService("UI")
    bas = CreateScriptService("Basic")
    doc = ui.OpenDocument("~/Documents/myFile.ods")
    bas.MsgBox(doc.DocumentType)

Definir PYTHONPATH

Dependendo da configuração do seu sistema operacional, você terá de definir a variável de ambiente PYTHONPATH para poder importar a biblioteca scriptforge.py, que, por sua vez, requer a importação da biblioteca uno.py.

Utilize a ferramenta de pesquisa de arquivos do seu sistema operacional para determinar o diretório onde se encontram esses dois arquivos.

Por exemplo, numa instalação padrão do Ubuntu, ambos os arquivos podem estar localizados em:

scriptforge.py: Localizado em /usr/lib/libreoffice/program
uno.py: Localizado em /usr/lib/python3/dist-packages

Neste caso, defina a variável de ambiente PYTHONPATH da seguinte forma antes de iniciar o interpretador Python:

export PYTHONPATH=/usr/lib/libreoffice/program:/usr/lib/python3/dist-packages

A localização destes arquivos varia conforme o sistema operacional e o método de instalação do LibreOffice.

Ajuda dos scripts Python do LibreOffice