LibreOffice Module pyuno (master) 1
uno.py
Go to the documentation of this file.
1# -*- tab-width: 4; indent-tabs-mode: nil; py-indent-offset: 4 -*-
2#
3# This file is part of the LibreOffice project.
4#
5# This Source Code Form is subject to the terms of the Mozilla Public
6# License, v. 2.0. If a copy of the MPL was not distributed with this
7# file, You can obtain one at http://mozilla.org/MPL/2.0/.
8#
9# This file incorporates work covered by the following license notice:
10#
11# Licensed to the Apache Software Foundation (ASF) under one or more
12# contributor license agreements. See the NOTICE file distributed
13# with this work for additional information regarding copyright
14# ownership. The ASF licenses this file to you under the Apache
15# License, Version 2.0 (the "License"); you may not use this file
16# except in compliance with the License. You may obtain a copy of
17# the License at http://www.apache.org/licenses/LICENSE-2.0 .
18#
19import pyuno
20import sys
21import traceback
22import warnings
23
24# since on Windows sal3.dll no longer calls WSAStartup
25import socket
26
27# All functions and variables starting with a underscore (_) must be
28# considered private and can be changed at any time. Don't use them.
29_component_context = pyuno.getComponentContext()
30
31
33 """Returns the UNO component context used to initialize the Python runtime."""
34
35 return _component_context
36
37
39 """Returns the current context.
40
41 See http://udk.openoffice.org/common/man/concept/uno_contexts.html#current_context
42 for an explanation on the current context concept.
43 """
44
45 return pyuno.getCurrentContext()
46
47
48def setCurrentContext(newContext):
49 """Sets newContext as new UNO context.
50
51 The newContext must implement the XCurrentContext interface. The
52 implementation should handle the desired properties and delegate
53 unknown properties to the old context. Ensure that the old one
54 is reset when you leave your stack, see
55 http://udk.openoffice.org/common/man/concept/uno_contexts.html#current_context
56 """
57
58 return pyuno.setCurrentContext(newContext)
59
60
61def getConstantByName(constant):
62 """Looks up the value of an IDL constant by giving its explicit name."""
63
64 return pyuno.getConstantByName(constant)
65
66
67def getTypeByName(typeName):
68 """Returns a `uno.Type` instance of the type given by typeName.
69
70 If the type does not exist, a `com.sun.star.uno.RuntimeException` is raised.
71 """
72
73 return pyuno.getTypeByName(typeName)
74
75
76def createUnoStruct(typeName, *args, **kwargs):
77 """Creates a UNO struct or exception given by typeName.
78
79 Can be called with:
80
81 1) No additional argument.
82 In this case, you get a default constructed UNO structure.
83 (e.g. `createUnoStruct("com.sun.star.uno.Exception")`)
84 2) Exactly one additional argument that is an instance of typeName.
85 In this case, a copy constructed instance of typeName is returned
86 (e.g. `createUnoStruct("com.sun.star.uno.Exception" , e)`)
87 3) As many additional arguments as the number of elements within typeName
88 (e.g. `createUnoStruct("com.sun.star.uno.Exception", "foo error" , self)`).
89 4) Keyword arguments to give values for each element of the struct by name.
90 5) A mix of 3) and 4), such that each struct element is given a value exactly once,
91 either by a positional argument or by a keyword argument.
92
93 The additional and/or keyword arguments must match the type of each struct element,
94 otherwise an exception is thrown.
95 """
96
97 return getClass(typeName)(*args, **kwargs)
98
99
100def getClass(typeName):
101 """Returns the class of a concrete UNO exception, struct, or interface."""
102
103 return pyuno.getClass(typeName)
104
105
106def isInterface(obj):
107 """Returns True, when obj is a class of a UNO interface."""
108
109 return pyuno.isInterface(obj)
110
111
113 """Returns a 16 byte sequence containing a newly generated uuid or guid.
114
115 For more information, see rtl/uuid.h.
116 """
117
118 return pyuno.generateUuid()
119
120
121def systemPathToFileUrl(systemPath):
122 """Returns a file URL for the given system path."""
123
124 return pyuno.systemPathToFileUrl(systemPath)
125
126
128 """Returns a system path.
129
130 This path is determined by the system that the Python interpreter is running on.
131 """
132
133 return pyuno.fileUrlToSystemPath(url)
134
135
136def absolutize(path, relativeUrl):
137 """Returns an absolute file url from the given urls."""
138
139 return pyuno.absolutize(path, relativeUrl)
140
141
142class Enum:
143 """Represents a UNO enum.
144
145 Use an instance of this class to explicitly pass an enum to UNO.
146
147 :param typeName: The name of the enum as a string.
148 :param value: The actual value of this enum as a string.
149 """
150
151 def __init__(self, typeName, value):
152 self.typeName = typeName
153 self.value = value
154 pyuno.checkEnum(self)
155
156 def __repr__(self):
157 return "<Enum instance %s (%r)>" % (self.typeName, self.value)
158
159 def __eq__(self, that):
160 if not isinstance(that, Enum):
161 return False
162
163 return (self.typeName == that.typeName) and (self.value == that.value)
164
165 def __ne__(self,other):
166 return not self.__eq__(other)
167
168
169class Type:
170 """Represents a UNO type.
171
172 Use an instance of this class to explicitly pass a type to UNO.
173
174 :param typeName: Name of the UNO type
175 :param typeClass: Python Enum of TypeClass, see com/sun/star/uno/TypeClass.idl
176 """
177
178 def __init__(self, typeName, typeClass):
179 self.typeName = typeName
180 self.typeClass = typeClass
181 pyuno.checkType(self)
182
183 def __repr__(self):
184 return "<Type instance %s (%r)>" % (self.typeName, self.typeClass)
185
186 def __eq__(self, that):
187 if not isinstance(that, Type):
188 return False
189
190 return self.typeClass == that.typeClass and self.typeName == that.typeName
191
192 def __ne__(self,other):
193 return not self.__eq__(other)
194
195 def __hash__(self):
196 return self.typeName.__hash__()
197
198
199class Bool(object):
200 """Represents a UNO boolean.
201
202 Use an instance of this class to explicitly pass a boolean to UNO.
203
204 Note: This class is deprecated. Use Python's True and False directly instead.
205 """
206
207 def __new__(cls, value):
208 message = "The Bool class is deprecated. Use Python's True and False directly instead."
209 warnings.warn(message, DeprecationWarning)
210
211 if isinstance(value, str) and value == "true":
212 return True
213
214 if isinstance(value, str) and value == "false":
215 return False
216
217 if value:
218 return True
219
220 return False
221
222
223class Char:
224 """Represents a UNO char.
225
226 Use an instance of this class to explicitly pass a char to UNO.
227
228 For Python 3, this class only works with unicode (str) objects. Creating
229 a Char instance with a bytes object or comparing a Char instance
230 to a bytes object will raise an AssertionError.
231
232 :param value: A Unicode string with length 1
233 """
234
235 def __init__(self, value):
236 assert isinstance(value, str), "Expected str object, got %s instead." % type(value)
237
238 assert len(value) == 1, "Char value must have length of 1."
239 assert ord(value[0]) <= 0xFFFF, "Char value must be UTF-16 code unit"
240
241 self.value = value
242
243 def __repr__(self):
244 return "<Char instance %s>" % (self.value,)
245
246 def __eq__(self, that):
247 if isinstance(that, str):
248 if len(that) > 1:
249 return False
250
251 return self.value == that[0]
252
253 if isinstance(that, Char):
254 return self.value == that.value
255
256 return False
257
258 def __ne__(self,other):
259 return not self.__eq__(other)
260
261
263 """Represents a UNO ByteSequence value.
264
265 Use an instance of this class to explicitly pass a byte sequence to UNO.
266
267 :param value: A string or bytesequence
268 """
269
270 def __init__(self, value):
271 if isinstance(value, bytes):
272 self.value = value
273
274 elif isinstance(value, ByteSequence):
275 self.value = value.value
276
277 else:
278 raise TypeError("Expected bytes object or ByteSequence, got %s instead." % type(value))
279
280 def __repr__(self):
281 return "<ByteSequence instance '%s'>" % (self.value,)
282
283 def __eq__(self, that):
284 if isinstance(that, bytes):
285 return self.value == that
286
287 if isinstance(that, ByteSequence):
288 return self.value == that.value
289
290 return False
291
292 def __len__(self):
293 return len(self.value)
294
295 def __getitem__(self, index):
296 return self.value[index]
297
298 def __iter__(self):
299 return self.value.__iter__()
300
301 def __add__(self, b):
302 if isinstance(b, bytes):
303 return ByteSequence(self.value + b)
304
305 elif isinstance(b, ByteSequence):
306 return ByteSequence(self.value + b.value)
307
308 else:
309 raise TypeError("Can't add ByteString and %s." % type(b))
310
311 def __hash__(self):
312 return self.value.hash()
313
314
315class Any:
316 """Represents a UNO Any value.
317
318 Use only in connection with uno.invoke() to pass an explicit typed Any.
319 """
320
321 def __init__(self, type, value):
322 if isinstance(type, Type):
323 self.type = type
324 else:
325 self.type = getTypeByName(type)
326
327 self.value = value
328
329
330def invoke(object, methodname, argTuple):
331 """Use this function to pass exactly typed Anys to the callee (using uno.Any)."""
332
333 return pyuno.invoke(object, methodname, argTuple)
334
335
336# -----------------------------------------------------------------------------
337# Don't use any functions beyond this point; private section, likely to change.
338# -----------------------------------------------------------------------------
339_builtin_import = __import__
340
341
342def _uno_import(name, *optargs, **kwargs):
343 """Overrides built-in import to allow directly importing LibreOffice classes."""
344
345 try:
346 return _builtin_import(name, *optargs, **kwargs)
347 except ImportError as e:
348 # process optargs
349 globals, locals, fromlist = list(optargs)[:3] + [kwargs.get('globals', {}), kwargs.get('locals', {}),
350 kwargs.get('fromlist', [])][len(optargs):]
351
352 # from import form only, but skip if a uno lookup has already failed
353 if not fromlist or hasattr(e, '_uno_import_failed'):
354 raise
355
356 # hang onto exception for possible use on subsequent uno lookup failure
357 py_import_exc = e
358
359 mod = None
360 d = sys.modules
361
362 for module in name.split("."):
363 if module in d:
364 mod = d[module]
365 else:
366 # How to create a module ??
367 mod = pyuno.__class__(module)
368 if mod is None:
369 raise py_import_exc
370
371 d = mod.__dict__
372
373 RuntimeException = pyuno.getClass("com.sun.star.uno.RuntimeException")
374
375 for class_name in fromlist:
376 if class_name not in d:
377 failed = False
378
379 try:
380 # check for structs, exceptions or interfaces
381 d[class_name] = pyuno.getClass(name + "." + class_name)
382 except RuntimeException:
383 # check for enums
384 try:
385 d[class_name] = Enum(name, class_name)
386 except RuntimeException:
387 # check for constants
388 try:
389 d[class_name] = getConstantByName(name + "." + class_name)
390 except RuntimeException:
391 # check for constant group
392 try:
393 d[class_name] = _impl_getConstantGroupByName(name, class_name)
394 except ValueError:
395 failed = True
396
397 if failed:
398 # We have an import failure, but cannot distinguish between
399 # uno and non-uno errors as uno lookups are attempted for all
400 # "from xxx import yyy" imports following a python failure.
401 #
402 # In Python 3, the original python exception traceback is reused
403 # to help pinpoint the actual failing location. Its original
404 # message, unlike Python 2, is unlikely to be helpful for uno
405 # failures, as it most commonly is just a top level module like
406 # 'com'. So our exception appends the uno lookup failure.
407 # This is more ambiguous, but it plus the traceback should be
408 # sufficient to identify a root cause for python or uno issues.
409 #
410 # Our exception is raised outside of the nested exception
411 # handlers above, to avoid Python 3 nested exception
412 # information for the RuntimeExceptions during lookups.
413 #
414 # Finally, a private attribute is used to prevent further
415 # processing if this failure was in a nested import. That
416 # keeps the exception relevant to the primary failure point,
417 # preventing us from re-processing our own import errors.
418
419 uno_import_exc = ImportError("%s (or '%s.%s' is unknown)" %
420 (py_import_exc, name, class_name))
421
422 uno_import_exc = uno_import_exc.with_traceback(py_import_exc.__traceback__)
423
424 uno_import_exc._uno_import_failed = True
425 raise uno_import_exc
426
427 return mod
428
429
430try:
431 import __builtin__
432except ImportError:
433 import builtins as __builtin__
434
435# hook into the __import__ chain
436__builtin__.__dict__['__import__'] = _uno_import
437
438
439class _ConstantGroup(object):
440 """Represents a group of UNOIDL constants."""
441
442 __slots__ = ['_constants']
443
444 def __init__(self, constants):
445 self._constants = constants
446
447 def __dir__(self):
448 return self._constants.keys()
449
450 def __getattr__(self, name):
451 if name in self._constants:
452 return self._constants[name]
453
454 raise AttributeError("The constant '%s' could not be found." % name)
455
456
458 """Gets UNOIDL constant group by name."""
459
460 constants = Enum('com.sun.star.uno.TypeClass', 'CONSTANTS')
461 one = Enum('com.sun.star.reflection.TypeDescriptionSearchDepth', 'ONE')
462 type_desc_mgr = _component_context.getValueByName('/singletons/com.sun.star.reflection.theTypeDescriptionManager')
463 type_descs = type_desc_mgr.createTypeDescriptionEnumeration(module, (constants,), one)
464 qualified_name = module + '.' + group
465
466 for type_desc in type_descs:
467 if type_desc.Name == qualified_name:
468 return _ConstantGroup(dict(
469 (c.Name.split('.')[-1], c.ConstantValue)
470 for c in type_desc.Constants))
471
472 raise ValueError("The constant group '%s' could not be found." % qualified_name)
473
474
475def _uno_struct__init__(self, *args, **kwargs):
476 """Initializes a UNO struct.
477
478 Referenced from the pyuno shared library.
479
480 This function can be called with either an already constructed UNO struct, which it
481 will then just reference without copying, or with arguments to create a new UNO struct.
482 """
483
484 # Check to see if this function was passed an existing UNO struct
485 if len(kwargs) == 0 and len(args) == 1 and getattr(args[0], "__class__", None) == self.__class__:
486 self.__dict__['value'] = args[0]
487 else:
488 struct, used = pyuno._createUnoStructHelper(self.__class__.__pyunostruct__, args, **kwargs)
489
490 for kwarg in kwargs.keys():
491 if not used.get(kwarg):
492 RuntimeException = pyuno.getClass("com.sun.star.uno.RuntimeException")
493 raise RuntimeException("_uno_struct__init__: unused keyword argument '%s'." % kwarg, None)
494
495 self.__dict__["value"] = struct
496
497
499 """Gets attribute from UNO struct.
500
501 Referenced from the pyuno shared library.
502 """
503
504 return getattr(self.__dict__["value"], name)
505
506
507def _uno_struct__setattr__(self, name, value):
508 """Sets attribute on UNO struct.
509
510 Referenced from the pyuno shared library.
511 """
512
513 return setattr(self.__dict__["value"], name, value)
514
515
517 """Converts a UNO struct to a printable string.
518
519 Referenced from the pyuno shared library.
520 """
521
522 return repr(self.__dict__["value"])
523
524
526 """Converts a UNO struct to a string."""
527
528 return str(self.__dict__["value"])
529
530def _uno_struct__ne__(self, other):
531 return not self.__eq__(other)
532
533def _uno_struct__eq__(self, that):
534 """Compares two UNO structs.
535
536 Referenced from the pyuno shared library.
537 """
538
539 if hasattr(that, "value"):
540 return self.__dict__["value"] == that.__dict__["value"]
541
542 return False
543
544
546 """Extracts a printable stacktrace.
547
548 Referenced from pyuno shared lib and pythonscript.py.
549 """
550
551 return ''.join(traceback.format_tb(trace))
552
553# vim: set shiftwidth=4 softtabstop=4 expandtab:
Definition: uno.py:199
def __new__(cls, value)
Definition: uno.py:207
def __getitem__(self, index)
Definition: uno.py:295
def __add__(self, b)
Definition: uno.py:301
def __repr__(self)
Definition: uno.py:280
def __eq__(self, that)
Definition: uno.py:283
def __hash__(self)
Definition: uno.py:311
def __init__(self, value)
Definition: uno.py:270
def __len__(self)
Definition: uno.py:292
def __iter__(self)
Definition: uno.py:298
Definition: uno.py:223
def __init__(self, value)
Definition: uno.py:235
def __eq__(self, that)
Definition: uno.py:246
value
Definition: uno.py:241
def __repr__(self)
Definition: uno.py:243
def __ne__(self, other)
Definition: uno.py:258
Definition: uno.py:142
def __repr__(self)
Definition: uno.py:156
def __ne__(self, other)
Definition: uno.py:165
typeName
Definition: uno.py:152
def __init__(self, typeName, value)
Definition: uno.py:151
def __eq__(self, that)
Definition: uno.py:159
value
Definition: uno.py:153
Definition: uno.py:169
def __ne__(self, other)
Definition: uno.py:192
def __init__(self, typeName, typeClass)
Definition: uno.py:178
typeName
Definition: uno.py:179
def __repr__(self)
Definition: uno.py:183
def __eq__(self, that)
Definition: uno.py:186
typeClass
Definition: uno.py:180
def __hash__(self)
Definition: uno.py:195
def __dir__(self)
Definition: uno.py:447
def __init__(self, constants)
Definition: uno.py:444
def __getattr__(self, name)
Definition: uno.py:450
PyRef getClass(const OUString &name, const Runtime &runtime)
def generateUuid()
Definition: uno.py:112
def absolutize(path, relativeUrl)
Definition: uno.py:136
def _uno_struct__repr__(self)
Definition: uno.py:516
_builtin_import
Definition: uno.py:339
def _uno_struct__str__(self)
Definition: uno.py:525
def _uno_struct__ne__(self, other)
Definition: uno.py:530
def invoke(object, methodname, argTuple)
Definition: uno.py:330
def _uno_import(name, *optargs, **kwargs)
Definition: uno.py:342
def getCurrentContext()
Definition: uno.py:38
def getClass(typeName)
Definition: uno.py:100
def _uno_extract_printable_stacktrace(trace)
Definition: uno.py:545
def getComponentContext()
Definition: uno.py:32
def _uno_struct__setattr__(self, name, value)
Definition: uno.py:507
def createUnoStruct(typeName, *args, **kwargs)
Definition: uno.py:76
def isInterface(obj)
Definition: uno.py:106
def fileUrlToSystemPath(url)
Definition: uno.py:127
def getConstantByName(constant)
Definition: uno.py:61
def systemPathToFileUrl(systemPath)
Definition: uno.py:121
def _impl_getConstantGroupByName(module, group)
Definition: uno.py:457
def getTypeByName(typeName)
Definition: uno.py:67
def _uno_struct__getattr__(self, name)
Definition: uno.py:498
def setCurrentContext(newContext)
Definition: uno.py:48
def _uno_struct__init__(self, *args, **kwargs)
Definition: uno.py:475
def _uno_struct__eq__(self, that)
Definition: uno.py:533