Python Language Binding

From Apache OpenOffice Wiki
Jump to: navigation, search


The Python language binding allows developers to work with UNO in Python language.

This page describes detaile of the binding. Writing macros or UNO component in Python is described in dedicated pages for them.

uno Module

The binding is implemented in Python extension module pyuno and additional module uno. Some types are defined in uno module and the binding is not work without these values.

Classes for Types

The following classes represents corresponding UNO types.

class uno.Enum(typeName, value)

This class represents an enum value defined in UNO. typeName specifies name of an enum and value specifies name of a value. The specified values are checked during the initialization. When wrong name is specified, RuntimeError is raised.

class uno.Type(typeName, typeClass)

This class is dedicated to be used as type type of UNO. typeName specifies name of value type of UNO and typeClass specifies type class of the type in uno.Enum. List of type class is defined in com.sun.star.uno.TypeClass enum. The type name have to be valid for the reflection API. The sequence can be represented with [], e.g. []long or [][]string. When wrong name is specified, RuntimeError is raised.

uno.getTypeByName() method returns instance of the class from type name only. And also, the type can be requested by import statement with "typeOf" prefix.

The following line adds typeOfXEventListener variable having type of com.sun.star.lang.XEventListener.

 from com.sun.star.lang import typeOfXEventListener

class uno.Char(value)

This class represents char type of UNO. value should be an unicode character.

class uno.ByteSequence(value)

All str and unicode are converted to string type when they are passed to UNO. Therefore, this class is used to tell the string should be converted to []byte. value is string or uno.ByteSequence value to be wrapped.

Since Python 3, uno.ByteSequence, bytes and bytearray are allowed.

class uno.Any(type, value)

The bridge based on the invocation has problem about type conversion in few cases. type specifies the type of value to be converted in uno.Type or string that represents a type. value is real value to be converted to specified type.

Module Functions

The following functions are defined in uno module but real function is provided by pyuno module.

uno.getComponentContext()

Initialize the bridge and returns the UNO component context that was used to initialize. When the bridge is loaded by the instance of Python working as part of the office, the return value of this method is match with the instance of the component context represents the instance of current office. But when the bridge is initialized to be used as a bridge for RPC connection, this method returns local component context and it is the different component context from remote one, they can not be replaced each other. Therefore, using this method to get component context is not good manner if your script is intended to be executed both macros and RPC scripts.

uno.getConstantByName(constant)

Looks up the value that defined in IDL. constant specifies a value of enum or a value of constants.

uno.getTypeByName(typeName)

Returns new instance of uno.Type. typeName specifies name of UNO type. See uno.Type also.

uno.createUnoStruct(typeName, *args)

Returns new instance of structs or exceptions defined in IDL.typeName specifies name of a struct or an exception. Additional arguments can be passed to be initial value. Number of them can be matched with definition of the type to be initialized and the order of the

uno.getClass(typeName)

Returns class for struct, exception or interface of UNO. This class defines new class and returns. If the class defined already, it is returned. typeName specifies one of struct, interface or exception.

uno.isInterface(obj)

This function checks the passed obj is a class of UNO interface. True is returned if the value is a class of UNO interface, otherwise False is returned.

uno.generateUuid()

Generates new UUID version 4 that is used to identify the type of interfaces defined in Python. Return value is instance of uno.ByteSequence.

uno.systemPathToFileUrl(systemPath)

Converts system dependent path to file URL.

uno.fileUrlToSystemPath(url)

Converts file URL to system dependent path.

uno.absolutize(path, relativeUrl)

Extends relative URL specified by relativeUrl based on path.

uno.getCurrentContext()

Returns currently used context to instantiate services.

uno.setCurrentContext(newContext)

Sets current context to be used to instantiate services.

uno.invoke(object, methodname, argTuple)

Calls method with exactly typed arguments using uno.Any. object is the UNO value where the method specified by methodname is called. argTuple specifies arguments in tuple that allows to use uno.Any type to type the value exactly.

Type Mappings

The following table shows type mapping between UNO and Python for simple types.

UNO Python
void None
boolean bool
byte long/int[1]
short long
unsigned short long
long long
unsigned long long
hyper long
unsigned hyper long
float float
double float
char uno.Char
string unicode/str[2]
type uno.Type
any uno.Any[3]
  • [1] No long type is there in Python 3, the value converted into int.
  • [2] Python 3 uses Unicode string as normal string.
  • [3] It is used only with uno.invoke method.

Mapping of Integer Types

The numerical types are converted to different types depending on their range of value.

Mapping of String

Any string type is coming from UNO is unicode even that contain only 7 bit range characters. Both unicode and str are valid string to pass them to UNO.

Since Python 3, only str is valid but bytes is no longer converted as string type.

Mapping of Type

This type is defined in uno module that constructor takes type name of the type and type class of the type. The new instance of the type will be checked by the binding to avoid invalid type. Its instance variables can be changed after the instantiation, but do not try to change them.

New value can be taken also with uno.getTypeByName() method without type class to specify.

The import hook provided by uno module allows to instantiate uno.Type in import statement with typeOf prefix. For example, from com.sun.star.lang import typeOfXEventListener adds typeOfEventListener variable and set its type value to it.

Mapping of Any

This type is not passed from UNO because the value wrapped by it is extracted and converted into Python value.

The usage of this type is to tell the type of value with uno.invoke() method.

Mapping of Sequence

A sequence comes from UNO is converted to tuple of Python. And also you have to pass instance of tuple to UNO, list of Python is not allowed.

Mapping of Struct

The bridge defines classes for UNO structs at runtime. To request to generate a class for a struct, import the struct or call uno.getClass() function.

Mapping of Exception

Exceptions are also defined at runtime by the bridge as described in struct section. But all exceptions inherit Exception of Python so that its instance can be raised or trapped by try and except statements.

Mapping of Enum

This type is described by uno.Enum class.

Mapping of Constants

Static values defined in constant groups can be imported with import statement or uno.getConstantByName() function.

Mapping of Interface

All interfaces come from UNO are represented by PyUNO class that works as proxy to call method, to get access to their property values. And resultant values are resolved by the bridge and

Working with PyUNO Instance

Implements Interfaces

If complex value of Python is passed to UNO, the bridge checks the class of the value is prepared to support com.sun.star.lang.XTypeProvider interface. The information about supported interface types is required to generate invocation adapter that behaves as normal UNO component. And calling the method and request to get and set property values are delegated to the instance of Python value.

There is easy way to support XTypeProvider interface provided by unohelper module. Define your class and inherit unohelper.Base class that provides getTypes and getImplementationId methods.

Personal tools