Python UNO Components to Control LibreOffice

Controlling LibreOffice externally using standalone Python scripts relies on the Python-UNO (PyUNO) bridge, a specialized interface enabling direct communication with the LibreOffice Universal Network Objects (UNO) API. To establish this control, standalone scripts combine LibreOffice’s IPC connection parameters with core Python modules such as uno and unohelper, alongside essential UNO services like the UnoUrlResolver, ServiceManager, and the Desktop component. Together, these components initialize inter-process communication, resolve remote contexts, and allow scripts to programmatically create, modify, and convert documents.

Inter-Process Communication Setup

Before Python can interact with LibreOffice, the LibreOffice process must run in listening mode (often headlessly) to accept incoming connections over a socket or named pipe. This is typically initialized via the command line:

soffice --headless --accept="socket,host=localhost,port=2002;urp;StarOffice.ServiceManager"

The uno Module

The uno module is the primary Python interface for the PyUNO runtime. In a standalone script, it provides: * uno.getComponentContext(): Retrieves the initial local component context required to bootstrap communications. * uno.createUnoStruct(): Instantiates UNO-specific data structures (such as com.sun.star.beans.PropertyValue), which are necessary for passing parameters like file filters, passwords, or hidden window states to LibreOffice methods. * uno.ByteSequence(): Handles raw binary data streams between Python and UNO.

The unohelper Module

The unohelper module provides utility functions and base classes to bridge Python and UNO architecture seamlessly: * Path Conversion: Functions like unohelper.systemPathToFileUrl() convert standard local file paths into the file:// URL format required by UNO components. * Interface Inheritance: The unohelper.Base class allows custom Python classes to implement UNO interfaces, enabling event listening and callbacks within standalone scripts.

The UNO URL Resolver (com.sun.star.bridge.UnoUrlResolver)

To connect to an active LibreOffice instance, the standalone script uses the UnoUrlResolver service. Created via the local context, its resolve() method parses the UNO connection string:

uno:socket,host=localhost,port=2002;urp;StarOffice.ServiceManager

This call returns the remote XComponentContext, providing the script with access to the running LibreOffice environment.

The Service Manager (com.sun.star.lang.ServiceManager)

The remote ServiceManager (accessed via remoteContext.getServiceManager()) acts as the factory for creating any UNO service available inside LibreOffice. It translates high-level service requests from the standalone script into live remote objects.

The Desktop Component (com.sun.star.frame.Desktop)

Instantiated via the remote ServiceManager, the Desktop service (com.sun.star.frame.Desktop) is the central engine for document manipulation: * loadComponentFromURL(): Opens existing files, creates blank documents (using templates like private:factory/swriter or private:factory/scalc), and applies configuration properties. * getCurrentComponent(): Accesses the active document model. * terminate(): Closes the LibreOffice process cleanly when batch operations complete.