4.6.1 pde.tools.cache module

Functions, classes, and decorators for managing caches.

cached_property

Decorator to use a method as a cached property.

cached_method

Decorator to enable caching of a method.

hash_mutable

Return hash also for (nested) mutable objects.

hash_readable

Return human readable hash also for (nested) mutable objects.

make_serializer

Returns a function that serialize data with the given method.

make_unserializer

Returns a function that unserialize data with the given method.

DictFiniteCapacity

Cache with a limited number of items.

SerializedDict

A key value database which is stored on the disk.

class DictFiniteCapacity(*args, **kwargs)[source]

Bases: OrderedDict

Cache with a limited number of items.

check_length()[source]

Ensures that the dictionary does not grow beyond its capacity.

default_capacity: int = 100
update([E, ]**F) None.  Update D from dict/iterable E and F.[source]

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

class SerializedDict(key_serialization='pickle', value_serialization='pickle', storage_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.

Parameters:
  • key_serialization (str) – Determines the serialization method for keys

  • value_serialization (str) – Determines the serialization method for values

  • storage_dict (dict) – Can be used to chose a different dictionary for the underlying storage mechanism, e.g., storage_dict = PersistentDict()

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 method bar() 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 cleared

Example

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 arguments

  • 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 method bar() 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 cleared

Example

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 arguments

  • 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)[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:

int

hash_readable(obj)[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:

str

make_serializer(method)[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)[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)[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:

bool