oslo.cache — Library interface

Library interface — oslo.cache — branch stable/2026.2

Branch stable/2026.2 @ fc96999a99e4 (4.3.0 + 3 commits) — repository https://opendev.org/openstack/oslo.cache — analysed on 2026-10-28

oslo.cache exposes no service. It is a thin layer over dogpile.cache (1.5.0 in the analysed environment) that OpenStack services use to:

1. build a dogpile cache region from the [cache] section of their configuration;
2. memoize functions, with a per-group switch and TTL.

Everything that travels to memcached or Redis is decided by dogpile.cache and the client library, configured by oslo.cache. 03 describes that traffic, and 07 the contract a Go service must respect to share it.

1. Public API

The package exports 5 names (oslo_cache/__init__.py):

Other entry points used by services:

• oslo_cache.testing.CacheIsolatingProxy: proxy that deep-copies values for the in-memory test backend (oslo_cache/testing.py:52-76);
• the deprecated function_key_generator and kwarg_function_key_generator wrappers, which only call dogpile's (oslo_cache/core.py:408-431);
• private but imported by keystonemiddleware: oslo_cache._memcache_pool.MemcacheClientPool and oslo_cache._bmemcache_pool.BMemcacheClientPool, used by the auth_token token cache (keystonemiddleware:keystonemiddleware/auth_token/_cache.py:105-110). Renaming them breaks keystonemiddleware.

2. Configuring a region

configure_cache_region (oslo_cache/core.py:459-513):

1. refuses anything that is not a dogpile CacheRegion (ConfigurationError, oslo_cache/core.py:478-481);
2. does nothing if the region is already configured;
3. builds a flat dictionary <config_prefix>.backend, <config_prefix>.expiration_time, <config_prefix>.arguments.* with _build_cache_config (oslo_cache/core.py:130-389), and gives it to dogpile's configure_from_config;
4. wraps the backend with _DebugProxy if debug_cache_backend is set: every get, set and delete is logged with its key and value (oslo_cache/core.py:74-120);
5. installs the SHA-1 key mangler if the backend has none (oslo_cache/core.py:498-499);
6. wraps the backend with each class listed in proxies.

From [cache] to backend arguments

_build_cache_config (oslo_cache/core.py:130-389). The 17 cases recorded in _rewrite/config-mapping_stable-2026.2.json show its output.

The pooled memcached backend oslo_cache.memcache_pool

PooledMemcachedBackend (oslo_cache/backends/memcache_pool.py:48-107) is dogpile's python-memcached backend, but each call borrows a client from a pool (ClientProxy, oslo_cache/backends/memcache_pool.py:36-45):

• pool: at most memcache_pool_maxsize (10) clients; an idle client is closed after memcache_pool_unused_timeout (60 s); waiting for a client is limited to memcache_pool_connection_get_timeout (10 s), then QueueEmpty is raised (oslo_cache/_memcache_pool.py:179-201);
• dead servers: a client that finds a dead server reports it to the pool, which marks it dead for every client for memcache_dead_retry (300 s) (oslo_cache/_memcache_pool.py:285-321);
• TLS or SASL: the pool switches to python-binary-memcached (BMemcacheClientPool, memcached binary protocol, oslo_cache/_bmemcache_pool.py:65-89). SASL without username and password is refused (oslo_cache/backends/memcache_pool.py:70-82).

Other backends provided: oslo_cache.dict (in-process dictionary, oslo_cache/backends/dictionary.py:29-111) and oslo_cache.etcd3gw (etcd v3 through its HTTP gateway, values as JSON, oslo_cache/backends/etcd3gw.py:30-81).

3. Memoization

get_memoization_decorator (oslo_cache/core.py:577-648) returns region.cache_on_arguments(should_cache_fn=…, expiration_time=…):

• cache or not: the value is stored only if [cache] enabled and [<group>] caching (default True if the option does not exist) (oslo_cache/core.py:536-541). The cache is still read when caching = false (scenario 8 of 07);
• TTL: [<expiration_group>] cache_time if set, otherwise [cache] expiration_time (oslo_cache/core.py:569-572). It is read at each call, so a change of configuration applies without restart;
• key: dogpile's function_key_generator, <module>:<function name>|<arguments separated by spaces>. self/cls are dropped, and keyword arguments are refused. Through the decorator, default values are included: get_project("p1") gives …:get_project|p1 default. The key then goes through the SHA-1 mangler.
• The decorator carries should_cache and get_expiration_time, to pre-fill the cache (oslo_cache/core.py:642-646).

4. Options ([cache], oslo_cache/_opts.py:34-412)

Source: reverse-spec-oslo.cache/01-library-interface_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.