4.6.1. pde.tools.cache module¶
Functions, classes, and decorators for managing caches
Decorator to use a method as a cached property |
|
Decorator to enable caching of a method |
|
return hash also for (nested) mutable objects. |
|
return human readable hash also for (nested) mutable objects. |
|
returns a function that serialize data with the given method. |
|
returns a function that unserialize data with the given method |
|
cache with a limited number of items |
|
a key value database which is stored on the disk This class provides hooks for converting arbitrary keys and values to strings, which are then stored in the database. |
- class DictFiniteCapacity(*args, **kwargs)[source]¶
Bases:
OrderedDict
cache with a limited number of items
- class SerializedDict(key_serialization: str = 'pickle', value_serialization: str = 'pickle', storage_dict: Optional[Dict] = None)[source]¶
Bases:
MutableMapping
a key value database which is stored on the disk This class provides hooks for converting arbitrary keys and values to strings, which are then stored in the database.
provides a dictionary whose keys and values are serialized
- class cached_method(factory=None, extra_args=None, ignore_args=None, hash_function='hash_mutable', doc=None, name=None)[source]¶
Bases:
_class_cache
Decorator to enable caching of a method
The function is only called the first time and each successive call returns the cached result of the first call.
Example
The decorator can be used like so:
class Foo: @cached_method def bar(self): return "Cached" foo = Foo() result = foo.bar()
The data is stored in a dictionary named _cache_methods attached to the instance of each object. The cache can thus be cleared by setting self._cache_methods = {}. The cache of specific property can be cleared using self._cache_methods[property_name] = {}, where property_name is the name of the property
decorator that caches calls in a dictionary attached to the instances. This can be used with most classes
Example
An example for using the class is:
class Foo(): @cached_property() def property(self): return "Cached property" @cached_method() def method(self): return "Cached method" foo = Foo() foo.property foo.method()
The cache can be cleared by setting foo._cache_methods = {} if the cache factory is a simple dict, i.e, if factory == None. Alternatively, each cached method has a
clear_cache_of_obj()
method, which clears the cache of this particular method. In the example above we could thus call foo.bar.clear_cache_of_obj(foo) to clear the cache. Note that the object instance has to be passed as a parameter, since the methodbar()
is defined on the class, not the instance, i.e., we could also call Foo.bar.clear_cache_of_obj(foo). To clear the cache from within a method, one can thus call self.method_name.clear_cache_of_obj(self), where method_name is the name of the method whose cache is clearedExample
An advanced example is:
class Foo(): def get_cache(self, name): # `name` is the name of the method to cache return DictFiniteCapacity() @cached_method(factory='get_cache') def foo(self): return "Cached"
- Parameters
factory (callable) – Function/class creating an empty cache. dict by default. This can be used with user-supplied storage backends by. The cache factory should return a dict-like object that handles the cache for the given method.
extra_args (list) – List of attributes of the class that are included in the cache key. They are then treated as if they are supplied as arguments to the method. This is important to include when the result of a method depends not only on method arguments but also on instance attributes.
ignore_args (list) – List of keyword arguments that are not included in the cache key. These should be arguments that do not influence the result of a method, e.g., because they only affect how intermediate results are displayed.
hash_function (str) – An identifier determining what hash function is used on the argument list.
doc (str) – Optional string giving the docstring of the decorated method
name (str) – Optional string giving the name of the decorated method
- class cached_property(factory=None, extra_args=None, ignore_args=None, hash_function='hash_mutable', doc=None, name=None)[source]¶
Bases:
_class_cache
Decorator to use a method as a cached property
The function is only called the first time and each successive call returns the cached result of the first call.
Example
Here is an example for how to use the decorator:
class Foo(): @cached_property def bar(self): return "Cached" foo = Foo() result = foo.bar
The data is stored in a dictionary named _cache_methods attached to the instance of each object. The cache can thus be cleared by setting self._cache_methods = {}. The cache of specific property can be cleared using self._cache_methods[property_name] = {}, where property_name is the name of the property
Adapted from <https://wiki.python.org/moin/PythonDecoratorLibrary>.
decorator that caches calls in a dictionary attached to the instances. This can be used with most classes
Example
An example for using the class is:
class Foo(): @cached_property() def property(self): return "Cached property" @cached_method() def method(self): return "Cached method" foo = Foo() foo.property foo.method()
The cache can be cleared by setting foo._cache_methods = {} if the cache factory is a simple dict, i.e, if factory == None. Alternatively, each cached method has a
clear_cache_of_obj()
method, which clears the cache of this particular method. In the example above we could thus call foo.bar.clear_cache_of_obj(foo) to clear the cache. Note that the object instance has to be passed as a parameter, since the methodbar()
is defined on the class, not the instance, i.e., we could also call Foo.bar.clear_cache_of_obj(foo). To clear the cache from within a method, one can thus call self.method_name.clear_cache_of_obj(self), where method_name is the name of the method whose cache is clearedExample
An advanced example is:
class Foo(): def get_cache(self, name): # `name` is the name of the method to cache return DictFiniteCapacity() @cached_method(factory='get_cache') def foo(self): return "Cached"
- Parameters
factory (callable) – Function/class creating an empty cache. dict by default. This can be used with user-supplied storage backends by. The cache factory should return a dict-like object that handles the cache for the given method.
extra_args (list) – List of attributes of the class that are included in the cache key. They are then treated as if they are supplied as arguments to the method. This is important to include when the result of a method depends not only on method arguments but also on instance attributes.
ignore_args (list) – List of keyword arguments that are not included in the cache key. These should be arguments that do not influence the result of a method, e.g., because they only affect how intermediate results are displayed.
hash_function (str) – An identifier determining what hash function is used on the argument list.
doc (str) – Optional string giving the docstring of the decorated method
name (str) – Optional string giving the name of the decorated method
- hash_mutable(obj) int [source]¶
return hash also for (nested) mutable objects.
Notes
This function might be a bit slow, since it iterates over all containers and hashes objects recursively. Moreover, the returned value might change with each run of the python interpreter, since the hash values of some basic objects, like None, change with each instance of the interpreter.
- Parameters
obj – A general python object
- Returns
A hash value associated with the data of obj
- Return type
- hash_readable(obj) str [source]¶
return human readable hash also for (nested) mutable objects.
This function returns a JSON-like representation of the object. The function might be a bit slow, since it iterates over all containers and hashes objects recursively. Note that this hash function tries to return the same value for equivalent objects, but it does not ensure that the objects can be reconstructed from this data.
- Parameters
obj – A general python object
- Returns
A hash value associated with the data of obj
- Return type
- make_serializer(method: str) Callable [source]¶
returns a function that serialize data with the given method. Note that some of the methods destroy information and cannot be reverted.
- Parameters
method (str) – An identifier determining the serializer that will be returned
- Returns
A function that serializes objects
- Return type
callable
- make_unserializer(method: str) Callable [source]¶
returns a function that unserialize data with the given method
This is the inverse function of
make_serializer()
.- Parameters
method (str) – An identifier determining the unserializer that will be returned
- Returns
A function that serializes objects
- Return type
callable
- objects_equal(a, b) bool [source]¶
compares two objects to see whether they are equal
In particular, this uses
numpy.array_equal()
to check for numpy arrays- Parameters
a – The first object
b – The second object
- Returns
Whether the two objects are considered equal
- Return type