oslo_cache package

updated: 2019-09-06 03:05

oslo_cache package¶

Subpackages¶

oslo_cache.backends 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)¶

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)¶