Como executar scripts Python em macros do LibreOffice Calc

Sim. O LibreOffice Calc pode executar código Python como uma macro dentro do processo do LibreOffice, e uma macro Basic do LibreOffice também pode chamar uma função Python através da estrutura de scripts do LibreOffice. Se o seu objetivo é ler ou alterar células na planilha aberta, uma macro Python em execução no mesmo processo geralmente é o ponto de partida mais simples. Use uma chamada de Basic para Python quando uma macro Basic existente precisar delegar uma tarefa a uma função Python reutilizável.

Essas abordagens são diferentes da execução de um script Python comum do sistema com um comando do shell. Um processo Python externo normal não recebe automaticamente o objeto de documento do Calc. Para acessar a planilha, execute uma macro Python por meio do LibreOffice ou conecte deliberadamente um processo externo a uma instância do LibreOffice por meio do UNO.

O que significa "executar Python dentro de uma macro do Calc"?

O LibreOffice oferece suporte a várias linguagens de script por meio de sua estrutura de scripts. Em uma macro Python, o LibreOffice fornece um objeto de contexto UNO que permite que o script acesse o documento atual e suas planilhas. Uma macro Python é uma função em um .pymódulo; a g_exportedScriptstupla do módulo identifica as funções que o LibreOffice deve exibir como macros executáveis.

Uma macro em Python pode ser executada diretamente do menu de macros do Calc. Ela não precisa ser chamada pelo Basic. Se você já possui uma macro em Basic e deseja que ela chame Python, o provedor de scripts do LibreOffice ou o Session.ExecutePythonScriptserviço mais recente ScriptForge podem fazer a ponte entre as duas linguagens.

Qual abordagem você deve escolher?

• Use uma macro Python diretamente quando a tarefa for principalmente em Python e precisar do documento Calc atual. Isso evita a transferência de linguagem e é mais fácil de depurar, pois consiste em um único script.
• Chame o Python a partir do Basic quando você já tiver código Basic, botões ou eventos de documento que devem permanecer no lugar, e quiser que um auxiliar do Python execute um cálculo ou operação de dados específica.
• Utilize um processo Python externo quando precisar de um ambiente de desenvolvimento separado ou de pacotes Python não incluídos no LibreOffice. Configure uma conexão UNO explícita; não presuma que um script iniciado a partir de um terminal possa acessar a planilha aberta.

Por exemplo, uma pequena ferramenta de limpeza de planilha pode ser escrita inteiramente como uma macro em Python. Se um botão existente em Basic já executa um relatório, mantenha a macro do botão e faça com que ela chame uma função em Python que calcule o total do relatório.

Como criar uma macro em Python que edite células do Calc?

O LibreOffice armazena scripts Python pessoais no perfil do usuário, scripts globais do aplicativo no diretório de instalação e scripts de documento junto com o documento. Para um primeiro teste, um script pessoal é conveniente porque fica disponível em qualquer documento do LibreOffice aberto pelo mesmo usuário. No entanto, ele não é incluído em um arquivo ODS, portanto, outra pessoa não o receberá automaticamente com a planilha.

Encontre a pasta de scripts Python pessoais do seu sistema na Ajuda do LibreOffice, em "Organização e localização de scripts Python". Os locais comuns são %APPDATA%\LibreOffice\4\user\Scripts\pythonno Windows e ~/.config/libreoffice/4/user/Scripts/pythonno Linux. O perfil em si pode variar; use o local documentado para a sua instalação em vez de criar um segundo diretório de perfil por tentativa e erro.

Crie um arquivo com o nome calc_tools.pyna pasta de scripts Python pessoais e adicione este exemplo simples:

def double_a1(args=None):
    doc = XSCRIPTCONTEXT.getDocument()
    sheet = doc.getCurrentController().getActiveSheet()

    source = sheet.getCellRangeByName("A1")
    target = sheet.getCellRangeByName("B1")
    target.setValue(source.getValue() * 2)

g_exportedScripts = (double_a1,)

Esta função lê o valor numérico na célula A1 da planilha ativa e copia esse valor duas vezes para a célula B1. XSCRIPTCONTEXTEla é fornecida a uma macro Python do LibreOffice em tempo de execução; não é uma variável global Python comum quando o mesmo arquivo é aberto fora do LibreOffice. A função pública está listada no arquivo `package.json`, g_exportedScriptsportanto, aparece no seletor de macros.

Salve o arquivo e, em seguida, abra ou retorne ao Calc e escolha Ferramentas > Macros > Executar Macros . Dependendo da versão do LibreOffice ou da tradução da plataforma, o rótulo do menu pode estar no singular. Selecione Minhas Macros > calc_tools > double_a1 e execute-o. Digite um número em A1 primeiro e verifique se B1 contém o valor dobrado. Se o módulo não aparecer, confirme se a extensão do arquivo é .py .py, se o arquivo está na pasta Python do perfil correto e se o suporte a scripts Python está instalado. Reiniciar o LibreOffice após adicionar um novo módulo pode ajudar a atualizar a lista de scripts.

Como uma macro BASIC pode chamar uma função Python?

Para converter um código Basic para Python, coloque um módulo Python na pasta de scripts pessoais e chame sua função através do Sessionserviço do ScriptForge. Este exemplo soma dois valores em Python e escreve o resultado na célula B1 da planilha do Calc atual.

Em calc_tools.py, defina a função:

def add_values(first, second):
    return float(first) + float(second)

g_exportedScripts = (add_values,)

Em seguida, crie uma macro básica no Calc e use:

Sub RunPythonHelper()
    Dim session As Object
    Dim result As Variant
    Dim sheet As Object

    session = CreateScriptService("Session")
    result = session.ExecutePythonScript( _
        session.SCRIPTISPERSONAL, _
        "calc_tools.py$add_values", _
        12, 30)

    sheet = ThisComponent.CurrentController.getActiveSheet()
    sheet.getCellRangeByName("B1").setValue(result)
End Sub

Execute RunPythonHelpera partir do seletor de macros Básico. Se a chamada for bem-sucedida, B1 deverá exibir 42. A referência do script segue o formato module.py$function_name; para um módulo em uma subpasta ou outro local de armazenamento, use a sintaxe e a constante de localização documentadas para essa versão do ScriptForge. Mantenha os argumentos e valores de retorno em tipos de dados que ambas as linguagens possam representar claramente, como números, strings e sequências simples.

CreateScriptServiceOs auxiliares de sessão do ScriptForge documentados estão disponíveis nas versões modernas do LibreOffice, mas os nomes dos menus e os componentes incluídos podem ser diferentes em versões mais antigas ou em pacotes de distribuição. Se esse serviço não estiver disponível, use o método UNO script-provider documentado do LibreOffice, que obtém um XScriptscript a partir de um URI e o invoca. Evite copiar um fragmento de código para um local de macro diferente sem alterar sua configuração de localização.

O código Python deve ser pessoal, compartilhado ou incorporado?

Para um fluxo de trabalho em equipe, defina como os destinatários receberão e confiarão no código antes de criar uma planilha em torno de uma macro pessoal. Se a lógica em Python precisar acompanhar a planilha, teste o armazenamento de macros e os avisos de segurança do documento nas mesmas versões do LibreOffice que seus destinatários utilizam. Para implantação gerenciada, um administrador pode empacotar scripts para os usuários ou distribuir uma extensão sob os controles de software normais da organização.

Por que a macro pode estar faltando ou falhar?

• A opção ou módulo Python está ausente. Em algumas distribuições GNU/Linux, o framework de script Python do LibreOffice é um pacote opcional. Verifique as instruções de instalação do LibreOffice na sua distribuição caso as macros Python não apareçam na caixa de diálogo de macros.
• O script foi salvo no perfil errado. O LibreOffice permite o uso de múltiplos perfis de usuário. Confirme o caminho do perfil da instalação em execução e salve o módulo no Scripts/pythondiretório correspondente.
• A função não está exportada. Adicione-a g_exportedScriptspara uma função que você pretende executar a partir do seletor de macros. Certifique-se de que a sintaxe da tupla inclua a vírgula final para uma tupla de um único item.
• O script é executado fora do LibreOffice. XSCRIPTCONTEXT Ele existe para uma macro iniciada pelo LibreOffice, não quando o mesmo arquivo é iniciado com o pythoncomando do sistema. Use o executor de macros ou configure uma conexão UNO documentada.
• A segurança de macros bloqueia o código incorporado. Revise as configurações de segurança de macros do LibreOffice e habilite apenas o código de uma fonte confiável. Diminuir o nível de segurança global não é uma boa solução paliativa para problemas.
• Um módulo importado não consegue acessar o contexto do documento. Documentos do LibreOffice que XSCRIPTCONTEXTnão são passados ​​para módulos importados. Passe o objeto de documento ou planilha necessário para funções auxiliares em vez de esperar que os módulos importados leiam esse contexto global.
• Não há saída visível no console. A saída padrão do Python não está disponível quando uma macro é executada a partir do menu Ferramentas > Macros. Para obter feedback, escreva o resultado em uma célula, use um serviço de diálogo do LibreOffice ou registre em um caminho de arquivo específico.

Como verificar o resultado com segurança?

Faça o teste com uma cópia da planilha e uma entrada conhecida. Confirme se a macro Python aparece no executor, execute-a uma vez e compare a célula de saída com um resultado calculado manualmente. Para uma chamada de Basic para Python, teste uma entrada simples e confirme se o valor retornado é gravado na planilha desejada. Evite começar com scripts que excluem planilhas, sobrescrevem grandes intervalos ou executam comandos do sistema operacional.

Quando o teste funcionar, decida como o script será instalado em outros computadores e documente quaisquer bibliotecas Python necessárias ou versões do LibreOffice pressupostas. O ambiente Python incluído no LibreOffice é o usado para macros em processo; pacotes instalados para um interpretador Python de sistema separado podem não estar disponíveis para ele. Se você precisar de pacotes de outro interpretador, use a abordagem de processo externo/UNO e configure essa conexão deliberadamente.

Referências oficiais

• Ajuda do LibreOffice: Criando scripts Python com o ScriptForge
• Ajuda do LibreOffice: Chamando scripts Python a partir do Basic
• Ajuda do LibreOffice: Programação com scripts Python
• Ajuda do LibreOffice: Organização e localização de scripts Python
• Ajuda do LibreOffice: Lendo e escrevendo valores em intervalos
• SDK do LibreOffice: Interface XScript