Source Code for Module baseObject

  1  #baseObject.py 
  2  #A part of NonVisual Desktop Access (NVDA) 
  3  #Copyright (C) 2006-2007 NVDA Contributors <http://www.nvda-project.org/> 
  4  #This file is covered by the GNU General Public License. 
  5  #See the file COPYING for more details. 
  6   
  7  """Contains the base classes that many of NVDA's classes such as NVDAObjects, virtualBuffers, appModules, synthDrivers inherit from. These base classes provide such things as auto properties, and methods and properties for scripting and key binding. 
  8  """ 
  9   
 10  import weakref 
 11  from logHandler import log 
 12   
 13 -class Getter(object): 
 14   
 15 -        def __init__(self,fget): 
 16                  self.fget=fget 
 17   
 18 -        def __get__(self,instance,owner): 
 19                  if not instance: 
 20                          return self 
 21                  return self.fget(instance) 
 22   
 23 -        def setter(self,func): 
 24                  return property(fget=self._func,fset=func) 
 25   
 26 -        def deleter(self,func): 
 27                  return property(fget=self._func,fdel=func) 
 28   
 29 -class CachingGetter(Getter): 
 30   
 31 -        def __get__(self, instance, owner): 
 32                  if not instance: 
 33                          return self 
 34                  return instance._getPropertyViaCache(self.fget) 
 35   
 36 -class AutoPropertyType(type): 
 37   
 38 -        def __init__(self,name,bases,dict): 
 39                  super(AutoPropertyType,self).__init__(name,bases,dict) 
 40   
 41                  cacheByDefault=False 
 42                  try: 
 43                          cacheByDefault=dict["cachePropertiesByDefault"] 
 44                  except KeyError: 
 45                          cacheByDefault=any(getattr(base, "cachePropertiesByDefault", False) for base in bases) 
 46   
 47                  props=(x[5:] for x in dict.keys() if x[0:5] in ('_get_','_set_','_del_')) 
 48                  for x in props: 
 49                          g=dict.get('_get_%s'%x,None) 
 50                          s=dict.get('_set_%s'%x,None) 
 51                          d=dict.get('_del_%s'%x,None) 
 52                          if x in dict: 
 53                                  methodsString=",".join([str(i) for i in g,s,d if i]) 
 54                                  raise TypeError("%s is already a class attribute, cannot create descriptor with methods %s"%(x,methodsString)) 
 55                          if not g: 
 56                                  # There's a setter or deleter, but no getter. 
 57                                  # This means it could be in one of the base classes. 
 58                                  for base in bases: 
 59                                          g = getattr(base,'_get_%s'%x,None) 
 60                                          if g: 
 61                                                  break 
 62   
 63                          cache=dict.get('_cache_%s'%x,None) 
 64                          if cache is None: 
 65                                  # The cache setting hasn't been specified in this class, but it could be in one of the bases. 
 66                                  for base in bases: 
 67                                          cache = getattr(base,'_cache_%s'%x,None) 
 68                                          if cache is not None: 
 69                                                  break 
 70                                  else: 
 71                                          cache=cacheByDefault 
 72   
 73                          if g and not s and not d: 
 74                                  setattr(self,x,(CachingGetter if cache else Getter)(g)) 
 75                          else: 
 76                                  setattr(self,x,property(fget=g,fset=s,fdel=d)) 
 77   
 78 -class AutoPropertyObject(object): 
 79          """A class that dynamicly supports properties, by looking up _get_* and _set_* methods at runtime. 
 80          _get_x will make property x with a getter (you can get its value). 
 81          _set_x will make a property x with a setter (you can set its value). 
 82          If there is a _get_x but no _set_x then setting x will override the property completely. 
 83          Properties can also be cached for the duration of one core pump cycle. 
 84          This is useful if the same property is likely to be fetched multiple times in one cycle. For example, several NVDAObject properties are fetched by both braille and speech. 
 85          Setting _cache_x to C{True} specifies that x should be cached. Setting it to C{False} specifies that it should not be cached. 
 86          If _cache_x is not set, L{cachePropertiesByDefault} is used. 
 87          """ 
 88          __metaclass__=AutoPropertyType 
 89   
 90          #: Tracks the instances of this class; used by L{invalidateCaches}. 
 91          #: @type: weakref.WeakKeyDictionary 
 92          __instances=weakref.WeakKeyDictionary() 
 93          #: Specifies whether properties are cached by default; 
 94          #: can be overridden for individual properties by setting _cache_propertyName. 
 95          #: @type: bool 
 96          cachePropertiesByDefault = False 
 97   
 98 -        def __init__(self): 
 99                  #: Maps properties to cached values. 
100                  #: @type: dict 
101                  self._propertyCache={} 
102                  self.__instances[self]=None 
103   
104 -        def _getPropertyViaCache(self,getterMethod=None): 
105                  if not getterMethod: 
106                          raise ValueError("getterMethod is None") 
107                  try: 
108                          val=self._propertyCache[getterMethod] 
109                  except KeyError: 
110                          val=getterMethod(self) 
111                          self._propertyCache[getterMethod]=val 
112                  return val 
113   
114 -        def invalidateCache(self): 
115                  self._propertyCache.clear() 
116   
117          @classmethod 
118 -        def invalidateCaches(cls): 
119                  """Invalidate the caches for all current instances. 
120                  """ 
121                  # We use keys() here instead of iterkeys(), as invalidating the cache on an object may cause instances to disappear, 
122                  # which would in turn cause an exception due to the dictionary changing size during iteration. 
123                  for instance in cls.__instances.keys(): 
124                          instance.invalidateCache() 
125   
126 -class ScriptableObject(AutoPropertyObject): 
127          """A class that implements NVDA's scripting interface. 
128          Input gestures are bound to scripts such that the script will be executed when the appropriate input gesture is received. 
129          Scripts are methods named with a prefix of C{script_}; e.g. C{script_foo}. 
130          They accept an L{inputCore.InputGesture} as their single argument. 
131          Gesture bindings can be specified on the class by creating a C{__gestures} dict which maps gesture identifiers to script names. 
132          They can also be bound on an instance using the L{bindGesture} method. 
133          """ 
134   
135 -        def __init__(self): 
136                  #: Maps input gestures to script functions. 
137                  #: @type: dict 
138                  self._gestureMap = {} 
139                  # Bind gestures specified on the class. 
140                  for cls in self.__class__.__mro__: 
141                          try: 
142                                  self.bindGestures(getattr(cls, "_%s__gestures" % cls.__name__)) 
143                          except AttributeError: 
144                                  pass 
145                  super(ScriptableObject, self).__init__() 
146   
147 -        def bindGesture(self, gestureIdentifier, scriptName): 
148                  """Bind an input gesture to a script. 
149                  @param gestureIdentifier: The identifier of the input gesture. 
150                  @type gestureIdentifier: str 
151                  @param scriptName: The name of the script, which is the name of the method excluding the C{script_} prefix. 
152                  @type scriptName: str 
153                  @raise LookupError: If there is no script with the provided name. 
154                  """ 
155                  # Don't store the instance method, as this causes a circular reference 
156                  # and instance methods are meant to be generated on retrieval anyway. 
157                  func = getattr(self.__class__, "script_%s" % scriptName, None) 
158                  if not func: 
159                          raise LookupError("No such script: %s" % func) 
160                  # Import late to avoid circular import. 
161                  import inputCore 
162                  self._gestureMap[inputCore.normalizeGestureIdentifier(gestureIdentifier)] = func 
163   
164 -        def clearGestureBindings(self): 
165                  """Remove all input gesture bindings from this object. 
166                  """ 
167                  self._gestureMap.clear() 
168   
169 -        def bindGestures(self, gestureMap): 
170                  """Bind multiple input gestures to scripts. 
171                  This is a convenience method which simply calls L{bindGesture} for each gesture and script pair, logging any errors. 
172                  @param gestureMap: A mapping of gesture identifiers to script names. 
173                  @type gestureMap: dict of str to str 
174                  """ 
175                  for gestureIdentifier, scriptName in gestureMap.iteritems(): 
176                          try: 
177                                  self.bindGesture(gestureIdentifier, scriptName) 
178                          except LookupError: 
179                                  log.error("Error binding script %s in %r" % (scriptName, self)) 
180   
181 -        def getScript(self,gesture): 
182                  """Retrieve the script bound to a given gesture. 
183                  @param gesture: The input gesture in question. 
184                  @type gesture: L{inputCore.InputGesture} 
185                  @return: The script function or C{None} if none was found. 
186                  @rtype: script function 
187                  """  
188                  for identifier in gesture.identifiers: 
189                          try: 
190                                  # Convert to instance method. 
191                                  return self._gestureMap[identifier].__get__(self, self.__class__) 
192                          except KeyError: 
193                                  continue 
194                  else: 
195                          return None 
196