dol.cache_keys

Key strategies: how cache_this turns an instance and a call into a cache key.

A key strategy (the KeyStrategy protocol) resolves a key from the method name when the class is defined (resolve_at_definition) or, if it needs the instance, when the cached attribute is accessed (resolve_at_runtime). The ready-made ones:

• ExplicitKey: a fixed key

• ApplyToMethodName: a function of the method name (e.g. add an extension)

• InstanceProp: the value of an attribute of the instance

• ApplyToInstance: a function of the instance

• FromMethodArgs: a function of the method’s arguments

• CompositeKey: several strategies combined

cache_this accepts a strategy, or anything _resolve_key_for_cached_prop / _resolve_key_for_cached_method can turn into one (a string, a callable, …). The strategies are also attributes of cache_this (cache_this.ExplicitKey).

These used to live in dol.caching, which still re-exports them (i2mint/dol#70).

>>> from dol.cache_keys import ExplicitKey, ApplyToMethodName
>>> ExplicitKey('data.json').resolve_at_definition('load')
'data.json'
>>> ApplyToMethodName(lambda name: name + '.pkl').resolve_at_definition('load')
'load.pkl'

Functions

register_key_strategy(cls)

Register a class as a KeyStrategy.

Classes

ApplyToInstance(func)	Apply a function to the instance to generate the key.
ApplyToMethodName(func)	Apply a function to the method name to generate the key.
CompositeKey(*strategies[, separator])	Combine multiple key strategies into a single composite key.
ExplicitKey(key)	Use an explicitly provided key value.
FromMethodArgs(func)	Apply a function to method arguments to generate the key.
InstanceProp(prop_name)	Get a key from an instance property.
KeyStrategy(*args, **kwargs)	Protocol defining how a key strategy should behave.

class dol.cache_keys.ApplyToInstance(func)

Bases: object

Apply a function to the instance to generate the key.

resolve_at_definition(method_name)

Cannot resolve at definition time, need the instance.

Return type:

None

resolve_at_runtime(instance, method_name)

Apply the function to the instance at runtime.

Return type:

Any

class dol.cache_keys.ApplyToMethodName(func)

Bases: object

Apply a function to the method name to generate the key.

>>> strategy = ApplyToMethodName(lambda name: f"{name}.cache")
>>> strategy.resolve_at_definition("my_method")
'my_method.cache'

resolve_at_definition(method_name)

Apply the function to the method name at definition time.

Return type:

Any

class dol.cache_keys.CompositeKey(*strategies, separator='_')

Bases: object

Combine multiple key strategies into a single composite key.

Useful for creating keys that depend on both instance properties and method arguments.

resolve_at_definition(method_name)

Try to resolve all strategies at definition time.

Return type:

Any | None

resolve_at_runtime(instance, method_name, *args, **kwargs)

Resolve all strategies at runtime and combine them.

Return type:

Any

class dol.cache_keys.ExplicitKey(key)

Bases: object

Use an explicitly provided key value.

>>> strategy = ExplicitKey("my_key")
>>> strategy.resolve_at_definition("method_name")
'my_key'

resolve_at_definition(method_name)

Return the explicit key value at definition time.

Return type:

Any

class dol.cache_keys.FromMethodArgs(func)

Bases: object

Apply a function to method arguments to generate the key.

The function receives (self, *args, **kwargs) and should return a cache key.

resolve_at_definition(method_name)

Cannot resolve at definition time, need the arguments.

Return type:

None

resolve_at_runtime(instance, method_name, *args, **kwargs)

Apply the function to the instance and method arguments at runtime.

Return type:

Any

class dol.cache_keys.InstanceProp(prop_name)

Bases: object

Get a key from an instance property.

resolve_at_definition(method_name)

Cannot resolve at definition time, need the instance.

Return type:

None

resolve_at_runtime(instance, method_name)

Get the property value from the instance at runtime.

Return type:

Any

class dol.cache_keys.KeyStrategy(*args, **kwargs)

Bases: Protocol

Protocol defining how a key strategy should behave.

resolve_at_definition(method_name)

Attempt to resolve the key at class definition time.

Parameters:

method_name (str) – The name of the method being decorated.

Return type:

Any | None

Returns:

The resolved key or None if it can’t be resolved at definition time.

resolve_at_runtime(instance, method_name)

Resolve the key at runtime. By default, this will call resolve_at_definition on method_name.

Parameters:

• instance (Any) – The instance the property is being accessed on.

• method_name (str) – The name of the method being decorated.

Return type:

Any

Returns:

The resolved key.

dol.cache_keys.register_key_strategy(cls)

Register a class as a KeyStrategy.