oslo.cache

Common errors

• oslo_cache.exception.ConfigurationError: Unsupported cache backend: dogpile.cache.mongo

  cause Attempting to use the `dogpile.cache.mongo` backend with `oslo.cache` version 4.0.0 or newer. This backend was explicitly removed.
  fix Update your configuration to use a supported backend such as `dogpile.cache.memcached`, `oslo_cache.memcache_pool`, or `dogpile.cache.redis`. Ensure the necessary backend dependencies are installed (e.g., `pip install python-memcached` or `pip install redis`).

• DeprecationWarning: The oslo namespace package is deprecated. Please use oslo_config instead.

  cause This warning typically indicates an older `oslo.config` import pattern (e.g., `from oslo.config import cfg`) being used in a project that depends on `oslo.cache`. While not directly from `oslo.cache`, it's a common OpenStack-related dependency warning.
  fix Ensure all `oslo` libraries are updated to their latest compatible versions. Specifically, update `oslo.config` and any code importing it to use `from oslo_config import cfg`.

• oslo_cache.exception.ConfigurationError: No cache backend specified. Please set 'backend' option under the '[cache]' section in your configuration.

  cause The `backend` option for the cache region has not been set in the configuration, which is mandatory for `oslo.cache` to know which `dogpile.cache` backend to utilize.
  fix Add `backend = dogpile.cache.<your_chosen_backend>` to the `[cache]` section of your configuration file or set it programmatically using `CONF.set_default('backend', 'dogpile.cache.<your_chosen_backend>', group='cache')`. Replace `<your_chosen_backend>` with a suitable option like `memory`, `memcached`, `redis`, etc.

Warnings

• breaking The MongoDB backend support was removed in `oslo.cache` version 4.0.0. Projects upgrading from older versions that relied on `dogpile.cache.mongo` will encounter `ConfigurationError` or import issues. This was done to align with Semantic Versioning due to a long-standing broken state with `pymongo` versions 3.x and later.
  Fix: Migrate to a supported backend like Memcached or Redis. If still on older `oslo.cache` and `pymongo` versions, ensure `pymongo<3.0` is used, though this is highly discouraged due to security and compatibility issues.
• deprecated The `[cache]` section options `memcache_username` and `memcache_password` are deprecated and will be removed in a future release, leading to deprecation warnings. These were used for SASL authentication with Memcached.
  Fix: Use the `backend_argument` option to pass Memcached client-specific authentication details, or use environment variables where appropriate for the chosen Memcached client library.
• gotcha Incorrect configuration order can lead to `oslo.cache` not functioning as expected or raising `ConfigurationError`. Specifically, `cache.configure()` must be called before `cache.create_region()`, and `create_region()` must be called before `get_memoization_decorator()` or `configure_cache_region()` are used. The config file should be fully loaded before `configure_cache_region()` is invoked, and all setup calls must complete before a decorated function is used.
  Fix: Always follow the recommended configuration order: register options, load config, `cache.configure(CONF)`, `cache.create_region()`, then `cache.get_memoization_decorator()` or `cache.configure_cache_region()`.

Install

• pip install oslo-cache Install stable version
• pip install oslo-cache[dogpile] Install with dogpile.cache extras
• pip install oslo-cache[etcd3gw] Install with etcd3gw backend support

Imports

• cache

  from oslo_cache import core as cache

• ConfigurationError

  from oslo_cache.exception import ConfigurationError

• create_region

  from oslo_cache.core import create_region

• get_memoization_decorator

  from oslo_cache.core import get_memoization_decorator

Quickstart

This quickstart demonstrates how to set up and use `oslo.cache` with `oslo.config` for memoization. It initializes a cache region and applies a memoization decorator to a function. The first call to `get_heavy_computation_result` will execute the function, subsequent calls with the same arguments will retrieve the cached value. This example uses the `dogpile.cache.memory` backend, suitable for in-process caching. For production, backends like Memcached or Redis are recommended.

import os
from oslo_config import cfg
from oslo_cache import core as cache

CONF = cfg.CONF

def register_cache_opts():
    cache_group = cfg.OptGroup('cache', title='Cache Options')
    CONF.register_group(cache_group)
    cache.register_opts(CONF)

# Simulate loading configuration (e.g., from a config file)
# In a real OpenStack project, this would be handled by oslo.config setup
# For a simple script, we can set some options directly
CONF.set_default('backend', 'dogpile.cache.memory', group='cache')
CONF.set_default('expiration_time', 3600, group='cache')

register_cache_opts()
cache.configure(CONF)

example_cache_region = cache.create_region(name='my_app_cache')
MEMOIZE = cache.get_memoization_decorator(
    CONF, example_cache_region, 'cache'
)

@MEMOIZE()
def get_heavy_computation_result(value):
    print(f"Performing heavy computation for: {value}")
    return value * 2

if __name__ == '__main__':
    print(get_heavy_computation_result(10))
    print(get_heavy_computation_result(10)) # This should be cached
    print(get_heavy_computation_result(20))
    print(get_heavy_computation_result(20)) # This should be cached