Data cache

list_attributes(key)

List all Higra attributes of the object key.

get_attribute(key, attribute_name)

Get the Higra attributes named attribute_name of the object key.

set_attribute(key, attribute_name, attribute)

Set the Higra attributes named attribute_name of the object key to the value attribute.

auto_cache(fun)

Function decorator that provides automatic caching of function results.

set_auto_cache_state(boolean)

Globally activates or deactivates the caching of auto_cache() decorated functions.

get_auto_cache_state()

Returns the current state of the caching policy for of auto_cache() decorated functions.

clear_auto_cache(*[, function, …])

Cleanup the result cache for the specified elements

list_attributes(key)[source]

List all Higra attributes of the object key.

See functions get_attribute() and set_attribute().

Parameters

key – an object

Returns

a list of strings

get_attribute(key, attribute_name)[source]

Get the Higra attributes named attribute_name of the object key.

See functions list_attributes() and set_attribute().

Parameters
  • key – an object

  • attribute_name – a string

Returns

the attribute value associated to the given name (None if no such attribute exists)

set_attribute(key, attribute_name, attribute, insert_dynamic=True)[source]

Set the Higra attributes named attribute_name of the object key to the value attribute.

See functions list_attributes() and get_attribute().

Parameters
  • key – an object

  • attribute_name – a string

  • attribute – a value

  • insert_dynamic – if True and if key supports dynamic attributes, a new object attribute with the given name and values will be added to the given object

Returns

None

@auto_cache[source]

Function decorator that provides automatic caching of function results.

The basic idea is that two successive calls with the same arguments to an auto_cache decorated function will indeed produce a single function call. The second time, the result of the first call will be returned.

Auto cache is useful for expensive functions that might be called in unrelated locations (where manual reuse of function result would be difficult).

Auto cache can only decorates functions with only positional and named arguments. The first argument of the function must support weak references.

Special parameters

All functions decorated by auto-cache support the following named arguments:

  • no_cache (boolean value). If True, auto caching is disabled for this function call: no cached data will be used or stored.

  • force_recompute (boolean value). If True, no cache result will be used for this function call but the result of the function call will be cached for future use.

Caveats

A function call is identified by a hash of its arguments. This hash is computed in such a way that non hashable objects (except from dictionaries) are indeed identified by their unique object identifier. This means that calling the same auto-cached function with the same mutated arguments can potentially lead to unexpected results.

>>> @hg.auto_cache
>>> def cached_sum(a):
>>>     return sum(a)
>>>
>>> a = numpy.zeros(10)
>>> cached_sum(a)
0
>>> a[0] = 1 # mutate a
>>> cached_sum(a) # auto cache cannot detect mutation of a and returns the cached result
0

This problem can be solved by using no_cache, force_recompute (see above) or by globally disabling function caching (see set_auto_cache_state()).

>>> cached_sum(a, no_cache=True) # or force_recompute=True
1

If you are really unlucky, it might also appends that two unrelated set of arguments get the same hash. In such case the auto cache decorator will consider that they are the same. This is however extremely unlikely to happen.

Life Time

The data stored in the cache are associated to the first argument of the function called the reference object. All data related to a reference object is cleared when it gets garbage collected.

The cache data associated to a particular function or object can be manually cleared with clear_auto_cache().

Global setting

Auto caching can be globally disabled, see:

Returns

set_auto_cache_state(boolean)[source]

Globally activates or deactivates the caching of auto_cache() decorated functions.

If set to True (default), an auto cached function will save its results in the object cache of its first argument. Any other call to this function with the same arguments will return the result stored in the cache instead of recomputing a new result (except if this behaviour is locally overridden with the name arguments “force_recompute=True” or “no_cache=True”).

If set to False, auto-cached functions will behave as normal function: they won’t try to cache results.

See

get_auto_cache_state(): get current state of the automatic caching.

Parameters

booleanTrue to globally activate caching, False to deactivate it

Returns

nothing

get_auto_cache_state()[source]

Returns the current state of the caching policy for of auto_cache() decorated functions.

See

set_auto_cache_state(): modify the state of the automatic caching.

Returns

True if auto-caching is globally active, False otherwise

clear_auto_cache(*, function=None, reference_object=None, data_cache=None)[source]

Cleanup the result cache for the specified elements

Parameters
  • function – function or name of a auto_cache() decorated function to clear (if None all functions are cleared)

  • reference_object – reference object whose cached data have to be cleared (if None cache data of all objects are cleared)

  • data_cache – data cache to work on (will default to the global Higra cache)

Returns

nothing