oslo_cache package

updated: 2017-07-18 13:10

oslo_cache package

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.

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

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

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: exceptions.Exception

Raised when the cache isn’t configured correctly.

exception oslo_cache.exception.QueueEmpty¶

Bases: exceptions.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)¶

set(key, value)¶

oslo_cache.version module¶

Module contents¶

oslo_cache.configure(conf)¶