Execução de scripts Python do LibreOfficeDev

Dependendo do que pretende alcançar, pode optar por uma das seguintes abordagens para executar scripts Python no LibreOfficeDev:

Executar scripts no processo atual do LibreOfficeDev: Os scripts Python são executados a partir do processo do LibreOfficeDev através do menu Ferramentas - Macros - Executar Macro ou da extensão APSO para chamar scripts do utilizador armazenados na pasta de scripts Python. Também é possível utilizar o shell Python do APSO para executar scripts Python de forma interativa.
Executar scripts separadamente do processo LibreOfficeDev: Os scripts Python são executados a partir de um processo externo que se liga a um processo LibreOfficeDev em execução através de um pipe ou de um socket.

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

Executar scripts a partir do processo LibreOfficeDev

Utilização da extensão APSO

A forma mais fácil de começar a utilizar scripts Python no LibreOfficeDev é instalar a extensão APSO. Após a instalação, abra qualquer componente do LibreOfficeDev e aceda a Ferramentas - Macros - Organizar scripts Python.

Na janela principal do APSO, aceda a Menu - Python Shell.

Em alternativa, pode abrir o APSO utilizando o atalho predefinido Alt + Shift + F11.

Agora pode começar a escrever comandos Python e o shell irá apresentar o resultado correspondente após a execução de cada linha de código.

Para começar a utilizar a biblioteca ScriptForge, é necessário importar o método CreateScriptService, com o qual poderá aceder aos serviços fornecidos pela biblioteca. O exemplo abaixo utiliza o serviço Basic para apresentar uma caixa de mensagem.


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

Para executar o exemplo acima, introduza cada linha no shell do Python, uma a uma, premindo a tecla Enter após escrever cada linha de código.

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


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

Criação de ficheiros de script em Python

Pode criar os seus próprios ficheiros Python e editá-los com o seu editor de texto preferido. Posteriormente, poderá chamá-los a partir de qualquer componente LibreOfficeDev.

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

Agora pode criar um ficheiro de texto na pasta de scripts do utilizador do Python, por exemplo, my_script.py, e começar a escrever os 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 seguinte no ficheiro 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. Note-se que g_exportedScripts é uma tupla que indica quais as funções que serão apresentadas no LibreOfficeDev como scripts do utilizador.

Para executar este script a partir de um documento do Calc:

Crie ou abra um ficheiro do Calc.
Introduza um valor numérico na célula «A1» da folha atual.
Vá a Ferramentas - Macros - Executar macros .
Selecione As minhas macros - my_script no seletor da biblioteca. Em seguida, selecione a função increment_cell na lista Nome da macro.
Clique em Executar. Repare que o valor na célula «A1» aumentou em 1.

Também pode utilizar o APSO para executar scripts Python de forma semelhante:

Primeiro, abra o APSO acedendo a Ferramentas - Macros - Organizar Scripts Python.
Na lista de macros, aceda a As minhas macros - my_script - increment_cell.
Clique em Executar.

Executar scripts separadamente do processo LibreOfficeDev

Determinar o caminho de instalação

O primeiro passo para executar scripts a partir de um processo separado é localizar a pasta onde o LibreOfficeDev está instalado. Existem várias formas de o fazer, mas o ScriptForge oferece uma forma rápida de identificar o caminho de instalação. Para tal, abra o shell Python do APSO e escreva:


      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 base onde o LibreOfficeDev está instalado. Agora, é necessário adicionar a subpasta «program» ao caminho resultante. Esta é a pasta base a partir da qual irá executar scripts Python num 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 LibreOfficeDev com as configurações pipe ou socket

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

Abra a linha de comandos do seu sistema operativo, aceda à pasta do programa no diretório de instalação LibreOfficeDev 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 LibreOfficeDev com um canal de comunicação aberto, para que outros processos possam trocar mensagens com ele.

Note que o exemplo anterior abre o LibreOfficeDev start center. Se pretender abrir um componente específico, por exemplo, Writer, pode adicionar o parâmetro --writer ao comando, da seguinte forma.

./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 LibreOfficeDev. 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 LibreOfficeDev. Mas, primeiro, é necessário configurar a ligaçã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 secçã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 LibreOfficeDev 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 LibreOfficeDev. 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 operativo, 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 ficheiros do seu sistema operativo para determinar o diretório onde se encontram esses dois ficheiros.

Por exemplo, numa instalação padrão do Ubuntu, ambos os ficheiros 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 ficheiros varia consoante o sistema operativo e o método de instalação do LibreOfficeDev.

Ajuda para os scripts Python no LibreOfficeDev