Criando Scripts Python com o ScriptForge

Diferenças entre Basic e Python

A biblioteca ScriptForge está disponível nas linguagens Basic e Python. A maioria dos serviços, métodos e propriedades funcionam de forma idêntica em ambas linguagens de programação. Entretanto, devido a diferenças em como cada linguagem funciona, usuários do ScriptForge devem estar cientes de algumas características da biblioteca ao usar Python:

Nomes de métodos e propriedades: Em Python todos os métodos e propriedades podem ser usados nos formatos lowercased, ProperCased ou camelCased.
Arguments: All keyword arguments passed on to methods are lowercased.
Datas: Todos os objetos de data são passados e retornados como objetos nativos Python do tipo datetime.datetime.
Arrays: Arrays de uma dimensão são passados e retornados como tuplas (as quais são objetos imutáveis em Python). Arrays de duas dimensões são passados e retornados como tuplas de tuplas.
None: O objeto None do Python é equivalente às palavras-chave do Basic Null, Empty ou Nothing.
Objetos UNO: Todas as estruturas UNO são transmitidas entre as linguagens Basic e Python sem mudança alguma.
Depuração: Sempre que um erro ocorrer em scripts Python que usem a biblioteca ScriptForge, a mensagem de erro fornecida pelo interpretador Python mostrará a linha de código que disparou o erro. Na linguagem Basic as mensagens de erro não possuem essa informação.

Visite a Ajuda dos scripts Python do LibreOffice para maiores informações sobre a criação de scripts Python no LibreOffice.

Editar scripts Python em IDEs

Dicas de digitação Python - relacionadas a métodos e propriedades públicas de serviços ScriptForge - podem ser obtidas de IDEs que suportam tal recurso. Visualmente, ao editar um script de usuário:

passar o mouse sobre uma instância de objeto, um método ou uma propriedade exibe sua descrição detalhada.
um "." depois de uma instância de objeto exibe uma caixa suspensa listando todas as interfaces disponíveis.
colchetes após o nome de um método iniciam a conclusão do código exibindo seus argumentos.

Dicas de digitação são exibidas ao editar métodos e propriedades com letras maiúsculas e minúsculas.

Executando scripts Python no 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.

A Biblioteca ScriptForge

Ajuda dos scripts Python do LibreOffice

Iniciar o LibreOffice com parâmetros