oslo_cache package¶
Subpackages¶
Submodules¶
oslo_cache.core module¶
Caching Layer Implementation.
To use this library:
You must call configure()
.
Inside your application code, decorate the methods that you want the results
to be cached with a memoization decorator created with
get_memoization_decorator()
. This function takes a group name from the
config. Register [group] caching
and [group] cache_time
options
for the groups that your decorators use so that caching can be configured.
This library’s configuration options must be registered in your application’s
oslo_config.cfg.ConfigOpts
instance. Do this by passing the ConfigOpts
instance to configure()
.
The library has special public value for nonexistent or expired keys called
NO_VALUE
. To use this value you should import it from oslo_cache.core:
from oslo_cache import core
NO_VALUE = core.NO_VALUE
-
oslo_cache.core.
NO_VALUE
= <dogpile.cache.api.NoValue object>¶ Value returned for nonexistent or expired keys.
-
oslo_cache.core.
configure
(conf)¶ Configure the library.
Register the required oslo.cache config options into an oslo.config CONF object.
This must be called before
configure_cache_region()
.- Parameters
conf (oslo_config.cfg.ConfigOpts) – The configuration object.
-
oslo_cache.core.
configure_cache_region
(conf, region)¶ Configure a cache region.
If the cache region is already configured, this function does nothing. Otherwise, the region is configured.
- Parameters
conf (oslo_config.cfg.ConfigOpts) – config object, must have had
configure()
called on it.region (dogpile.cache.region.CacheRegion) – Cache region to configure (see
create_region()
).
- Raises
oslo_cache.exception.ConfigurationError – If the region parameter is not a dogpile.cache.CacheRegion.
- Returns
The region.
- Return type
dogpile.cache.region.CacheRegion
-
oslo_cache.core.
create_region
(function=<function function_key_generator>)¶ Create a region.
This is just dogpile.cache.make_region, but the key generator has a different to_str mechanism.
Note
You must call
configure_cache_region()
with this region before a memoized method is called.- Parameters
function (function) – function used to generate a unique key depending on the arguments of the decorated function
- Returns
The new region.
- Return type
dogpile.cache.region.CacheRegion
-
oslo_cache.core.
get_memoization_decorator
(conf, region, group, expiration_group=None)¶ Build a function based on the cache_on_arguments decorator.
The memoization decorator that gets created by this function is a
dogpile.cache.region.CacheRegion.cache_on_arguments()
decorator, whereThe
should_cache_fn
is set to a function that returns True if both the[cache] enabled
option is true and [group]caching
is True.The
expiration_time
is set from the [expiration_group]cache_time
option ifexpiration_group
is passed in and the value is set, or [group]cache_time
ifexpiration_group
is not passed in and the value is set, or[cache] expiration_time
otherwise.
Example usage:
import oslo_cache.core MEMOIZE = oslo_cache.core.get_memoization_decorator( conf, region, group='group1') @MEMOIZE def function(arg1, arg2): ... ALTERNATE_MEMOIZE = oslo_cache.core.get_memoization_decorator( conf, region, group='group2', expiration_group='group3') @ALTERNATE_MEMOIZE def function2(arg1, arg2): ...
- Parameters
conf (oslo_config.cfg.ConfigOpts) – config object, must have had
configure()
called on it.region (dogpile.cache.region.CacheRegion) – region as created by
create_region()
.group (string) – name of the configuration group to examine
expiration_group (string) – name of the configuration group to examine for the expiration option. This will fall back to using
group
if the value is unspecified orNone
- Return type
function reference
oslo_cache.exception module¶
oslo_cache.testing module¶
Items useful for external testing.
-
class
oslo_cache.testing.
CacheIsolatingProxy
(*arg, **kw)¶ Bases:
dogpile.cache.proxy.ProxyBackend
Proxy that forces a memory copy of stored values.
The default in-memory cache-region does not perform a copy on values it is meant to cache. Therefore if the value is modified after set or after get, the cached value also is modified. This proxy does a copy as the last thing before storing data.
In your application’s tests, you’ll want to set this as a proxy for the in-memory cache, like this:
self.config_fixture.config( group='cache', backend='dogpile.cache.memory', enabled=True, proxies=['oslo_cache.testing.CacheIsolatingProxy'])
-
get
(key)¶ Retrieve an optionally serialized value from the cache.
- Parameters
key – String key that was passed to the
CacheRegion.get()
method, which will also be processed by the “key mangling” function if one was present.- Returns
the Python object that corresponds to what was established via the
CacheBackend.set()
method, or theNO_VALUE
constant if not present.
If a serializer is in use, this method will only be called if the
CacheBackend.get_serialized()
method is not overridden.
-
set
(key, value)¶ Set an optionally serialized value in the cache.
- Parameters
key – String key that was passed to the
CacheRegion.set()
method, which will also be processed by the “key mangling” function if one was present.value – The optionally serialized
CachedValue
object. May be an instance ofCachedValue
or a bytes object depending on if a serializer is in use with the region and if theCacheBackend.set_serialized()
method is not overridden.
See also
CacheBackend.set_serialized()
-
oslo_cache.version module¶
Module contents¶
-
oslo_cache.
configure
(conf)¶ Configure the library.
Register the required oslo.cache config options into an oslo.config CONF object.
This must be called before
configure_cache_region()
.- Parameters
conf (oslo_config.cfg.ConfigOpts) – The configuration object.
-
oslo_cache.
configure_cache_region
(conf, region)¶ Configure a cache region.
If the cache region is already configured, this function does nothing. Otherwise, the region is configured.
- Parameters
conf (oslo_config.cfg.ConfigOpts) – config object, must have had
configure()
called on it.region (dogpile.cache.region.CacheRegion) – Cache region to configure (see
create_region()
).
- Raises
oslo_cache.exception.ConfigurationError – If the region parameter is not a dogpile.cache.CacheRegion.
- Returns
The region.
- Return type
dogpile.cache.region.CacheRegion
-
oslo_cache.
create_region
(function=<function function_key_generator>)¶ Create a region.
This is just dogpile.cache.make_region, but the key generator has a different to_str mechanism.
Note
You must call
configure_cache_region()
with this region before a memoized method is called.- Parameters
function (function) – function used to generate a unique key depending on the arguments of the decorated function
- Returns
The new region.
- Return type
dogpile.cache.region.CacheRegion
-
oslo_cache.
get_memoization_decorator
(conf, region, group, expiration_group=None)¶ Build a function based on the cache_on_arguments decorator.
The memoization decorator that gets created by this function is a
dogpile.cache.region.CacheRegion.cache_on_arguments()
decorator, whereThe
should_cache_fn
is set to a function that returns True if both the[cache] enabled
option is true and [group]caching
is True.The
expiration_time
is set from the [expiration_group]cache_time
option ifexpiration_group
is passed in and the value is set, or [group]cache_time
ifexpiration_group
is not passed in and the value is set, or[cache] expiration_time
otherwise.
Example usage:
import oslo_cache.core MEMOIZE = oslo_cache.core.get_memoization_decorator( conf, region, group='group1') @MEMOIZE def function(arg1, arg2): ... ALTERNATE_MEMOIZE = oslo_cache.core.get_memoization_decorator( conf, region, group='group2', expiration_group='group3') @ALTERNATE_MEMOIZE def function2(arg1, arg2): ...
- Parameters
conf (oslo_config.cfg.ConfigOpts) – config object, must have had
configure()
called on it.region (dogpile.cache.region.CacheRegion) – region as created by
create_region()
.group (string) – name of the configuration group to examine
expiration_group (string) – name of the configuration group to examine for the expiration option. This will fall back to using
group
if the value is unspecified orNone
- Return type
function reference