Python as a macro language

From Apache OpenOffice Wiki
Revision as of 20:26, 17 January 2007 by Jza (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Pyuno supports the OOo scripting framework, that is first shipped with OOo 2.0. The current support is limited to the core framework, meaning that execution and assigning of macros via the standard Tools/Macro dialog works fine, but editing and debugging macros is not integrated in's UI (simply because of the lack of development resources). Use your favourite text editor to create and modify python scripts.

Script Location

Scripts to be excuted in can be stored within the following locations:'s user directory

This is the standard place for self written python scripts. The script files are simply stored within the file system. On windows, the directory can typically be found in:

  • windows - C:\Documents and Settings\<current-user\>Application Data\ 2.0\user\Scripts\python
  • unix - ~/

Note, that the last python subdirectory may need to be created initially. Make sure, the python is completly written lowercase. You can add arbitrary deeply nested subdirectories, the names of these directories are reflected in the UI.

Example: The file can simply be placed in the above directory. Afterwards, open the Tools/Macros/Run macro dialog and navigate to the position shown in the above picture. Click on Run to execute the python script, which opens another dialog with a push button and a label field. Clicking the button will increase the number within the label field. The dialog can be closed by pressing ESC.'s share directory

Scripts that shall be shared throughout all users of a concrete installation can be stored with the share directory. All default scripts coming with are located here. In general, this directory should not be used for script deployment (see later uno-packages).

The script files are simply stored within the file system. The directory can typically be found in

  • windows C:\Program Files\ 2.0\share\Scripts\python
  • unix ~/

Embedded within an's document

An document is a zip-File, which contains different files. Python scripts within documents are stored in Scripts/python subdirectory.

If you want to ship your self written python scripts within a document, you should first develop your scripts in the (above mentioned) user directory and then finally move the scripts into the document with your favorite zip tool. However, note that you must reassign every binding you did before to the script instances in the document. Ideally, you move away the scripts from the user directory and do a regression test on the document's functionality.

After moving the script files into the document, you have to add some lines (boldly printed) to the META-INF/manifest.xml file: [xml] <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE manifest:manifest PUBLIC "-// Manifest 1.0//EN" "Manifest.dtd"> <manifest:manifest xmlns:manifest="">

<manifest:file-entry manifest:media-type="application/vnd.oasis.opendocument.text" manifest:full-path="/"/>
<manifest:file-entry manifest:media-type="application/vnd.sun.xml.ui.configuration" manifest:full-path="Configurations2/"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Pictures/"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="content.xml"/>
<manifest:file-entry :media-type="text/xml" manifest:full-path="styles.xml"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="meta.xml"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/thumbnail.png"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="settings.xml"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Scripts/python/"/>
<manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/python/"/>
<manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/"/>

</manifest:manifest> When you open the document afterwards, the's UI should warn you about script content within the document (when this is not the case, you either have switched off the warning in the options or you did something wrong).

Example:To see how it works, download push_me_python4.odt. The document contains a push button and a multi line edit control. Pressing the button adds a new line with the current time stamp to the multi line edit control.

Embedded within a uno-package in's user directory (read only)

Often, distributing scripts in documents is not what you want (for instance when you want to modify the application itself or you want to use the same scripts with multiple documents ). Therefor you can place your scripts simply within uno-packages.

A uno-package is a zip-file. Its name must end with .pkg, otherwise it does not work. file, where you must define the subdirectory (required!) that shall contain scripts. For instance the sample has the following file structure: [bash] META-INF/ META-INF/manifest.xml package/ package/ The contains the scripts. How to write scripts is explained below. However, in order to make a script work within a uno package, you must add some dummy code. [python]

  1. ... here is the python script code
  1. this must be added to every script file (the
  2. name org.openoffice.script.DummyImplementationForPythonScripts should be changed to something
  3. different (must be unique within an office installation !)
  4. --- faked component, dummy to allow registration with unopkg, no functionality expected

import unohelper g_ImplementationHelper = unohelper.ImplementationHelper() g_ImplementationHelper.addImplementation( \ None,"org.openoffice.script.DummyImplementationForPythonScripts", \


By default, every .py-file is interpreted as a UNO component. Not having the above lines within the .py file would raise errors during deployment.

The directory name (here package) can be choosen freely. A uno-package with a python script must contain a META-INF/manifest.xml, which needs to point to the freely chosen directory name. [xml] <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE manifest:manifest PUBLIC "-// Manifest 1.0//EN" "Manifest.dtd"> <manifest:manifest xmlns:manifest=""> <manifest:file-entry manifest:media-type="application/" manifest:full-path="package"/> </manifest:manifest> Every user can add packages via the package manager (Tools/Package manager). Note, that content within the package is by design readonly, it is really a pure deployment, not a development mechanism. This might be the reason, why scripts in packages cannot be viewed via Tools/Macros/Organize macros/Python dialog. Embedded within a uno-package in's share directory (read only)

Packages can be added by an administrator to a complete installation, so that every user can use run the macros located within the package. This can be done with the unopkg tool.

Script coding

A python script within the's scripting framework is a function (introduced by the def keyword) within a .py file. For execution via the Tools/Macros/Run macro dialog, the script must have an empty argument list. For typical event listeners, the function must have exactly one argument (the event). In general, the number of arguments depend on the context where the function shall be used. Currently, the .py file must use unix line feeds, this will be changed in future.

A single .py file may contain an arbitrary number of function definitions. By default, all function definitions are exported ( = shown in the macro selection dialog). As this may become tedious, exports can be limited to a smaller set of functions by having a global variable named g_exportedScripts, which is a tuple of function definitions.

At the current integration level, .py files can only import python modules, which are within the python PYTHONPATH, by default this is just the python runtime and the uno bridge files. This means, that it cannot reference other python macro files. This limitation may be changed in future but exists currently.

Before executing the source code within the module, the global variable XSCRIPTCONTEXT is inserted as global variable within the module (this variable also exists e.g. for javascript and beanshell, it is offered here for consistency reasons). It has three members (Document,Desktop and ComponentContext).

The comment of a function (introduced and ended by three ") is shown as description in the macros' selection dialog.

The compiled python script files are not added to sys.modules. There may exist multiple instances of the same module at the same time. Example: [python] # HelloWorld python script for the scripting framework

def HelloWorldPython( ):

   """Prints the string 'Hello World(in Python)' into the current document"""
   #get the doc from the scripting context which is made available to all scripts
   model = XSCRIPTCONTEXT.getDocument()
   text = model.Text
   cursor = text.createTextCursor()
   text.insertString( cursor, "Hello World(in Python)", 0 )

Error handling and debugging

Errors during compilation or execution of the scripts are passed as exceptions to the scripting framework where possible. The scripting framework in general opens a popup box and displays the message of the thrown exception.

However, sometimes this is not possible and an error gets silently ignored. The user realizes these errors, when

  • his python script file does not appear where it is expected to be
  • the name of the script file appears, but it does not contain any scripts
  • only part of the script gets executed.

You can get to know these problems by changing some flags in the 2.0/program/ file :

[python]# Configuration ---------------------------------------------------- LogLevel.use = LogLevel.NONE # alternavly use LogLevel.ERROR or LogLevel.DEBUG LOG_STDOUT = False # True, writes to stdout

                                           # False, writes to user/Scripts/python/log.txt

ENABLE_EDIT_DIALOG=False # offers a minimal editor for editing. Attaching a python debugger is currently not supported.


The python binding of the scripting framework is developed and maintained by Joerg Budischewski in his spare time. Many, many thanks to Tomas O'Connor from Sun for his great support and his code additions to the framework which made this binding possible. Please put low level questions about the binding to Questions about the's API should be put to

Personal tools