Text Documents (Writer)
HTML Documents (Writer Web)
Spreadsheets (Calc)
Presentations (Impress)
Drawings (Draw)
Database Functionality (Base)
Formulae (Math)
Charts and Diagrams
Macros and Scripting
Office Installation
Common Help Topics
OneOffice Logo

Programming with Python Scripts

A Python macro is a function within a .py file, identified as a module. Unlike Office Basic and its dozen of UNO objects functions or services, Python macros use the XSCRIPTCONTEXT UNO single object, shared with JavaScript and BeanShell. The g-exportedScripts global tuple explicitly lists selectable macros from a module. Python modules hold autonomous code logic, and are independent from one another.


Genuine Basic UNO facilities can be inferred from XSCRIPTCONTEXT global variable. Refer to Office API for a complete description of XSCRIPTCONTEXT. XSCRIPTCONTEXT methods summarize as:

Methods Description Mapped in Basic as
getDocument() The document reference on which the script can operate. ThisComponent
getDesktop() The desktop reference on which the script can operate. StarDesktop
getComponentContext() The component context which the script can use to create other UNO components. GetDefaultContext

HelloWorld and Capitalise installation shared scripts illustrate UNO-related macros making use of XSCRIPTCONTEXT global variable.

Python standard output file is not available when running Python macros from Tools - Macros - Run Macro menu. Refer to Input/Output to Screen for more information.

Module import

XSCRIPTCONTEXT is not provided to imported modules.

Office Basic libraries contain classes, routines and variables, Python modules contain classes, functions and variables. Common pieces of reusable Python or UNO features must be stored in My macros within (User Profile)/Scripts/python/pythonpath. Python libraries help organise modules in order to prevent module name collisions. Import uno.py inside shared modules.

Genuine BASIC UNO facilities can be inferred using uno.py module. Use Python interactive shell to get a complete module description using dir() and help() Python commands.

Functions Description Mapped in Basic as
absolutize() Returns an absolute file URL from the given URLs.
createUnoStruct() Creates a UNO struct or exception given by typeName. CreateUNOStruct()
fileUrlToSystemPath() Returns a system path. ConvertFromURL()
getClass() Returns the class of a concrete UNO exception, struct, or interface.
getComponentContext() Returns the UNO component context used to initialise the Python runtime. GetDefaultContext()
Enum() getConstantByName() Looks up the value of an IDL constant by giving its explicit name. See API constant groups
isInterface() Returns True, when obj is a class of a UNO interface.
systemPathToFileUrl() Returns a file URL for the given system path. ConvertToURL()

LibreLogo and TableSample installation shared scripts use uno.py module.

More Python-Basic samples

Python UNO Basic UNO features
ctx = uno.getComponentContext() smgr = ctx.getServiceManager() obj = smgr.createInstanceWithContext( .. , ctx) CreateUnoService()
See Opening a Dialog CreateUnoDialog()
See Creating a Listener CreateUnoListener()
See UNO data types CreateUnoValue() CreateObject()
ctx = uno.getComponentContext() smgr = ctx.getServiceManager() GetProcessServiceManager()
def hasUnoInterfaces(obj, *interfaces): return set(interfaces).issubset(t.typeName for t in obj.Types) HasUnoInterfaces()
ctx = uno.getComponentContext() smgr = ctx.getServiceManager() DESK = 'com.sun.star.frame.Desktop' desktop = smgr.createInstanceWithContext(DESK , ctx) StarDesktop
desktop = smgr.createInstanceWithContext(DESK , ctx) doc = desktop.CurrentComponent ThisComponent

Importing an embedded Module

Similarly to Office Basic that supports browsing and dynamic loading of libraries, Python libraries can be explored and imported on demand. For more information on library containers, visit Office Application Programming Interface (API) or download Office Software Development Kit (SDK).

Importing a Python document embedded module is illustrated below, exception handling is not detailed:

            import uno, sys
            def load-library(library-name: str, module-name=None):
                """ load library and import module
                Adapted from 'Bibliothèque de fonctions' by Hubert Lambert
                at https://forum.openoffice.org/fr/forum/viewtopic.php?p=286213"""
                doc = XSCRIPTCONTEXT.getDocument()  # current document
                url = uno.fileUrlToSystemPath( \
                    '{}/{}'.format(doc.URL, 'Scripts/python'+library-name))  # ConvertToURL()
                if not url in sys.path:  # add path if necessary
                    sys.path.insert(0, url)  # doclib takes precedence
                if module-name:  # import if requested
                    return zipimport.zipimporter(url).load-module(module-name)
            def import-embedded-python():
                ui = load-library("my-gui",'screen-io')  # add  path + import 
            g-exportedScripts = (import-embedded-python,)  # Public macros