oslo_cache package

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.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.core.NO_VALUE = <dogpile.cache.api.NoValue object>

Value returned for nonexistent or expired keys.

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(*args, **kwargs)

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 a value from the cache.

The returned value should be an instance of CachedValue, or NO_VALUE if not present.

set(key, value)

Set a value in the cache.

The key will be whatever was passed to the registry, processed by the “key mangling” function, if any. The value will always be an instance of CachedValue.

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