Criação de scripts em Python com o ScriptForge

Conteúdo

# Criação de scripts em Python com ScriptForge

## Diferenças entre o Basic e o Python

A biblioteca ScriptForge está disponível tanto para Basic como para Python. A maioria dos serviços, métodos e propriedades funciona de forma idêntica em ambas as linguagens de programação. No entanto, devido às diferenças no funcionamento de cada linguagem, os utilizadores do ScriptForge devem ter em conta algumas características da biblioteca ao utilizarem Python:

- Nomes de métodos e propriedades: Em Python, todos os métodos e propriedades podem ser utilizados nos formatos minúsculas, maiúsculas ou camelCase.

- Argumentos: Todos os argumentos-chave passados aos métodos são convertidos para minúsculas.

- Datas: Todos os objetos de data são passados e devolvidos como objetos nativos do Python do tipo datetime.datetime.

- Matrizes: As matrizes unidimensionais são passadas e devolvidas como tuplas (que são objetos imutáveis). As matrizes bidimensionais são passadas e devolvidas como tuplas de tuplas.

- None: A palavra-chave None do Python é equivalente a Null, Empty ou Nothing do Basic.

- Objetos UNO: Todas as estruturas UNO são trocadas entre o Basic e o Python sem quaisquer alterações.

- Depuração: Sempre que ocorre um erro em scripts Python que utilizam o ScriptForge, a mensagem de erro fornecida pela pilha de execução do Python apresenta a linha de código que provocou o erro. No Basic, as mensagens de erro não apresentam esta informação.

Visite LibreOffice Ajuda sobre scripts em Python para obter mais informações sobre a criação de scripts em Python utilizando o LibreOffice.

## Edição de scripts Python em IDEs

As sugestões de tipagem do Python — relacionadas com os métodos e propriedades públicos dos serviços ScriptForge — podem ser obtidas em IDEs que suportem essa funcionalidade. Visualmente, ao editar um script de utilizador:

- Ao passar o cursor sobre uma instância de objeto, um método ou uma propriedade, é apresentada a respetiva descrição detalhada.

- Um «.» após uma instância de objeto exibe uma lista suspensa com todas as interfaces disponíveis.

- Os parênteses após o nome de um método ativam a autocompletar, exibindo os seus argumentos.

São apresentadas sugestões de digitação ao editar métodos e propriedades com letras em maiúsculas e minúsculas adequadas.

## Executar scripts Python no LibreOffice

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

- Executar scripts no processo atual do LibreOffice: Os scripts Python são executados a partir do processo do LibreOffice 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 LibreOffice: Os scripts Python são executados a partir de um processo externo que se liga a um processo LibreOffice em execução através de um pipe ou de um socket.

Se pretender 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 a partir do exterior do LibreOffice, pode escolher o seu IDE Python preferido.

### Executar scripts a partir do processo LibreOffice

#### Utilização da extensão APSO

A forma mais fácil de começar a utilizar scripts Python no LibreOffice é instalar a extensão APSO. Após a instalação, abra qualquer componente do LibreOffice 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 LibreOffice.

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 LibreOffice como scripts do utilizador.

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

1. Crie ou abra um ficheiro do Calc.

2. Introduza um valor numérico na célula «A1» da folha atual.

3. Vá a Ferramentas - Macros - Executar macros .

4. Selecione As minhas macros - my_script no seletor da biblioteca. Em seguida, selecione a função increment_cell na lista Nome da macro.

5. 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:

1. Primeiro, abra o APSO acedendo a Ferramentas - Macros - Organizar Scripts Python.

2. Na lista de macros, aceda a As minhas macros - my_script - increment_cell.

3. Clique em Executar.

### Executar scripts separadamente do processo LibreOffice

#### Determinar o caminho de instalação

O primeiro passo para executar scripts a partir de um processo separado é localizar a pasta onde o LibreOffice 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 LibreOffice 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 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 anfitrião 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 operativo, aceda à 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 o exemplo anterior abre o LibreOffice 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 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 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 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 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 LibreOffice.

Tópicos relacionados

A biblioteca ScriptForge

Ajuda para os scripts Python no LibreOffice

Starting LibreOffice Software With Parameters

Necessitamos da sua ajuda!