Cómo ejecutar scripts de Python en las macros de LibreOffice Calc

Sí. LibreOffice Calc puede ejecutar código Python como una macro dentro del proceso de LibreOffice, y una macro de LibreOffice Basic también puede llamar a una función de Python a través del entorno de scripting de LibreOffice. Si su objetivo es leer o modificar celdas en la hoja de cálculo abierta, una macro de Python dentro del proceso suele ser el punto de partida más sencillo. Utilice una llamada de Basic a Python cuando una macro de Basic existente deba delegar una tarea a una función de Python reutilizable.

Estos métodos difieren de ejecutar un script de Python del sistema con un comando de shell. Un proceso externo de Python no recibe automáticamente el objeto de documento de Calc. Para acceder a un libro de trabajo, ejecute una macro de Python a través de LibreOffice o conecte un proceso externo a una instancia de LibreOffice mediante UNO.

¿Qué significa “ejecutar Python dentro de una macro de Calc”?

LibreOffice admite varios lenguajes de scripting a través de su marco de trabajo. En una macro de Python, LibreOffice proporciona un objeto de contexto UNO que permite que el script acceda al documento actual y sus hojas. Una macro de Python es una función dentro de un .pymódulo; la g_exportedScriptstupla del módulo identifica las funciones que LibreOffice debe mostrar como macros ejecutables.

Una macro de Python puede ejecutarse de forma independiente desde el menú de macros de Calc. No es necesario que Basic la llame. Si ya tiene una macro de Basic y desea que llame a Python, el proveedor de scripts de LibreOffice o el nuevo Session.ExecutePythonScriptservicio ScriptForge pueden servir de puente entre ambos lenguajes.

¿Qué enfoque debería elegir?

• Utilice una macro de Python directamente cuando la tarea se base principalmente en Python y requiera el documento Calc actual. Esto evita la necesidad de cambiar de lenguaje y facilita la depuración al tratarse de un único script.
• Llama a Python desde Basic cuando ya tengas código Basic, botones o eventos de documento que deban permanecer en su lugar, y quieras que una función auxiliar de Python realice un cálculo o una operación de datos específica.
• Utilice un proceso Python externo cuando necesite un entorno de desarrollo independiente o paquetes Python no incluidos en LibreOffice. Configure una conexión UNO explícita; no dé por sentado que un script ejecutado desde una terminal puede acceder a la hoja de cálculo abierta.

Por ejemplo, una pequeña herramienta de limpieza de hojas de cálculo se puede escribir completamente como una macro de Python. Si un botón de Basic ya genera un informe, conserve la macro del botón y haga que llame a una función de Python que calcule el total del informe.

¿Cómo se crea una macro de Python para editar celdas de Calc?

LibreOffice almacena los scripts personales de Python en el perfil del usuario, los scripts de la aplicación en el directorio de instalación y los scripts de los documentos junto con el documento. Para una primera prueba, un script personal resulta práctico, ya que está disponible desde cualquier documento de LibreOffice abierto para el mismo usuario. Sin embargo, no se incluye en un archivo ODS, por lo que otra persona no lo recibirá automáticamente con la hoja de cálculo.

Encuentra la carpeta de scripts de Python de tu sistema en la Ayuda de LibreOffice, en la sección «Organización y ubicación de los scripts de Python». Las ubicaciones más comunes incluyen %APPDATA%\LibreOffice\4\user\Scripts\pythonWindows y ~/.config/libreoffice/4/user/Scripts/pythonLinux. La ubicación real puede variar; utiliza la documentada para tu instalación en lugar de crear un segundo directorio de perfil al azar.

Crea un archivo con ese nombre calc_tools.pyen la carpeta de scripts de Python personales y luego agrega este sencillo ejemplo:

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 función lee el valor numérico de la celda A1 de la hoja activa y escribe el doble de ese valor en la celda B1. XSCRIPTCONTEXTSe proporciona a una macro de Python de LibreOffice en tiempo de ejecución; no es una variable global de Python habitual cuando el mismo archivo se ejecuta fuera de LibreOffice. La función pública g_exportedScriptsaparece en el selector de macros.

Guarda el archivo, luego abre o regresa a Calc y elige Herramientas > Macros > Ejecutar macros . Dependiendo de la versión de LibreOffice o la traducción de la plataforma, la etiqueta del menú puede ser singular. Selecciona Mis macros > calc_tools > double_a1 y ejecútala. Primero introduce un número en A1, luego verifica que B1 contenga el valor duplicado. Si el módulo no aparece, confirma que la extensión del archivo sea .py .py, que el archivo esté en la carpeta Python del perfil correcto y que la compatibilidad con scripts de Python esté instalada. Reiniciar LibreOffice después de agregar un nuevo módulo puede ayudar a actualizar la lista de scripts.

¿Cómo puede una macro de Basic llamar a una función de Python?

Para realizar una llamada de Basic a Python, coloque un módulo de Python en la carpeta de scripts personales y llame a su función a través del Sessionservicio de ScriptForge. Este ejemplo suma dos valores en Python y escribe el resultado en la celda B1 de la hoja de cálculo actual.

En calc_tools.py, defina la función:

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

g_exportedScripts = (add_values,)

Luego, crea una macro básica en Calc y usa:

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

Ejecutar RunPythonHelperdesde el selector de macros Básico. Si la llamada se realiza correctamente, B1 debería mostrar 42. La referencia del script sigue el formato module.py$function_name; para un módulo en una subcarpeta u otra ubicación de almacenamiento, utilice la sintaxis y la constante de ubicación documentadas para esa versión de ScriptForge. Mantenga los argumentos y los valores de retorno en tipos de datos que ambos lenguajes puedan representar correctamente, como números, cadenas y secuencias simples.

CreateScriptServiceLas funciones auxiliares de sesión de ScriptForge documentadas están disponibles en las versiones modernas de LibreOffice, pero los nombres de los menús y los componentes incluidos pueden variar en versiones anteriores o en paquetes de distribución. Si este servicio no está disponible, utilice el método documentado del proveedor de scripts UNO de LibreOffice, que obtiene un XScriptscript a partir de su URI y lo ejecuta. Evite copiar un fragmento de código para una ubicación de macro diferente sin modificar su configuración de ubicación.

¿El código Python debe ser personal, compartido o estar integrado?

Para un flujo de trabajo en equipo, decida cómo los destinatarios recibirán y confiarán en el código antes de crear un libro de trabajo basado en una macro personal. Si la lógica de Python debe acompañar a la hoja de cálculo, pruebe el almacenamiento de macros y las indicaciones de seguridad del documento en las mismas versiones de LibreOffice que utilizan sus destinatarios. Para una implementación controlada, un administrador puede empaquetar scripts para los usuarios o distribuir una extensión bajo los controles de software habituales de la organización.

¿Por qué podría faltar la macro o fallar?

• La opción o módulo de Python no está disponible. En algunas distribuciones GNU/Linux, el entorno de scripting de Python de LibreOffice es un paquete opcional. Si las macros de Python no aparecen en el cuadro de diálogo de macros, consulte las instrucciones de instalación de LibreOffice de su distribución.
• El script se guardó en el perfil incorrecto. LibreOffice admite varios perfiles de usuario. Confirme la ruta del perfil de la instalación en ejecución y guarde el módulo en su Scripts/pythondirectorio.
• La función no se exporta. Agréguela g_exportedScriptspara una función que desee ejecutar desde el selector de macros. Asegúrese de que la sintaxis de la tupla incluya la coma final para una tupla de un solo elemento.
• El script se ejecuta fuera de LibreOffice. XSCRIPTCONTEXT Existe para una macro iniciada por LibreOffice, no cuando el mismo archivo se abre con el pythoncomando del sistema. Utilice el ejecutor de macros o configure una conexión UNO documentada.
• La seguridad de macros bloquea el código incrustado. Revisa la configuración de seguridad de macros de LibreOffice y habilita solo el código de fuentes confiables. Reducir el nivel de seguridad global no es una buena solución rápida para solucionar problemas.
• Un módulo importado no puede ver el contexto del documento. LibreOffice documenta que XSCRIPTCONTEXTno se pasa a los módulos importados. Pase el objeto de documento u hoja necesario a las funciones auxiliares en lugar de esperar que los módulos importados lean esa variable global.
• No se muestra ninguna salida en la consola. La salida estándar de Python no está disponible al ejecutar una macro desde el menú Herramientas > Macros. Para obtener información, escriba el resultado en una celda, utilice un servicio de diálogo de LibreOffice o registre la salida en una ruta de archivo específica.

¿Cómo se verifica el resultado de forma segura?

Prueba con una copia de la hoja de cálculo y una entrada conocida. Confirma que la macro de Python aparece en el ejecutor, ejecútala una vez y compara la celda de salida con un resultado calculado manualmente. Para una llamada de Basic a Python, prueba con una entrada simple y confirma que el valor devuelto se escribe en la hoja deseada. Evita comenzar con scripts que eliminen hojas, sobrescriban rangos grandes o ejecuten comandos del sistema operativo.

Cuando la prueba funcione, decida cómo se instalará el script en otros equipos y documente las bibliotecas de Python necesarias o las suposiciones sobre la versión de LibreOffice. El entorno de Python incluido en LibreOffice es el que se utiliza para las macros en proceso; es posible que los paquetes instalados para un intérprete de Python de sistema independiente no estén disponibles. Si necesita paquetes de otro intérprete, utilice el método de proceso externo/UNO y configure esa conexión de forma específica.

Referencias oficiales

• Ayuda de LibreOffice: Creación de scripts de Python con ScriptForge
• Ayuda de LibreOffice: Llamar a scripts de Python desde Basic
• Ayuda de LibreOffice: Programación con scripts de Python
• Ayuda de LibreOffice: Organización y ubicación de los scripts de Python
• Ayuda de LibreOffice: Lectura y escritura de valores en rangos
• SDK de LibreOffice: Interfaz XScript