Provides a series of useful decorators for defining various types of properties.
For example usage, consider the unittests at the end of the module.
See PEP 318 and Michele Simionato’s decorator documentation for more information on decorators.
libbe.storage.util.settings_object : bundle properties into a convenient package
End a chain of property decorators, returning a property.
Allow caching of values generated by generator(instance), where instance is the instance to which this property belongs. Uses ._<name>_cache to store a cache flag for a particular owner instance.
When the cache flag is True or missing and the stored value is initVal, the first fget call triggers the generator function, 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 loaded from disk or set with fset), that value overrides any cached value, and this property has no effect.
When the cache flag is False and the stored value is initVal, the generator is not cached, but is called on every fget.
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.
Call the function hook whenever a value different from the current value is set.
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.
In the case of mutables, things are slightly trickier. Because the property-owning class has no way of knowing when the value changes. We work around this by caching a private deepcopy of the mutable value, and checking for changes whenever the property is set (obviously) or retrieved (to check for external changes). So long as you’re conscientious about accessing the property after making external modifications, mutability won’t be a problem:
t.x.append(5) # external modification
t.x # dummy access notices change and triggers hook
See testChangeHookMutableProperty for an example of the expected behavior.
| Parameters : | hook : fn
|
|---|
Define allowed values for get/set access to a property.
Define a default value for get access to a property. If the stored value is null, then default is returned.
If mutable_default == True, we only release deepcopies of the default to the outside world.
null should never escape to the outside world, so don’t worry about it being a mutable.
Add a docstring to a chain of property decorators.
Define allowed values for get/set access to a property.
Define get/set access to per-parent-instance local storage. Uses ._<name>_value to store the value for a particular owner instance. If the ._<name>_value attribute does not exist, returns null.
If mutable_null == True, we only release deepcopies of the null to the outside world.
Just like a cached_property, except that instead of returning a new value and running fset to cache it, the primer attempts some background manipulation (e.g. loads data into instance.settings) such that a _second_ pass through fget succeeds. If the second pass doesn’t succeed (e.g. no readable storage), we give up and return unprimeableVal.
The ‘cache’ flag becomes a ‘prime’ flag, with priming taking place whenever ._<name>_prime is True, or is False or missing and value == initVal.
Similar to local_property, except where local_property stores the value in instance._<name>_value, settings_property stores the value in instance.settings[name].