{"id":7479,"library":"oslo-cache","title":"oslo.cache","description":"oslo.cache is a Python library providing a generic caching mechanism for OpenStack projects, built as a wrapper around the `dogpile.cache` library. It offers support for memoization, key-value storage, and interfaces to common caching backends like Memcached and Redis. The current version is 4.1.1, and it typically follows the OpenStack release cycle, with new versions released regularly to align with OpenStack development milestones.","status":"active","version":"4.1.1","language":"en","source_language":"en","source_url":"https://opendev.org/openstack/oslo.cache","tags":["openstack","caching","memoization","dogpile.cache","oslo"],"install":[{"cmd":"pip install oslo-cache","lang":"bash","label":"Install stable version"},{"cmd":"pip install oslo-cache[dogpile]","lang":"bash","label":"Install with dogpile.cache extras"},{"cmd":"pip install oslo-cache[etcd3gw]","lang":"bash","label":"Install with etcd3gw backend support"}],"dependencies":[{"reason":"Core caching backend wrapper.","package":"dogpile.cache","optional":false},{"reason":"Used for configuration options.","package":"oslo.config","optional":false},{"reason":"Internationalization utilities.","package":"oslo.i18n","optional":false},{"reason":"Logging configuration library.","package":"oslo.log","optional":false},{"reason":"Common utilities.","package":"oslo.utils","optional":false}],"imports":[{"symbol":"cache","correct":"from oslo_cache import core as cache"},{"symbol":"ConfigurationError","correct":"from oslo_cache.exception import ConfigurationError"},{"symbol":"create_region","correct":"from oslo_cache.core import create_region"},{"symbol":"get_memoization_decorator","correct":"from oslo_cache.core import get_memoization_decorator"}],"quickstart":{"code":"import os\nfrom oslo_config import cfg\nfrom oslo_cache import core as cache\n\nCONF = cfg.CONF\n\ndef register_cache_opts():\n    cache_group = cfg.OptGroup('cache', title='Cache Options')\n    CONF.register_group(cache_group)\n    cache.register_opts(CONF)\n\n# Simulate loading configuration (e.g., from a config file)\n# In a real OpenStack project, this would be handled by oslo.config setup\n# For a simple script, we can set some options directly\nCONF.set_default('backend', 'dogpile.cache.memory', group='cache')\nCONF.set_default('expiration_time', 3600, group='cache')\n\nregister_cache_opts()\ncache.configure(CONF)\n\nexample_cache_region = cache.create_region(name='my_app_cache')\nMEMOIZE = cache.get_memoization_decorator(\n    CONF, example_cache_region, 'cache'\n)\n\n@MEMOIZE()\ndef get_heavy_computation_result(value):\n    print(f\"Performing heavy computation for: {value}\")\n    return value * 2\n\nif __name__ == '__main__':\n    print(get_heavy_computation_result(10))\n    print(get_heavy_computation_result(10)) # This should be cached\n    print(get_heavy_computation_result(20))\n    print(get_heavy_computation_result(20)) # This should be cached","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions (deprecation warnings present)"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use the `dogpile.cache.mongo` backend with `oslo.cache` version 4.0.0 or newer. This backend was explicitly removed.","error":"oslo_cache.exception.ConfigurationError: Unsupported cache backend: dogpile.cache.mongo"},{"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`.","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.","error":"DeprecationWarning: The oslo namespace package is deprecated. Please use oslo_config instead."},{"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.","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.","error":"oslo_cache.exception.ConfigurationError: No cache backend specified. Please set 'backend' option under the '[cache]' section in your configuration."}]}