pyatspi/accessible.py

   1 '''
   2 Creates functions at import time that are mixed into the
   3 Accessibility.Accessible base class to make it more Pythonic.
   4
   5 Based on public domain code originally posted at
   6 U{http://wwwx.cs.unc.edu/~parente/cgi-bin/RuntimeClassMixins}.
   7
   8 @var _ACCESSIBLE_CACHE: Pairs hash values for accessible objects to
   9   L{_PropertyCache} bags. We do not store actual accessibles in the dictionary
  10   because that would +1 their ref counts and cause __del__ to never be called
  11   which is the method we rely on to properly invalidate cache entries.
  12 @type _ACCESSIBLE_CACHE: dictionary
  13 @var _CACHE_LEVEL: Current level of caching enabled. Checked dynamically by
  14   L{_AccessibleMixin}
  15 @type _CACHE_LEVEL: integer
  16
  17 @author: Peter Parente
  18 @organization: IBM Corporation
  19 @copyright: Copyright (c) 2005, 2007 IBM Corporation
  20 @license: LGPL
  21
  22 This library is free software; you can redistribute it and/or
  23 modify it under the terms of the GNU Library General Public
  24 License as published by the Free Software Foundation; either
  25 version 2 of the License, or (at your option) any later version.
  26
  27 This library is distributed in the hope that it will be useful,
  28 but WITHOUT ANY WARRANTY; without even the implied warranty of
  29 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  30 Library General Public License for more details.
  31
  32 You should have received a copy of the GNU Library General Public
  33 License along with this library; if not, write to the
  34 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  35 Boston, MA 02111-1307, USA.
  36
  37 Portions of this code originally licensed and copyright (c) 2005, 2007
  38 IBM Corporation under the BSD license, available at
  39 U{http://www.opensource.org/licenses/bsd-license.php}
  40 '''
  41 import new
  42 import types
  43 import ORBit
  44 import Accessibility
  45 import constants
  46 import utils
  47 import registry
  48
  49 _ACCESSIBLE_CACHE = {}
  50 _CACHE_LEVEL = None
  51
  52 class _PropertyCache(object):
  53   '''Fixed-size bag class for holding cached values.'''
  54   __slots__ = ('name', 'description', 'rolename')
  55
  56 def getCacheLevel():
  57   '''
  58   Gets the current level of caching.
  59
  60   @return: None indicating no caching is in effect.
  61     L{constants.CACHE_INTERFACES} indicating all interface query results are
  62     cached. L{constants.CACHE_PROPERTIES} indicating all basic accessible
  63     properties are cached.
  64   @rtype: integer
  65   '''
  66   return _CACHE_LEVEL
  67
  68 def setCacheLevel(val):
  69   '''
  70   Sets the desired level of caching for all accessible objects created after
  71   this function is invoked. Immediately clears the current accessible cache.
  72
  73   @param val: None indicating no caching is in effect.
  74     L{constants.CACHE_INTERFACES} indicating all interface query results are
  75     cached. L{constants.CACHE_PROPERTIES} indicating all basic accessible
  76     properties are cached plus all interfaces.
  77   @type val: integer
  78   '''
  79   global _CACHE_LEVEL
  80   if _CACHE_LEVEL != val:
  81     # empty our accessible cache
  82     _ACCESSIBLE_CACHE.clear()
  83     # need to register/unregister for listeners depending on caching level
  84     if val == constants.CACHE_PROPERTIES:
  85       r = registry.Registry()
  86       r.registerEventListener(_updateCache, *constants.CACHE_EVENTS)
  87     else:
  88       r = registry.Registry()
  89       r.deregisterEventListener(_updateCache, *constants.CACHE_EVENTS)
  90   _CACHE_LEVEL = val
  91
  92 def clearCache():
  93   '''Forces a clear of the entire cache.'''
  94   _ACCESSIBLE_CACHE.clear()
  95
  96 def printCache(template='%s'):
  97   '''
  98   Prints the contents of the cache.
  99
 100   @param template: Format string to use when printing
 101   @type template: string
 102   '''
 103   print template % _ACCESSIBLE_CACHE
 104
 105 def _updateCache(event):
 106   '''
 107   Invalidates an entry in the cache when the hash value of a source of an event
 108   matches an entry in the cache.
 109
 110   @param event: One of the L{constants.CACHE_EVENTS} event types
 111   @type event: L{event.Event}
 112   '''
 113   try:
 114     del _ACCESSIBLE_CACHE[hash(event.source)]
 115   except KeyError:
 116     return
 117
 118 def _makeQuery(iid):
 119   '''
 120   Builds a function querying to a specific interface and returns it.
 121
 122   @param iid: Interface identifier to use when querying
 123   @type iid: string
 124   @return: Function querying to the given interface
 125   @rtype: function
 126   '''
 127   def _inner(self):
 128     '''
 129     Queries an object for another interface.
 130
 131     @return: An object with the desired interface
 132     @rtype: object
 133     @raise NotImplementedError: When the desired interface is not supported
 134     '''
 135     try:
 136       i = self._icache[iid]
 137     except KeyError:
 138       # interface not cached
 139       caching = True
 140     except TypeError:
 141       # determine if we're caching
 142       caching = _CACHE_LEVEL is not None
 143       if caching:
 144         # initialize the cache
 145         self._icache = {}
 146     else:
 147       # check if our cached result was an interface, or an indicator that the
 148       # interface is not supported
 149       if i is None:
 150         raise NotImplementedError
 151       else:
 152         return i
 153
 154     try:
 155       # do the query remotely
 156       i = self.queryInterface(iid)
 157     except Exception, e:
 158       raise LookupError(e)
 159     if i is None:
 160       # cache that the interface is not supported
 161       if caching:
 162         self._icache[iid] = None
 163       raise NotImplementedError
 164
 165     if caching:
 166       # cache the narrow'ed result, but only if we're caching for this object
 167       self._icache[iid] = i
 168     return i
 169
 170   return _inner
 171
 172 def _makeExceptionHandler(func):
 173   '''
 174   Builds a function calling the one it wraps in try/except statements catching
 175   CORBA exceptions.
 176
 177   @return: Function calling the method being wrapped
 178   @rtype: function
 179   '''
 180   def _inner(self, *args, **kwargs):
 181     try:
 182       # try calling the original func
 183       return func(self, *args, **kwargs)
 184     except ORBit.CORBA.NO_IMPLEMENT, e:
 185       # raise Python exception
 186       raise NotImplementedError(e)
 187     except ORBit.CORBA.Exception, e:
 188       # raise Python exception
 189       raise LookupError(e)
 190   return _inner
 191
 192 def _mixInterfaces(cls, interfaces):
 193   '''
 194   Add methods for querying to interfaces other than the base accessible to
 195   the given class.
 196
 197   @param cls: Class to mix interface methods into
 198   @type cls: class
 199   @param interfaces: Classes representing AT-SPI interfaces
 200   @type interfaces: list of class
 201   '''
 202   # create functions in this module for all interfaces listed in constants
 203   for interface in interfaces:
 204     # build name of converter from the name of the interface
 205     name = 'query%s' % utils.getInterfaceName(interface)
 206     # build a function that queries to the given interface
 207     func = _makeQuery(utils.getInterfaceIID(interface))
 208     # build a new method that is a clone of the original function
 209     method = new.function(func.func_code, func.func_globals, name,
 210                           func.func_defaults, func.func_closure)
 211     # add the method to the given class
 212     setattr(cls, name, method)
 213
 214 def _mixExceptions(cls):
 215   '''
 216   Wraps all methods and properties in a class with handlers for CORBA
 217   exceptions.
 218
 219   @param cls: Class to mix interface methods into
 220   @type cls: class
 221   '''
 222   # get a method type as a reference from a known method
 223   method_type = Accessibility.Accessible.getRole.__class__
 224   # loop over all names in the new class
 225   for name in cls.__dict__.keys():
 226     obj = cls.__dict__[name]
 227     # check if we're on a protected or private method
 228     if name.startswith('_'):
 229       continue
 230     # check if we're on a method
 231     elif isinstance(obj, method_type):
 232       # wrap the function in an exception handler
 233       method = _makeExceptionHandler(obj)
 234       # add the wrapped function to the class
 235       setattr(cls, name, method)
 236     # check if we're on a property
 237     elif isinstance(obj, property):
 238       # wrap the getters and setters
 239       if obj.fget:
 240         func = getattr(cls, obj.fget.__name__)
 241         getter = _makeExceptionHandler(func)
 242       else:
 243         getter = None
 244       if obj.fset:
 245         func = getattr(cls, obj.fset.__name__)
 246         setter = _makeExceptionHandler(func)
 247       else:
 248         setter = None
 249       setattr(cls, name, property(getter, setter))
 250
 251 def _mixClass(cls, new_cls, ignore=[]):
 252   '''
 253   Adds the methods in new_cls to cls. After mixing, all instances of cls will
 254   have the new methods. If there is a method name clash, the method already in
 255   cls will be prefixed with '_mix_' before the new method of the same name is
 256   mixed in.
 257
 258   @note: _ is not the prefix because if you wind up with __ in front of a
 259   variable, it becomes private and mangled when an instance is created.
 260   Difficult to invoke from the mixin class.
 261
 262   @param cls: Existing class to mix features into
 263   @type cls: class
 264   @param new_cls: Class containing features to add
 265   @type new_cls: class
 266   @param ignore: Ignore these methods from the mixin
 267   @type ignore: iterable
 268   '''
 269   # loop over all names in the new class
 270   for name, func in new_cls.__dict__.items():
 271     if name in ignore:
 272       continue
 273     if isinstance(func, types.FunctionType):
 274       # build a new function that is a clone of the one from new_cls
 275       method = new.function(func.func_code, func.func_globals, name,
 276                             func.func_defaults, func.func_closure)
 277       try:
 278         # check if a method of the same name already exists in the target
 279         old_method = getattr(cls, name)
 280       except AttributeError:
 281         pass
 282       else:
 283         # rename the old method so we can still call it if need be
 284         setattr(cls, '_mix_'+name, old_method)
 285       # add the clone to cls
 286       setattr(cls, name, method)
 287     elif isinstance(func, staticmethod):
 288       try:
 289         # check if a method of the same name already exists in the target
 290         old_method = getattr(cls, name)
 291       except AttributeError:
 292         pass
 293       else:
 294         # rename the old method so we can still call it if need be
 295         setattr(cls, '_mix_'+name, old_method)
 296       setattr(cls, name, func)
 297     elif isinstance(func, property):
 298       try:
 299         # check if a method of the same name already exists in the target
 300         old_prop = getattr(cls, name)
 301       except AttributeError:
 302         pass
 303       else:
 304         # IMPORTANT: We save the old property before overwriting it, even
 305         # though we never end up calling the old prop from our mixin class.
 306         # If we don't save the old one, we seem to introduce a Python ref count
 307         # problem where the property get/set methods disappear before we can
 308         # use them at a later time. This is a minor waste of memory because
 309         # a property is a class object and we only overwrite a few of them.
 310         setattr(cls, '_mix_'+name, old_prop)
 311       setattr(cls, name, func)
 312
 313 class _AccessibleMixin(object):
 314   '''
 315   Defines methods to be added to the Accessibility.Accessible class. The
 316   features defined here will be added to the Accessible class at run time so
 317   that all instances of Accessible have them (i.e. there is no need to
 318   explicitly wrap an Accessible in this class or derive a new class from it.)
 319
 320   @cvar SLOTTED_CLASSES: Mapping from raw Accessibility class to a new class
 321     having the slots defined by L{SLOTS}
 322   @type SLOTTED_CLASSES: dictionary
 323   @cvar SLOTS: All slots to create
 324   @type SLOTS: tuple
 325   '''
 326   SLOTTED_CLASSES = {}
 327   SLOTS = ('_icache',)
 328
 329   def __new__(cls):
 330     '''
 331     Creates a new class mimicking the one requested, but with an extra _cache
 332     attribute set in the __slots__ tuple. This field can be set to a dictionary
 333     or other object to allow caching to occur.
 334
 335     Note that we can't simply mix __slots__ into this class because __slots__
 336     has an effect only at class creation time.
 337
 338     @param cls: Accessibility object class
 339     @type cls: class
 340     @return: Instance of the new class
 341     @rtype: object
 342     '''
 343     try:
 344       # check if we've already created a new version of the class
 345       new_cls = _AccessibleMixin.SLOTTED_CLASSES[cls]
 346     except KeyError:
 347       # create the new class if not
 348       new_cls = type(cls.__name__, (cls,),
 349                      {'__module__' : cls.__module__,
 350                       '__slots__' : _AccessibleMixin.SLOTS})
 351       _AccessibleMixin.SLOTTED_CLASSES[cls] = new_cls
 352     obj = cls._mix___new__(new_cls)
 353     # don't create the interface cache until we need it
 354     obj._icache = None
 355     return obj
 356
 357   def __del__(self):
 358     '''
 359     Decrements the reference count on the accessible object when there are no
 360     Python references to this object. This provides automatic reference
 361     counting for AT-SPI objects. Also removes this object from the cache if
 362     we're caching properties.
 363     '''
 364     try:
 365       del _ACCESSIBLE_CACHE[hash(self)]
 366     except KeyError:
 367       pass
 368     try:
 369       self.unref()
 370     except Exception:
 371       pass
 372
 373   def __iter__(self):
 374     '''
 375     Iterator that yields one accessible child per iteration. If an exception is
 376     encountered, None is yielded instead.
 377
 378     @return: A child accessible
 379     @rtype: Accessibility.Accessible
 380     '''
 381     for i in xrange(self.childCount):
 382       try:
 383         yield self.getChildAtIndex(i)
 384       except LookupError:
 385         yield None
 386
 387   def __str__(self):
 388     '''
 389     Gets a human readable representation of the accessible.
 390
 391     @return: Role and name information for the accessible
 392     @rtype: string
 393     '''
 394     try:
 395       return '[%s | %s]' % (self.getRoleName(), self.name)
 396     except Exception:
 397       return '[DEAD]'
 398
 399   def __nonzero__(self):
 400     '''
 401     @return: True, always
 402     @rtype: boolean
 403     '''
 404     return True
 405
 406   def __getitem__(self, index):
 407     '''
 408     Thin wrapper around getChildAtIndex.
 409
 410     @param index: Index of desired child
 411     @type index: integer
 412     @return: Accessible child
 413     @rtype: Accessibility.Accessible
 414     '''
 415     n = self.childCount
 416     if index >= n:
 417       raise IndexError
 418     elif index < -n:
 419       raise IndexError
 420     elif index < 0:
 421       index += n
 422     return self.getChildAtIndex(index)
 423
 424   def __len__(self):
 425     '''
 426     Thin wrapper around childCount.
 427
 428     @return: Number of child accessibles
 429     @rtype: integer
 430     '''
 431     return self.childCount
 432
 433   def _get_name(self):
 434     '''
 435     Gets the name of the accessible from the cache if it is available,
 436     otherwise, fetches it remotely.
 437
 438     @return: Name of the accessible
 439     @rtype: string
 440     '''
 441     if _CACHE_LEVEL != constants.CACHE_PROPERTIES:
 442       return self._get_name()
 443
 444     cache = _ACCESSIBLE_CACHE
 445     h = hash(self)
 446     try:
 447       return cache[h].name
 448     except KeyError:
 449       # no cached info for this object yet
 450       name = self._get_name()
 451       pc = _PropertyCache()
 452       pc.name = name
 453       cache[h] = pc
 454       return name
 455     except AttributeError:
 456       # no cached name for this object yet
 457       name = self._get_name()
 458       cache[h].name = name
 459       return name
 460
 461   name = property(_get_name, Accessibility.Accessible._set_name)
 462
 463   def getRoleName(self):
 464     '''
 465     Gets the unlocalized role name of the accessible from the cache if it is
 466     available, otherwise, fetches it remotely.
 467
 468     @return: Role name of the accessible
 469     @rtype: string
 470     '''
 471     if _CACHE_LEVEL != constants.CACHE_PROPERTIES:
 472       return self._mix_getRoleName()
 473
 474     cache = _ACCESSIBLE_CACHE
 475     h = hash(self)
 476     try:
 477       return cache[h].rolename
 478     except KeyError, e:
 479       # no cached info for this object yet
 480       rolename = self._mix_getRoleName()
 481       pc = _PropertyCache()
 482       pc.rolename = rolename
 483       cache[h] = pc
 484       return rolename
 485     except AttributeError, e:
 486       # no cached name for this object yet
 487       rolename = self._mix_getRoleName()
 488       cache[h].rolename = rolename
 489       return rolename
 490
 491   def _get_description(self):
 492     '''
 493     Gets the description of the accessible from the cache if it is available,
 494     otherwise, fetches it remotely.
 495
 496     @return: Description of the accessible
 497     @rtype: string
 498     '''
 499     if _CACHE_LEVEL != constants.CACHE_PROPERTIES:
 500       return self._get_description()
 501
 502     cache = _ACCESSIBLE_CACHE
 503     h = hash(self)
 504     try:
 505       return cache[h].description
 506     except KeyError:
 507       # no cached info for this object yet
 508       description = self._get_description()
 509       pc = _PropertyCache()
 510       pc.description = description
 511       cache[h] = pc
 512       return description
 513     except AttributeError:
 514       # no cached name for this object yet
 515       description = self._get_description()
 516       cache[h].description = description
 517       return description
 518
 519   description = property(_get_description,
 520                          Accessibility.Accessible._set_description)
 521
 522   def getIndexInParent(self):
 523     '''
 524     Gets the index of this accessible in its parent. Uses the implementation of
 525     this method provided by the Accessibility.Accessible object, but checks the
 526     bound of the value to ensure it is not outside the range of childCount
 527     reported by this accessible's parent.
 528
 529     @return: Index of this accessible in its parent
 530     @rtype: integer
 531     '''
 532     i = self._mix_getIndexInParent()
 533     try:
 534       # correct for out-of-bounds index reporting
 535       return min(self.parent.childCount-1, i)
 536     except AttributeError:
 537       # return sentinel if there is no parent
 538       return -1
 539
 540   def getApplication(self):
 541     '''
 542     Gets the most-parent accessible (the application) of this accessible. Tries
 543     using the getApplication method introduced in AT-SPI 1.7.0 first before
 544     resorting to traversing parent links.
 545
 546     @warning: Cycles involving more than the previously traversed accessible
 547       are not detected by this code.
 548     @return: Application object
 549     @rtype: Accessibility.Application
 550     '''
 551     try:
 552       return self._mix_getApplication()
 553     except AttributeError:
 554       pass
 555     curr = self
 556     try:
 557       while curr.parent is not None and (not curr.parent == curr):
 558         curr = curr.parent
 559       return curr
 560     except Exception:
 561       pass
 562     # return None if the application isn't reachable for any reason
 563     return None
 564
 565 # 1. mix the exception handlers into all queryable interfaces
 566 map(_mixExceptions, constants.ALL_INTERFACES)
 567 # 2. mix the exception handlers into other Accessibility objects
 568 map(_mixExceptions, [Accessibility.StateSet])
 569 # 3. mix the new functions
 570 _mixClass(Accessibility.Accessible, _AccessibleMixin,
 571           ['_get_name', '_get_description'])
 572 # 4. mix queryInterface convenience methods
 573 _mixInterfaces(Accessibility.Accessible, constants.ALL_INTERFACES)