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 = NoValue.NO_VALUE

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:
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, where

  • The 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 if expiration_group is passed in and the value is set, or [group] cache_time if expiration_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 or None

Return type:

function reference

oslo_cache.exception module

exception oslo_cache.exception.ConfigurationError

Bases: Exception

Raised when the cache isn’t configured correctly.

exception oslo_cache.exception.QueueEmpty

Bases: Exception

Raised when a connection cannot be acquired.

oslo_cache.testing module

Items useful for external testing.

class oslo_cache.testing.CacheIsolatingProxy(*arg, **kw)

Bases: 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 the NO_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 of CachedValue or a bytes object depending on if a serializer is in use with the region and if the CacheBackend.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:
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, where

  • The 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 if expiration_group is passed in and the value is set, or [group] cache_time if expiration_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 or None

Return type:

function reference