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.
Argumentos: Todos os argumentos de palavra-chave são passados em caixa baixa (lowecased).
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 você deseja fazer, você pode optar por uma das seguintes abordagens para rodar scripts Python no LibreOffice.

Rodar scripts dentro do processo atual do LibreOffice: Scripts Python são executados de dentro do próprio processo do LibreOffice usando o item de meu Ferramentas - Macros - Executar Macro ou usando a extensão APSO para chamar scripts de usuário armazenados na pasta de scripts Python. Você também pode usar a shell Python da extensão APSO para executar scripts interativamente.
Run Scripts separately from the LibreOffice process: Python scripts are executed from an external process that connects to an ongoing LibreOffice process using a pipe or a socket.

Se você planeja rodar scripts Pythons dentro do mesmo processo que o LibreOffice, é recomendável instalar a extensão APSO (Alternative Script Organizer for Python) extension. Contudo, para desenvolver scripts Python que serão rodados de fora do LibreOffice, você pode usar sua IDE Python preferida.

Executando scripts dentro do processo LibreOffice

Usando a extensão APSO

A maneira mais fácil de começar a criar scripts Python no LibreOffice é instalando a extensão APSO. Após sua instalação, abra qualquer aplicativo do LibreOffice e acesse o item do menu Ferramentas - Macros - Organize python scripts.

Na janela principal do APSO vá em Menu - Python Shell.

Alternativamente você pode abrir a janela principal da extensão APSO usando o atalho padrão Alt + Shift + F11.

Agora você pode começar a digitar comandos em Python e o shell irá imprimir as saídas de cada linha de código ao passo em que são executadas.

Para começar a usar a biblioteca ScriptForge é necessário importar o método CreateScriptService, com o qual você poderá acessar os serviços disponibilizados pela biblioteca. O exemplo abaixo usa o serviço Basic para mostrar uma caixa de mensagem.


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

Para executar o exemplo acima, entre cada linha de código no shell Python, uma a uma, pressionando a tecla Enter após digitar cada linha.

Agora você pode começar a executar comandos Python usando qualquer um dos serviços ScriptForge. Por exemplo, o fragmento de código abaixo usa o serviço UI para criar um documento Writer em branco.


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

Criando arquivos de script em Python

Você pode criar seus próprios arquivos de script em Python e editá-los com seu editor de texto de preferência. Após isso você poderá executá-los a partir de qualquer componente do LibreOffice.

O primeiro passo é localizar onde os scripts de usuário são armazenados. Para isso, consulte a página de ajuda Organização e localização de scripts Python.

Agora você pode criar um arquivo texto dentro da pasta de scripts de usuário em Python, por exemplo sf_test.py, e começar a editar seus próprios scripts.

A seguir é dado um simples exemplo que recupera o valor numérico de uma célula em um documento Calc e incrementa esse valor em uma unidade. Simplesmente escreva o código a seguir no arquivo sf_test.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 uma função chamada increment_cell. Note que a tupla g_exportedScripts tem o papel de informar quais funções serão mostradas no LibreOffice como scripts de usuário.

Para executar este script a partir de um documento Calc:

Crie ou abra um arquivo Calc.
Entre algum valor numérico na célula "A1" da planilha atual.
Vá ao menu Ferramentas - Macros - Executar macro .
Escolha My Macros - sf_test no seletor de biblioteca. Em seguida, escolha a função increment_cell na lista Nome da macro .
Clique em Run. O valor da célula "A1" será incrementado em uma unidade.

Você também pode usar a extensão APSO para rodar scripts Python de maneira similar:

Primeiro abra a janela principal da extensão APSO indo em Ferramentas - Macros - Organize python scripts.
Na lista de macros, navegue até Minhas macros - sf_test - increment_cell .
Clique Execute.

Executando scripts separadamente do processo LibreOffice

Determinando o Caminho de Instalação

O primeiro passo para executar passos a partir de um processo separado é encontrar a pasta onde o LibreOffice está instalado. Há várias formas para fazer isso, mas o ScriptForge provê uma maneira rápida de identificar sua pasta 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)

A saída resultante do código acima é o diretório base onde o LibreOffice está instalado. Agora você precisa adicionar a subpasta "program" ao caminho resultante. Esta será a pasta base a partir da qual você executará scripts Python de um processo separado.

Por exemplo, suponha que você obtenha /usr/lib/libreoffice/ como o resultado após executar o código Python acima. Então você precisa considerar /usr/lib/libreoffice/program como o caminho para executar seus scripts Python.

Start LibreOffice with pipe or socket settings

Para executar scripts em Python de um processo separado, você tem quem inicializar o LibreOffice com alguns parâmetros adicionais para especificar o nome do host (hostname) e a porta (port) pela qual o processo externo irá se comunicar com o processo do componente do LibreOffice.

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

./soffice --accept='pipe,name=libreoffice;urp;'

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

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

Note that the previous example opens LibreOffice start center. If you want to open a specific component, for instance Writer, you can add the --writer flag to the command, as follows.

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

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

Executando um Shell Python Externo

Inicialize o shell Python de dentro da pasta program do diretório de instalação do LibreOffice. Siga os passosacima para aprender como encontrar o diretório de instalação.

No Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

No 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 LibreOffice. 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='libreoffice')


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

Leia a seção Configurando o PYTHONPATH abaixo em caso de erros ao importar scriptforge.py ou 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 LibreOffice process opened with the same pipe or socket settings.

Agora você pode executar outros comandos em Python e eles serão capazes de se comunicar com o processo do LibreOffice. Por exemplo:


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

Configurando o PYTHONPATH

Dependendo da configuração do seu sistema operacional você precisará definir a variável de ambiente PYTHONPATH para importar a biblioteca scriptforge.py, que por sua vez requer a importação da biblioteca uno. py.

Use a ferramenta de pesquisa de arquivos do seu sistema operacional para determinar o diretório onde esses dois arquivos estão localizados.

Por exemplo, em uma 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 desses arquivos será diferente para cada sistema operacional e método de instalação do LibreOffice.

A Biblioteca ScriptForge

Ajuda dos scripts Python do LibreOffice

Iniciar o LibreOffice com parâmetros