Creating Python Scripts with ScriptForge

Differences between Basic and Python

The ScriptForge library is available both for Basic and Python. Most services, methods and properties work identically in both programming languages. However, due to differences in how each language works, ScriptForge users must be aware of some characteristics of the library when using Python:

Methods and Property names: In Python, all methods and properties can be used in lowercased, ProperCased or camelCased formats.
Arguments: All keyword arguments passed on to methods are lowercased.
Dates: All date objects are passed and returned as datetime.datetime native Python objects.
Arrays: One-dimensional arrays are passed and returned as tuples (which is an immutable object). Two-dimensional arrays are passed and returned as tuples of tuples.
None: Python's None keyword is equivalent to Basic's Null, Empty or Nothing.
UNO objects: All UNO structures are exchanged between Basic and Python without any changes.
Debugging: Whenever an error occurs in Python scripts that use ScriptForge, the error message provided by the Python execution stack displays the line of code that triggered the error. In Basic error messages do not display this information.

Visit LibreOfficeDev Python Scripts Help for more information on Python scripting using LibreOfficeDev.

Editing Python scripts in IDEs

Python typing hints - relating to ScriptForge services public methods and properties - can be obtained from IDEs that support such facility. Visually, while editing a user script:

hovering an object instance, a method or a property displays its detailed description.
a "." after an object instance displays a drop-down box listing all available interfaces.
brackets after a method-name start code-completion by displaying its arguments.

Typing hints are displayed when editing methods and properties with propercase letters.

Running Python scripts on 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.

A biblioteca ScriptForge

Ajuda para os scripts Python no LibreOfficeDev

Starting LibreOfficeDev Software With Parameters