Merge with W. Trevor King's tree.

1 files changed, 154 insertions, 19 deletions

diff --git a/libbe/properties.py b/libbe/properties.py
index a8e89fb..956ecc3 100644
--- a/libbe/properties.py
+++ b/libbe/properties.py
@@ -26,12 +26,17 @@ and
 for more information on decorators.
 """
 
+import copy
+import types
 import unittest
 
 
 class ValueCheckError (ValueError):
     def __init__(self, name, value, allowed):
-        msg = "%s not in %s for %s" % (value, allowed, name)
+        action = "in" # some list of allowed values
+        if type(allowed) == types.FunctionType:
+            action = "allowed by" # some allowed-value check function
+        msg = "%s not %s %s for %s" % (value, action, allowed, name)
         ValueError.__init__(self, msg)
         self.name = name
         self.value = value
@@ -66,7 +71,7 @@ def doc_property(doc=None):
         return funcs
     return decorator
 
-def local_property(name, null=None):
+def local_property(name, null=None, mutable_null=False):
     """
     Define get/set access to per-parent-instance local storage.  Uses
     ._<name>_value to store the value for a particular owner instance.
@@ -80,7 +85,11 @@ def local_property(name, null=None):
         def _fget(self):
             if fget is not None:
                 fget(self)
-            value = getattr(self, "_%s_value" % name, null)
+            if mutable_null == True:
+                ret_null = copy.deepcopy(null)
+            else:
+                ret_null = null
+            value = getattr(self, "_%s_value" % name, ret_null)
             return value
         def _fset(self, value):
             setattr(self, "_%s_value" % name, value)
@@ -118,7 +127,46 @@ def settings_property(name, null=None):
         return funcs
     return decorator
 
-def defaulting_property(default=None, null=None):
+
+# Allow comparison and caching with _original_ values for mutables,
+# since
+#
+# >>> a = []
+# >>> b = a
+# >>> b.append(1)
+# >>> a
+# [1]
+# >>> a==b
+# True
+def _hash_mutable_value(value):
+    return repr(value)
+def _init_mutable_property_cache(self):
+    if not hasattr(self, "_mutable_property_cache_hash"):
+        # first call to _fget for any mutable property
+        self._mutable_property_cache_hash = {}
+        self._mutable_property_cache_copy = {}
+def _set_cached_mutable_property(self, cacher_name, property_name, value):
+    _init_mutable_property_cache(self)
+    self._mutable_property_cache_hash[(cacher_name, property_name)] = \
+        _hash_mutable_value(value)
+    self._mutable_property_cache_copy[(cacher_name, property_name)] = \
+        copy.deepcopy(value)
+def _get_cached_mutable_property(self, cacher_name, property_name, default=None):
+    _init_mutable_property_cache(self)
+    if (cacher_name, property_name) not in self._mutable_property_cache_copy:
+        return default
+    return self._mutable_property_cache_copy[(cacher_name, property_name)]
+def _cmp_cached_mutable_property(self, cacher_name, property_name, value):
+    _init_mutable_property_cache(self)
+    if (cacher_name, property_name) not in self._mutable_property_cache_hash:
+        return 1 # any value > non-existant old hash
+    old_hash = self._mutable_property_cache_hash[(cacher_name, property_name)]
+    return cmp(_hash_mutable_value(value), old_hash)
+
+
+def defaulting_property(default=None, null=None,
+                        default_mutable=False,
+                        null_mutable=False):
     """
     Define a default value for get access to a property.
     If the stored value is null, then default is returned.
@@ -127,12 +175,25 @@ def defaulting_property(default=None, null=None):
         if hasattr(funcs, "__call__"):
             funcs = funcs()
         fget = funcs.get("fget")
+        fset = funcs.get("fset")
+        name = funcs.get("name", "<unknown>")
         def _fget(self):
             value = fget(self)
             if value == null:
-                return default
+                if default_mutable == True:
+                    return copy.deepcopy(default)
+                else:
+                    return default
             return value
+        def _fset(self, value):
+            if value == default:
+                if null_mutable == True:
+                    value = copy.deepcopy(null)
+                else:
+                    value = null
+            fset(self, value)
         funcs["fget"] = _fget
+        funcs["fset"] = _fset
         return funcs
     return decorator
 
@@ -184,7 +245,7 @@ def checked_property(allowed=[]):
         return funcs
     return decorator
 
-def cached_property(generator, initVal=None):
+def cached_property(generator, initVal=None, mutable=False):
     """
     Allow caching of values generated by generator(instance), where
     instance is the instance to which this property belongs.  Uses
@@ -193,7 +254,7 @@ def cached_property(generator, initVal=None):
 
     When the cache flag is True or missing and the stored value is
     initVal, the first fget call triggers the generator function,
-    whiose output is stored in _<name>_cached_value.  That and
+    whose output is stored in _<name>_cached_value.  That and
     subsequent calls to fget will return this cached value.
 
     If the input value is no longer initVal (e.g. a value has been
@@ -205,25 +266,27 @@ def cached_property(generator, initVal=None):
 
     The cache flag is missing on initialization.  Particular instances
     may override by setting their own flag.
+
+    In the case that mutable == True, all caching is disabled and the
+    generator is called whenever the cached value would otherwise be
+    used.  This avoids uncertainties in the value of stored mutables.
     """
     def decorator(funcs):
         if hasattr(funcs, "__call__"):
             funcs = funcs()
         fget = funcs.get("fget")
-        fset = funcs.get("fset")
         name = funcs.get("name", "<unknown>")
         def _fget(self):
             cache = getattr(self, "_%s_cache" % name, True)
             value = fget(self)
-            if cache == True:
-                if value == initVal:
+            if value == initVal:
+                if cache == True and mutable == False:
                     if hasattr(self, "_%s_cached_value" % name):
                         value = getattr(self, "_%s_cached_value" % name)
                     else:
                         value = generator(self)
                         setattr(self, "_%s_cached_value" % name, value)
-            else:
-                if value == initVal:
+                else:
                     value = generator(self)
             return value
         funcs["fget"] = _fget
@@ -258,12 +321,15 @@ def primed_property(primer, initVal=None):
         return funcs
     return decorator
 
-def change_hook_property(hook):
+def change_hook_property(hook, mutable=False):
     """
     Call the function hook(instance, old_value, new_value) whenever a
     value different from the current value is set (instance is a a
     reference to the class instance to which this property belongs).
-    This is useful for saving changes to disk, etc.
+    This is useful for saving changes to disk, etc.  This function is
+    called _after_ the new value has been stored, allowing you to
+    change the stored value if you want.
+
     """
     def decorator(funcs):
         if hasattr(funcs, "__call__"):
@@ -271,15 +337,31 @@ def change_hook_property(hook):
         fget = funcs.get("fget")
         fset = funcs.get("fset")
         name = funcs.get("name", "<unknown>")
+        def _fget(self, new_value=None, from_fset=False): # only used if mutable == True
+            value = fget(self)
+            if _cmp_cached_mutable_property(self, "change hook property", name, value) != 0:
+                # there has been a change, cache new value
+                old_value = _get_cached_mutable_property(self, "change hook property", name)
+                _set_cached_mutable_property(self, "change hook property", name, value)
+                if from_fset == True: # return previously cached value
+                    value = old_value
+                else: # the value changed while we weren't looking
+                    hook(self, old_value, value)
+            return value
         def _fset(self, value):
-            old_value = fget(self)
+            if mutable == True: # get cached previous value
+                old_value = _fget(self, new_value=value, from_fset=True)
+            else:
+                old_value = fget(self)
+            fset(self, value)
             if value != old_value:
                 hook(self, old_value, value)
-            fset(self, value)
+        if mutable == True:
+            funcs["fget"] = _fget
         funcs["fset"] = _fset
         return funcs
     return decorator
-
+        
 
 class DecoratorTests(unittest.TestCase):
     def testLocalDoc(self):
@@ -320,16 +402,18 @@ class DecoratorTests(unittest.TestCase):
         class Test(object):
             @Property
             @defaulting_property(default='y', null='x')
-            @local_property(name="DEFAULT")
+            @local_property(name="DEFAULT", null=5)
             def x(): return {}
         t = Test()
-        self.failUnless(t.x == None, str(t.x)) 
+        self.failUnless(t.x == 5, str(t.x)) 
         t.x = 'x'
         self.failUnless(t.x == 'y', str(t.x))
         t.x = 'y'
         self.failUnless(t.x == 'y', str(t.x))
         t.x = 'z'
         self.failUnless(t.x == 'z', str(t.x))
+        t.x = 5
+        self.failUnless(t.x == 5, str(t.x))
     def testCheckedLocalProperty(self):
         class Test(object):
             @Property
@@ -474,6 +558,57 @@ class DecoratorTests(unittest.TestCase):
         t.x = 2
         self.failUnless(t.old == 1, t.old)
         self.failUnless(t.new == 2, t.new)
+    def testChangeHookMutableProperty(self):
+        class Test(object):
+            def _hook(self, old, new):
+                self.old = old
+                self.new = new
+                self.hook_calls += 1
+
+            @Property
+            @change_hook_property(_hook, mutable=True)
+            @local_property(name="HOOKED")
+            def x(): return {}
+        t = Test()
+        t.hook_calls = 0
+        t.x = []
+        self.failUnless(t.old == None, t.old)
+        self.failUnless(t.new == [], t.new)
+        a = t.x
+        a.append(5)
+        t.x = a
+        self.failUnless(t.old == [], t.old)
+        self.failUnless(t.new == [5], t.new)
+        t.x = []
+        self.failUnless(t.old == [5], t.old)
+        self.failUnless(t.new == [], t.new)
+        # now append without reassigning.  this doesn't trigger the
+        # change, since we don't ever set t.x, only get it and mess
+        # with it.  It does, however, update our t.new, since t.new =
+        # t.x and is not a static copy.
+        t.x.append(5)
+        self.failUnless(t.old == [5], t.old)
+        self.failUnless(t.new == [5], t.new)
+        # however, the next t.x get _will_ notice the change...
+        a = t.x
+        self.failUnless(t.old == [], t.old)
+        self.failUnless(t.new == [5], t.new)
+        self.failUnless(t.hook_calls == 6, t.hook_calls)
+        t.x.append(6) # this append(6) is not noticed yet
+        self.failUnless(t.old == [], t.old)
+        self.failUnless(t.new == [5,6], t.new)
+        self.failUnless(t.hook_calls == 6, t.hook_calls)
+        # this append(7) is not noticed, but the t.x get causes the
+        # append(6) to be noticed
+        t.x.append(7)
+        self.failUnless(t.old == [5], t.old)
+        self.failUnless(t.new == [5,6,7], t.new)
+        self.failUnless(t.hook_calls == 7, t.hook_calls)
+        a = t.x # now the append(7) is noticed
+        self.failUnless(t.old == [5,6], t.old)
+        self.failUnless(t.new == [5,6,7], t.new)
+        self.failUnless(t.hook_calls == 8, t.hook_calls)
+
 
 suite = unittest.TestLoader().loadTestsFromTestCase(DecoratorTests)