Python-UNO bridge 0.9.2

- Introduction
- State
- Changes
- Installation guide
-- Binary
-- Source
- External references
- UNO type mapping
- Implementing UNO objects
- Implementing UNO components
- Out parameter handling
- Exception handling
- Dependencies
- Bootstrapping in non-OOo environments
- unohelper module
- Authors
- License

Introduction

You should find the most current version of this document at http://udk.openoffice.org/python/python-bridge.html

State

The Python-UNO bridge is in a beta state. It runs with the instable OpenOffice.org 1.1 source tree (to be more exact with the OO643C version). It does not run with an OpenOffice.org 1.0.x source tree.

PyUNO can be downloaded as a separate binary package, it does not come with the default OpenOffice.org installation. This may change in future, when a signifcant number of people have shown interest in PyUNO. So if you think, that PyUNO should be part of OOo installation, raise your voice on the dev@udk.openoffice.org mailing list.

The documentation in its current state is targeted at developers, who have already some experience with OpenOffice.org API with some other programmaing language (Java/C++/StarBasic). If you are a newbie and you think, that some background information is missing, you should try the developer manual mentioned in the external reference section.

Changes

• Version 0.9.2

    fixed bugs:
      - #i11487# PyUNO interfaces are not transitive
      - python list aren't accepted anymore in place of UNO
        sequences. Only tuples are accepted.
      - unicode string conversions should now also work on systems
        where sizeof( wchar_t ) == 4
  
    changes:
      - The source is now available from the OOo CVS repository.
      - uno.ByteSequence (idl sequence) is now treated
        differently than before (this is an incompatible change).
        See documentation for more information)
      - file url conversion routines added (API calls need file urls)
        ( unohelper.systemPathToFileUrl(), unohelper.fileUrlToSystemPath(),
          unohelper.absolutize())
      - added two more samples.
        * ooextract.py extracts pure text from a given OOo document
        and dumps it on stdout (which allows you to grep through
        OOo documents :o) )
  
        * biblioaccess.py is a small example showing how
          to access the database API within OOo.
      - uno.Bool is now deprecated, instead python True and False
        are used.	
  
    changes in source distribution:
      - build -i for the windows python build is not
        necessary anymore.
      - Build environment has changed. Only the d.lst and the
        makefile in the python module depends now on the concrete
        used python version. This should make python version
        changes easier in future. 
  
    changes in binary distribution:
      - pyuno ships now with a precompiled python runtime.
        This is necessary, because pyuno and python must
        be compiled with the same compiler version of gcc
        on unix platforms. 
      - therefor, pyuno's environment files pyunoenv.[bat|tcsh]
        have simplified a little.
  
  

1. If you are new to pyuno, skip to the next step. If you have used pyuno in version 0.9.1 on the same OOo installation, where you want to install the new version, you should first delete files belonging to the older version to avoid confusion. The following files should be deleted

   all platforms:
   program/pydemo
   program/uno.py
   program/unohelper.py
   program/pythonloader.py
   
   additionally on windows:
   program/pyuno.dll
   program/pycpld.dll
   program/pyuno_setup.bat
   program/regcomp.exe
   program/pyunoenv.bat
   program/pyuno.ini                                     
   
   addtiionally on unix:
   program/pyuno_setup.sh
   program/libpyuno.so
   program/libpycpld.so
   program/regcomp
   program/pyunoenv.tcsh
   program/pyuno.so
   program/libpython.so
   program/pyunorc                                                                   
   

   Note that pyuno now ships with a python runtime, so you don't need to install python anymore.
2. Download and install an OpenOffice643C build (see http://www.openoffice.org )
3. Download the Python-UNO bridge for your platform

   windows http://udk.openoffice.org/python/download/pyuno-win32-0.9.2.zip
   linux x86 http://udk.openoffice.org/python/download/pyuno-linux-x86-0.9.2.tar.gz
   linux-ppc ftp://ftp.yellowdoglinux.com/pub/yellowdog/software/openoffice/pyuno-linux-ppc-0.9.2.tar.gz (and its mirrors).

4. Start a shell ( tcsh on linux, cmd shell on windows ) and switch to the OpenOffice.org installation directory (e.g. /home/joe/OpenOffice.org643).
5. Unzip the Python-UNO installation set into the office installation directory.

   e.g. Linux:

        joe@foobar:/home/joe/OpenOffice.org643> gunzip < pyuno-linux-x86-0.9.2.tar.gz | tar -xvf -
        

6. Switch to the program directory (e.g. /home/joe/OpenOffice.org643/program)
7. Fire up your favourite text editor and edit the pyunoenv.tcsh (linux) or pyunoenv.bat (windows). Please set the OOOHOME variables appropriately in these files, e.g. (linux)

   setenv OOOHOME /home/joe/OpenOffice.org643
   

   or (windows)
   set OOOHOME=c:\programs\OpenOffice.org643

8. On linux, source the pyunoenv.tcsh script ( source pyunoenv.tcsh ), on windows simply start the pyunoenv.bat batch file (you must redo this step for every new shell).
9. Start the ./pyuno_setup[.sh|.bat] script. It will register two components to the office installation. When everything runs successful, you should get the following output:

   register component "pycpld" in registry "applicat.rdb" succesful!
    
   register component "swritercomp" in registry "applicat.rdb" succesful!                            
        

   If you get an error message, have a look at the troubleshooting section below.

Make sure, that the office doesn't run. Start the office from a python prepared shell ( do the pyunoenv step above). In order to let the demos run, start the office with

./soffice "-accept=socket,host=localhost,port=2002;urp;"

Now start the swriter demo script

python pydemo/swriter.py

It should connect to the office, create a new document and put some text and a table into it. Note that this swriter.py example does the same things as the swriter.java example, which comes with the OpenOffice.org development kit. If you have some java source code and you are unsure how to translate it to python, you might have a look at these source files to get an idea how to do this.

Additionally, there comes a python UNO component named swritercomponent.py, which implements the com.sun.star.lang.XMain interface. The only method run() does the same thing as the swriter.py example, the only difference is, that it is run within the OpenOffice.org process, which improves performance. You may either trigger the python component in the office directory from another python script

python pydemo/swritercompclient.py

or you may use the following Basic script via Tools/Macro/New macro

dim args()
pycomp = createUnoService( "org.openoffice.demo.SWriter" )
pycomp.run( args )

Troubleshooting

1. I can't find a pyunoenv.tcsh (or .bat) file
   Make sure to extract the pyuno bridge files into the toplevel directory of the OpenOffice.org installation. There should go multiple files into program subdirectory.
2. An error occurs during the the python pyuno_setup.py step.
   Make sure, that you have filled out the pyunoenv.bat (pyunoenv.tcsh) correctly, check especially for typos in the pathes.

Note for python 0.9.1 users ! When you want to build pyuno 0.9.2 in a solver tree, which already contains pyuno 0.9.1, you should first remove the files from the solver tree. These are the

your-platform/bin/python[.exe]
your-platform/lib/[lib]pycpld.[dll|so]
your-platform/lib/[lib]python.[dll|so]
your-platform/lib/[lib]pyuno.[dll|so]
your-platform/lib/python2.2  (whole directory)
your-platform/inc/python2.2  (whole directory)

Linux: Please add the following line to your LinuxIntelEnv.Set (Attention 0.9.1-users: The pathes have changed ! )

setenv PYTHONPATH .:"$SOLARVER"/"$UPD"/"$INPATH"/lib/python:
         	    "$SOLARVER"/"$UPD"/"$INPATH"/lib/python/lib-dynload

set PYTHONPATH=.;%SOLARVER%\%UPD%\%INPATH%\lib\python;
		 %SOLARVER%\%UPD%\%INPATH%\lib\python\lib-dynload

1. external/python
   This module builds the external python source. Put the python source tar file into the python/download directory, but make sure to rename it from Python-2.2.2.tgz to Python-2.2.2.tar.gz. (Note: Currently, you must use the Python-2.2.2 version !)

   Build and deliver this project.

2. udk/pyuno
   The following table gives an overview about the pyuno project.

   prj              -- build details
   source/module    -- contains the core Python-UNO bridge and 
                       the module, that is loaded my the python executable.
   		    The result is a shared C++ library, to which the python loader
   		    links to.
   source/loader    -- contains the UNO loader for python components
   inc/pyuno        -- contains exported API for the python module. 
   unotypes         -- generates the types needed for the bridge
   test             -- contains test python scripts. In order to execture the tests,
                       simply type dmake test
   demo             -- contains demo python scripts and a makefile
                       , which creates a deployment file for the OO643C build.
   

   Build this project. In order to run the tests, you need to get a HEAD version of the testtools project, which currently does not get built by default, build and deliver the testtools project. Afterwards run the tests in the pyuno/test directory using dmake runtest, you shouldn't get any errors there. Deliver this project.

   From now on, you can use UNO python scripts in the build environment, e.g. create some glue code for some UNO components to do a certain job. In the build environment, only the core UNO components to make the bridge work are preregistered. Have a look at the Bootstrapping section below to see, how you can register your components. The really nice thing is that you now can do UNO just with a text editor without any compilation :o).

External references

# idl signatore foo( [in] string value )
# both lines are valid
unoObject.foo( u'my foo string' )
unoObject.foo( 'my foo string' )

# idl signature foo( [in] char c)
unoObject.foo( uno.Char( u'h' ) )  #valid
unoObject.foo( 'h' )               #wrong

# idl signature XInterface createInstanceWithArguments(
#                        [in] string servicename,  [in] sequence <any> )
doc = smgr.createInstanceWithArguments( "foo.service", ("arg1",2))

# idl signature writeBytes( [in] sequence%lt; byte > data )
#
out.writeBytes( uno.ByteSequence( "abc" ) )

# you could also write the following
begin = uno.ByteSequence( "ab" )
out.writeBytes( begin + "c" )

# but this does not work !
out.writeBytes( "abc" ) # ERROR, no implict conversion supported by the runtime !


# idl signature long readBytes( [out] sequence<byte> , [in] length )
len,seq = in.readBytes( dummy, 3 )

# the statements do the same thing 
print seq == "abc":
print seq == uno.ByteSequence( "abc" )

from com.sun.star.beans.PropertyConcept import ATTRIBUTES
.
.
.
# the following 3 lines are equivalent
unoObject.setConcept( ATTRIBUTES )
unoObject.setConcept( 4 )
unoObject.setConcept( uno.getConstantByName( "com.sun.star.beans.PropertyConcept.ATTRIBUTES" ) )

To be an UNO object, a python class MUST implement the com.sun.star.lang.XTypeProvider interface by implementing two methods getTypes() and getImplementationId(), which inform the python-UNO bridge, which concrete UNO interfaces the python class implements. The getTypes() function defines, which interfaces are implemented by the class.

To make this easier, there exists a unohelper.Base class, where a python UNO object should derive from. You can then implement a UNO interface simply by deriving from the wanted interfaces. The following example implements a com.sun.star.io.XOutputStream, which stores all data written into the stream within a ByteSequence. (Note that this is quite a poor implementation, which is just for demonstration purposes).

import unohelper from com.sun.star.io import XOutputStream class SequenceOutputStream( unohelper.Base, XOutputStream ): def __init__( self ): self.s = uno.ByteSequence("") self.closed = 0 def closeOutput(self): self.closed = 1 def writeBytes( self, seq ): self.s = self.s + seq def flush( self ): pass def getSequence( self ): return self.s

From the list of base classes given (here only XOutputStream), the unohelper.Base implementation correctly implements the XTypeProvider interface.

Implementing Python UNO components

If the reader is unfamilar with the component registration process, it should visit the OpenOffice.org developer manual for a comprehensive explanation.

The python loader supports currently supports the following protocols for incoming urls.

Protocol name	Description
vnd.openoffice.pymodule	The protocol dependend part is interpreted as a python module name, which is imported using the common python import mechanism (which uses the PYTHONPATH environment variable). After the module has been imported, the python loader looks for a module-global variable with the name g_ImplementationHelper, which is expected to be an instance of unohelper.ImplementationHelper

More protocols may be supported in future (e.g. absolute file urls ). The following sample code makes a uno component out of the above UNO object ( note that the component is neither useful, because there is no UNO method to retrieve the tuple nor does a com.sun.star.io.OutputStream service specification exist, it's just here as an example).

import unohelper from com.sun.star.io import XOutputStream g_ImplementationHelper = unohelper.ImplementationHelper() class TupleOutputStream( unohelper.Base, XOutputStream ): # The component must have a ctor with the component context as argument. def __init__( self, ctx ): self.t = () self.closed = 0 # idl void closeOutput(); def closeOutput(self): self.closed = 1 # idl void writeBytes( [in] sequence seq ); def writeBytes( self, seq ): self.t = self.t + seq # simply add the incoming tuple to the member # idl void flush(); def flush( self ): pass # convenience function to retrieve the tuple later (no UNO function, may # only be called from python ) def getTuple( self ): return self.t # add the TupleOutputStream class to the implementation container, # which the loader uses to register/instantiate the component. g_ImplementationHelper.addImplementation( \ TupleOutputStream,"org.openoffice.pyuno.PythonOutputStream", ("com.sun.star.io.OutputStream",),)

Lets assume, that this code is stored in a file named tuplestrm.py and the file exists somewhere within the PYTHONPATH variable, it can be registered to an OO643C build with the following command :

regcomp -register -br applicat.rdb -r applicat.rdb -c vnd.openoffice.pymodule:tuplestrm

The component can be instantiated e.g. from OpenOffice Basic with

tupleStrm = createUnoService( "com.sun.star.io.OutputStream" ) tupleStrm.flush()

Out parameter handling

long foo( [in] long first, [inout] long second, [out] third )

class Dummy( XFoo ):
    def foo( self, first,second,third):
        # Note: the value of third is always None, but it must be there
	#       as a placeholder if more args would follow !
        return first,2*second,second + first	

ret,second,third = unoObject.foo( 2, 5 , None )
print ret,second,third    # results into 2,10,7

However, note that

• you must have the correct number of return values either in the calling and implementing code, otherwise you will get a RuntimeException during the call.
• a void method always returns a None followed by possible out parameters, so when you have a void method with one out parameter you must assign the output to two variables (though the first one will always be None).
• a python object implementing a void method with out parameters MUST always return None as the first parameter.

Example for catching

from com.sun.star.uno import RuntimeException from com.sun.star.lang import IllegalArgumentException from com.sun.star.connection import NoConnectException try: uuresoler.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext" ) except NoConnectException e: print "The OpenOffice process is not started or does not listen on the resource ("+e.Message+")" except IllegalArgumentException e: print "The url is invalid ( "+ e.Message+ ")" except RuntimeException e: print "An unknown error occured: " + e.Message

Example for throwing

class TupleOutputStream(XOutputStream,unohelper.Base): def writeBytes( self, seq ): if self.closed: raise IOException( "Output stream already closed", self ) self.t = self.t + seq

Dependencies

Unlike the Java or C++ UNO binding, the python UNO binding is not self contained. It requires the C++ UNO binding and additional scripting components. These additional components currently live in the shared libraries tcv,inv,corefl,insp,invadp,proxyfac,pycpld (on windows tcv.dll,inv.dll,etc.; unix libtcv.so, etc.).

Often, the components for setting up an interprocess connection are additonally required. These are uuresolver,connectr,remotebridge,brdgfctr shared libraries.

The path environment variables ( LD_LIBRARY_PATH on unix, PATH on windows) must point to a directory, where the core UNO libraries, the above listed components and the pyuno shared library is located. (On unix, there exists two files: libpyuno.so containing the code and a pyuno.so which is needed for importing a native python module). Additionally, the python module uno.py, unohelper.py and pythonloader.py must be located in a directory, which is listed in the PYTHONPATH environment variable.

Bootstrapping pyuno from the python executable

When the uno module gets first imported from an arbitrary python script, it must bootstrap a properly prepared UNO component context.

# bootstraps the uno component context import uno # retrieve the already bootstrapped component context unoContext = uno.getComponentContext()

As the python programmer can't (and probably doesn't want to) give parameters during importing a module, the python-uno binding uses the pyuno[rc|.ini] file located beside the pyuno shared library to bootstrap the UNO context (see uno bootstrap variable concept). The bootstrap variables UNO_SERVICES must point to a registry file, where the above given components got registered to.

PYUNOLIBDIR is a special bootstrap variable, which contains the path to the currently used pyuno shared library. Example:

# The bootstrap variable PYUNOLIBDIR will be set by the pyuno runtime library UNO_TYPES=$PYUNOLIBDIR/applicat.rdb UNO_SERVICES=$PYUNOLIBDIR/pyuno_services.rdb

If the above preconditions are fulfilled, the script can simply be started with

$ python myscript.py

Sometimes it is preferable to mention the librarynames of the desired components directly within the script instead of preparing a registry (however note that the above mentioned bootstrap components always needs to be registered in a registry). This can be achieved by using the function unohelper.addComponentsToContext( toBeExtendedContext, contextRuntime, componentUrls, loaderName )

Example:

import uno import unohelper localContext = uno.getComponentContext() unohelper.addComponentsToContext( localContext, localContext, ("stm",), "com.sun.star.loader.SharedLibrary") pipe = localContext.ServiceManager.createInstanceWithContext( "com.sun.star.io.Pipe", localContext ) pipe.writeBytes( uno.ByteSequence( "abc" ) ) ret,seq = pipe.readBytes( None, 3 )

unohelper module

Please use the dev@udk.openoffice.org mailing list for further questions.

License