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 LibreOfficeDev para maiores informações sobre a criação de scripts Python no LibreOfficeDev.

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 LibreOfficeDev

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

Executar scripts dentro do processo atual do LibreOfficeDev: Os scripts Python são executados a partir do processo do LibreOfficeDev 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 LibreOfficeDev: Os scripts Python são executados a partir de um processo externo que se conecta a um processo LibreOfficeDev em execução por meio de um pipe ou um socket.

Se você planeja 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 fora do LibreOfficeDev, você pode escolher seu IDE Python preferido.

Executando scripts a partir do processo LibreOfficeDev

Como usar a extensão APSO

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

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 LibreOfficeDev como scripts do usuário.

To run this script from within a Calc document:

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:

First open APSO by going to Tools - Macros - Organize Python Scripts.
In the macro list, navigate to My Macros - my_script - increment_cell.
Click Execute.

Running Scripts separately from the LibreOfficeDev process

Determining the Installation Path

The first step to run scripts from a separate process is to find the folder where LibreOfficeDev is installed. There are several ways to do that, but ScriptForge provides a quick way to identify your installation path. For that, open APSO's Python shell and type:


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

The output from the code above is the base directory where LibreOfficeDev is installed. Now you need to add the "program" subfolder to the resulting path. This is the base folder from which you will run Python scripts from a separate process.

For example, suppose you get /usr/lib/libreoffice/ as the result from running the Python code above. Then you need to consider /usr/lib/libreoffice/program as the path to run your Python scripts.

Start LibreOfficeDev with pipe or socket settings

To run Python scripts from a separate process, you need to start LibreOfficeDev with a few additional options that specify pipe name or the hostname and port through which the external process will communicate with the LibreOfficeDev component process.

Open the your operating system's command prompt, navigate to the program folder of your LibreOfficeDev installation directory and type either:

On Linux or macOS:

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

On Windows:

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

as a Flatpak:

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

Either command above will start LibreOfficeDev with a communication channel open so that other processes can exchange messages with it.

Note que nos exemplos anteriores abrem a tela inicial do LibreOfficeDev. 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;'

Take note of the name, or host and port parameters, which in this example are aPipeName, or localhost and 2021, respectively.

Running an External Python Shell

Start the Python shell from within the program folder inside your LibreOfficeDev installation path. Follow the steps above to learn how to find your installation path.

On Linux or macOS:

$ cd /usr/lib/libreoffice/program

$ python

On Windows:

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

$ python.exe

This will open the Python shell and now you can start typing commands that will be executed by LibreOfficeDev. But first you need to set up the pipe or the socket connection. The ScriptForge() statement below must precede the very first call to CreateScriptService().

Run either:


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


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

Read the section Setting PYTHONPATH below in case of errors importing scriptforge.py or uno.py.

The second line of code above defines the pipe or host and port settings so that the Python shell can communicate with an ongoing LibreOfficeDev process opened with the same pipe or socket settings.

Now you can run other Python commands and they will be able to communicate with the LibreOfficeDev process. For example:


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

Setting PYTHONPATH

Depending on your operating system's configuration you will need to set the environment variable PYTHONPATH in order to import the scriptforge.py library, which in turn requires importing the uno.py library.

Use your operating system's file search tool to determine the directory where both these files are located.

For instance, on a default Ubuntu installation both files may be located at:

scriptforge.py: Located in /usr/lib/libreoffice/program
uno.py: Located in /usr/lib/python3/dist-packages

In this case, set the environment variable PYTHONPATH as follows before starting the Python interpreter:

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

The location of these files will be different for each operating system and LibreOfficeDev installation method.

A Biblioteca ScriptForge

Ajuda dos scripts Python do LibreOfficeDev

Iniciar o LibreOfficeDev com parâmetros