manpages

oslocache(1)

OSLOCACHE(1) oslo.cache OSLOCACHE(1)

NAME

oslocache - oslo.cache 3.10.1

Cache storage for OpenStack projects.

CONTENTS

Installation

At the command line:

$ pip install oslo.cache


Contributing

If you would like to contribute to the development of oslo's libraries, first you must take a look to this page:

https://specs.openstack.org/openstack/oslo-specs/specs/policy/contributing.html


If you would like to contribute to the development of OpenStack, you must follow the steps in this page:

https://docs.openstack.org/infra/manual/developers.html


Once those steps have been completed, changes to OpenStack should be submitted for review via the Gerrit tool, following the workflow documented at:

https://docs.openstack.org/infra/manual/developers.html#development-workflow


Pull requests submitted through GitHub will be ignored.

Bugs should be filed on Launchpad, not GitHub:

https://bugs.launchpad.net/oslo.cache


Configuration Options

oslo.cache uses oslo.config to define and manage configuration options to allow the deployer to control how an application uses this library.

cache

config_prefix
Type
string
Default
cache.oslo

Prefix for building the configuration dictionary for the cache region. This should not need to be changed unless there is another dogpile.cache region with the same configuration name.


expiration_time
Type
integer
Default
600
Minimum Value
1

Default TTL, in seconds, for any cached item in the dogpile.cache region. This applies to any cached method that doesn't have an explicit cache expiration time defined for it.


backend_expiration_time
Type
integer
Default
<None>
Minimum Value
1

Expiration time in cache backend to purge expired records automatically. This should be greater than expiration_time and all cache_time options


backend
Type
string
Default
dogpile.cache.null
Valid Values
oslo_cache.memcache_pool, oslo_cache.dict, oslo_cache.mongo, oslo_cache.etcd3gw, dogpile.cache.pymemcache, dogpile.cache.memcached, dogpile.cache.pylibmc, dogpile.cache.bmemcached, dogpile.cache.dbm, dogpile.cache.redis, dogpile.cache.redis_sentinel, dogpile.cache.memory, dogpile.cache.memory_pickle, dogpile.cache.null

Cache backend module. For eventlet-based or environments with hundreds of threaded servers, Memcache with pooling (oslo_cache.memcache_pool) is recommended. For environments with less than 100 threaded servers, Memcached (dogpile.cache.memcached) or Redis (dogpile.cache.redis) is recommended. Test environments with a single instance of the server can use the dogpile.cache.memory backend.


backend_argument
Type
multi-valued
Default
''

Arguments supplied to the backend module. Specify this option once per argument to be passed to the dogpile.cache backend. Example format: "<argname>:<value>".


proxies
Type
list
Default
[]

Proxy classes to import that will affect the way the dogpile.cache backend functions. See the dogpile.cache documentation on changing-backend-behavior.


enabled
Type
boolean
Default
False

Global toggle for caching.


debug_cache_backend
Type
boolean
Default
False

Extra debugging from the cache backend (cache keys, get/set/delete/etc calls). This is only really useful if you need to see the specific cache-backend get/set/delete calls with the keys/values. Typically this should be left set to false.


memcache_servers
Type
list
Default
['localhost:11211']

Memcache servers in the format of "host:port". This is used by backends dependent on Memcached.If dogpile.cache.memcached or oslo_cache.memcache_pool is used and a given host refer to an IPv6 or a given domain refer to IPv6 then you should prefix the given address with the address family (inet6) (e.g inet6[::1]:11211, inet6:[fd12:3456:789a:1::1]:11211, inet6:[controller-0.internalapi]:11211). If the address family is not given then these backends will use the default inet address family which corresponds to IPv4


memcache_dead_retry
Type
integer
Default
300

Number of seconds memcached server is considered dead before it is tried again. (dogpile.cache.memcache and oslo_cache.memcache_pool backends only).


memcache_socket_timeout
Type
floating point
Default
1.0

Timeout in seconds for every call to a server. (dogpile.cache.memcache and oslo_cache.memcache_pool backends only).


memcache_pool_maxsize
Type
integer
Default
10

Max total number of open connections to every memcached server. (oslo_cache.memcache_pool backend only).


memcache_pool_unused_timeout
Type
integer
Default
60

Number of seconds a connection to memcached is held unused in the pool before it is closed. (oslo_cache.memcache_pool backend only).


memcache_pool_connection_get_timeout
Type
integer
Default
10

Number of seconds that an operation will wait to get a memcache client connection.


memcache_pool_flush_on_reconnect
Type
boolean
Default
False

Global toggle if memcache will be flushed on reconnect. (oslo_cache.memcache_pool backend only).


memcache_sasl_enabled
Type
boolean
Default
False

Enable the SASL(Simple Authentication and SecurityLayer) if the SASL_enable is true, else disable.


memcache_username
Type
string
Default
<None>

the user name for the memcached which SASL enabled


memcache_password
Type
string
Default
<None>

the password for the memcached which SASL enabled


redis_server
Type
string
Default
localhost:6379

Redis server in the format of "host:port"


redis_db
Type
integer
Default
0
Minimum Value
0

Database id in Redis server


redis_username
Type
string
Default
<None>

the user name for redis


redis_password
Type
string
Default
<None>

the password for redis


redis_sentinels
Type
list
Default
['localhost:26379']

Redis sentinel servers in the format of "host:port"


redis_socket_timeout
Type
floating point
Default
1.0

Timeout in seconds for every call to a server. (dogpile.cache.redis and dogpile.cache.redis_sentinel backends only).


redis_sentinel_service_name
Type
string
Default
mymaster

Service name of the redis sentinel cluster.


tls_enabled
Type
boolean
Default
False

Global toggle for TLS usage when communicating with the caching servers. Currently supported by dogpile.cache.bmemcache, dogpile.cache.pymemcache, oslo_cache.memcache_pool, dogpile.cache.redis and dogpile.cache.redis_sentinel.


tls_cafile
Type
string
Default
<None>

Path to a file of concatenated CA certificates in PEM format necessary to establish the caching servers' authenticity. If tls_enabled is False, this option is ignored.


tls_certfile
Type
string
Default
<None>

Path to a single file in PEM format containing the client's certificate as well as any number of CA certificates needed to establish the certificate's authenticity. This file is only required when client side authentication is necessary. If tls_enabled is False, this option is ignored.


tls_keyfile
Type
string
Default
<None>

Path to a single file containing the client's private key in. Otherwise the private key will be taken from the file specified in tls_certfile. If tls_enabled is False, this option is ignored.


tls_allowed_ciphers
Type
string
Default
<None>

Set the available ciphers for sockets created with the TLS context. It should be a string in the OpenSSL cipher list format. If not specified, all OpenSSL enabled ciphers will be available. Currently supported by dogpile.cache.bmemcache, dogpile.cache.pymemcache and oslo_cache.memcache_pool.


enable_socket_keepalive
Type
boolean
Default
False

Global toggle for the socket keepalive of dogpile's pymemcache backend


socket_keepalive_idle
Type
integer
Default
1
Minimum Value
0

The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes. Should be a positive integer most greater than zero.


socket_keepalive_interval
Type
integer
Default
1
Minimum Value
0

The time (in seconds) between individual keepalive probes. Should be a positive integer greater than zero.


socket_keepalive_count
Type
integer
Default
1
Minimum Value
0

The maximum number of keepalive probes TCP should send before dropping the connection. Should be a positive integer greater than zero.


enable_retry_client
Type
boolean
Default
False

Enable retry client mechanisms to handle failure. Those mechanisms can be used to wrap all kind of pymemcache clients. The wrapper allows you to define how many attempts to make and how long to wait between attemots.


retry_attempts
Type
integer
Default
2
Minimum Value
1

Number of times to attempt an action before failing.


retry_delay
Type
floating point
Default
0

Number of seconds to sleep between each attempt.


hashclient_retry_attempts
Type
integer
Default
2
Minimum Value
1

Amount of times a client should be tried before it is marked dead and removed from the pool in the HashClient's internal mechanisms.


hashclient_retry_delay
Type
floating point
Default
1

Time in seconds that should pass between retry attempts in the HashClient's internal mechanisms.


dead_timeout
Type
floating point
Default
60

Time in seconds before attempting to add a node back in the pool in the HashClient's internal mechanisms.


enforce_fips_mode
Type
boolean
Default
False

Global toggle for enforcing the OpenSSL FIPS mode. This feature requires Python support. This is available in Python 3.9 in all environments and may have been backported to older Python versions on select environments. If the Python executable used does not support OpenSSL FIPS mode, an exception will be raised. Currently supported by dogpile.cache.bmemcache, dogpile.cache.pymemcache and oslo_cache.memcache_pool.


Using oslo.cache

Usage

A simple example of oslo.cache in use:

from oslo_cache import core as cache
from oslo_config import cfg
CONF = cfg.CONF
caching = cfg.BoolOpt('caching', default=True)
cache_time = cfg.IntOpt('cache_time', default=3600)
CONF.register_opts([caching, cache_time], "feature-name")
cache.configure(CONF)
example_cache_region = cache.create_region()
MEMOIZE = cache.get_memoization_decorator(


    CONF, example_cache_region, "feature-name")
# Load config file here
cache.configure_cache_region(CONF, example_cache_region)
@MEMOIZE
def f(x):


    print(x)


    return x


An example config file for this is:

[cache]
enabled = true
backend = dogpile.cache.memory
[feature-name]
caching = True
cache_time = 7200


There is some subtlety in the order of the calls in the example above. The requirements are: configure must be done first; create_region must be before both get_memoization_decorator and configure_cache_region (because they use the output); the config file must be fully loaded before configure_cache_region is called; all these calls must complete before a decorated function is actually invoked. In principle, there are several different orders this can happen in. In practice, the decorator will be used at import time, and the config file will be loaded later, so the above order is the only possible one.

CHANGES

3.10.1

  • Skip installation to speed up pep8
  • Adjust warning message for eventlet support deprecation

3.10.0

  • deprecate using memcache_pool backend into an eventlet env
  • Skip functional tests for documentation update
  • Get rid of third party mock library
  • Detect service ports from pifpaf environments
  • Fix etcd package
  • reno: Update master for unmaintained/2023.1

3.9.0

  • Add note about requirements lower bounds
  • Run pyupgrade to clean up Python 2 syntaxes
  • Remove Python 3.8 support
  • Support expiration time in backend
  • Fix outdated tox minversion
  • Declare Python 3.12 support
  • Use oslo.utils implementation to parse sentinel address
  • Update master for stable/2024.2

3.8.0

  • redis: Make database id configurable
  • Use f-string when creating config dict
  • Redis Sentinel: Use dogpile.cache interface for username
  • reno: Update master for unmaintained/zed
  • Remove old excludes
  • Redis: Support socket keepalive
  • Update master for stable/2024.1
  • reno: Update master for unmaintained/xena
  • reno: Update master for unmaintained/wallaby
  • reno: Update master for unmaintained/victoria

3.7.0

  • Fix incomplete exception message
  • Prevent potential ReDoS attack
  • config: Document backends supporting specific options
  • Ensure requirements are capped by upper constraints
  • Display coverage report
  • reno: Update master for unmaintained/yoga
  • redis: Add functional tests
  • Add support for Redis Sentinel backend
  • Add native options for redis backend
  • memcache: Remove "default" username and password
  • Automate TLS certificates settings for redis backend
  • Fail if tls_enabled is True but backend does not support it
  • Fix minor typos in parameter help texts
  • pre-commit: Integrate bandit
  • pre-commit: Bump versions
  • Bump hacking (again)
  • Add a new option to enforce the OpenSSL FIPS mode
  • Bump hacking
  • Update python classifier in setup.cfg

3.6.0

  • Fix wrong path in coveragerc
  • Clean-up memcache connection sockets
  • Update master for stable/2023.2

3.5.0

  • Imported Translations from Zanata
  • Bump bandit
  • Imported Translations from Zanata

3.4.0

  • Revert "Moves supported python runtimes from version 3.8 to 3.10"
  • Moves supported python runtimes from version 3.8 to 3.10
  • [cache] memcache_password should be secret
  • Do not mark hosts as alive when they are all dead
  • Update master for stable/2023.1
  • Allow bmemcached to be optional for memcache_pool
  • Imported Translations from Zanata

3.3.1

  • Fix issues related to tox4
  • Cleanup py27 support

3.3.0

  • Imported Translations from Zanata
  • Add Python3 antelope unit tests
  • Update master for stable/zed
  • Add bmemcached as optional dependency

3.1.0

3.0.0

  • Imported Translations from Zanata
  • Drop python3.6/3.7 support in testing runtime
  • Support SASL protocol for memcached

2.11.0

  • Remove unnecessary unicode prefixes
  • Fix description of memcache_servers
  • Add Python3 zed unit tests
  • Update master for stable/yoga

2.10.1

  • Use the right backend for TLS tests
  • Add Python 3 only classifier

2.10.0

  • Expose pymemcache's HashClient public params
  • Add retry mechanisms to oslo.cache
  • Add socket keepalive options to oslo.cache

2.9.0

  • Update python testing classifier
  • Drop pymongo useless and removed attribute
  • Add Python3 yoga unit tests
  • Update master for stable/xena
  • fix typo

2.8.1

•
Don't import module "etcd3gw" if etcd3gw backend is not used

2.8.0

  • setup.cfg: Replace dashes with underscores
  • Move flake8 as a pre-commit local target
  • Add Python3 xena unit tests
  • Update master for stable/wallaby
  • Adding technical details about the memcache pool backend
  • Add bug comment and fix nits
  • Dropping lower constraints testing

2.7.0

  • Drop use of deprecated collections classes
  • Add dogpile.cache.pymemcache backend
  • Use py3 as the default runtime for tox
  • Do not hardcode flush_on_reconnect, move to oslo.cache config
  • Dropping lower constraints testing
  • Imported Translations from Zanata
  • Add Python3 wallaby unit tests
  • Update master for stable/victoria

2.6.1

  • Adding functional tests for memcache_pool backend
  • Add Memcached functional tests to gate

2.6.0

  • Add python-binary-memcached to support SASL
  • Drop hard choice on py38 for functional tests
  • Bump dogpile.cache's version for Memcached TLS support
  • Add pre-commit to pep8 gate
  • Apply fixes for pre-commit compliance in all code
  • Uses commit hash instead of version tags in pre-commit
  • Removes pre-commit hooks from Lucas-C
  • Bump bandit version
  • Introducing usage of pre-commit

2.5.0

  • Update lower-constraints versions
  • Add TLS context creation from config
  • Add TLS options to oslo.cache
  • Fix pygments style

2.4.1

•
Stop to use the __future__ module

2.4.0

  • Refactoring functional tests based on standard usages
  • Switch to newer openstackdocstheme and reno versions
  • Remove the unused coding style modules
  • Fix pep8 failure
  • Adding functional tests
  • Small cleanups in tox.ini
  • Remove unneeded babel.cfg etc
  • Remove six
  • Switch to Victoria tests
  • Align contributing doc with oslo's policy
  • [doc] tell to prefix ipv6 hosts with inet6
  • Add release notes links to doc index
  • Imported Translations from Zanata
  • Update master for stable/ussuri

2.3.0

  • Use unittest.mock instead of third party mock
  • Update hacking for Python3

2.2.0

  • Add memcache_pool backend job
  • Revert "Switch from python-memcached to pymemcache."
  • Remove dogpile kwarg test
  • Fix python2 syntaxe in doc
  • Fix pymemcache release note python package name

2.1.0

  • Switch from python-memcached to pymemcache
  • trivial: Cleanup tox.ini
  • remove outdated header

2.0.0

  • [ussuri][goal] Drop python 2.7 support and testing
  • Ignore reno artifacts
  • tox: Trivial cleanup

1.38.1

•
Imported Translations from Zanata

1.38.0

  • tox: Keeping going with docs
  • Update master for stable/train
  • Update memcached configuration help text

1.37.0

  • Lower the memcache_socket_timeout to one second
  • Add Python 3 Train unit tests

1.36.0

•
Pass server_max_value_length to memcached client

1.35.0

  • Cap Bandit below 1.6.0 and update Sphinx requirement
  • Replace git.openstack.org URLs with opendev.org URLs
  • tox: Use the new hotness for constraints
  • Avoid tox_install.sh for constraints support
  • Fix lower-constraints

1.34.0

  • OpenDev Migration Patch
  • Dropping the py35 testing
  • Pass `flush_on_reconnect` to memcache pooled backend
  • Update master for stable/stein
  • Update hacking version
  • add python 3.7 unit test job

1.33.2

•
Fix memcache pool client in monkey-patched environments

1.33.1

  • fix dogpile.cache issue due to the new usage of decorate in the lib
  • Remove stale comment in _memcache_pool

1.33.0

•
uncap dogpile

1.32.0

  • Update the requirements to match global-requirements for dogpile.cache
  • Use template for lower-constraints

1.31.2

  • Update mailinglist from dev to discuss
  • Only split url arg with memcache backend

1.31.1

  • Config dict arguments.url must be a list
  • Clean up .gitignore references to personal tools
  • Don't quote {posargs} in tox.ini
  • Always build universal wheels

1.31.0

  • Imported Translations from Zanata
  • Drop expired connections before retrieving from the queue
  • add lib-forward-testing-python3 test job
  • add python 3.6 unit test job
  • import zuul job settings from project-config
  • Update reno for stable/rocky
  • tox: Fix typo
  • Switch to stestr
  • Add release notes link to README
  • fix tox python3 overrides

1.30.1

  • Imported Translations from Zanata
  • Don't let tox_install.sh error if there is nothing to do
  • Remove stale pip-missing-reqs tox test
  • Trivial: Update pypi url to new url
  • Avoid use of autodoc_tree_index_modules
  • Switch pep8 job to python 3
  • Fix incompatible requirement in lower constraints

1.30.0

  • Change memcache_socket_timeout to a float
  • add lower-constraints job
  • Clean old output before new doc builds
  • Updated from global requirements

1.29.0

  • Update links in README
  • Imported Translations from Zanata
  • Imported Translations from Zanata
  • Update reno for stable/queens
  • Updated from global requirements
  • Updated from global requirements

1.28.0

  • Follow the new PTI for document build
  • add bandit to pep8 job
  • Updated from global requirements

1.27.0

  • Remove setting of version/release from releasenotes
  • Updated from global requirements
  • Add more cache backend options
  • Updated from global requirements
  • Imported Translations from Zanata
  • Imported Translations from Zanata
  • Updated from global requirements
  • Updated from global requirements

1.26.0

  • Updated from global requirements
  • Update the documentation link for doc migration
  • Imported Translations from Zanata
  • Update reno for stable/pike
  • Updated from global requirements

1.25.0

  • Imported Translations from Zanata
  • update the doc URLs

1.24.0

  • turn on warning-is-error in doc build
  • switch from oslosphinx to openstackdocstheme
  • rearrange content to fit the new standard layout
  • Change locations of docs for intersphinx
  • Improve backend configuration help text
  • Add kwarg function key generator
  • Fix error in cache.configure_cache_region usage doc
  • Updated from global requirements

1.23.0

  • Updated from global requirements
  • Updated from global requirements
  • etcd3 : get rid of ast_literal

1.22.0

  • etcd3 driver for oslo.cache
  • Updated from global requirements
  • Updated from global requirements

1.21.0

  • Remove unused/duplicated logging import
  • Optimize the link address
  • Updated from global requirements
  • Check reStructuredText documents for common style issues

1.20.0

•
Remove log translations

1.19.0

  • Updated from global requirements
  • Replaces uuid.uuid4 with uuidutils.generate_uuid()

1.18.0

  • Updated from global requirements
  • [Fix gate]Update test requirement
  • Updated from global requirements
  • pbr.version.VersionInfo needs package name (oslo.xyz and not oslo_xyz)
  • Update reno for stable/ocata
  • Switch to oslo_log

1.17.0

  • Remove references to Python 3.4
  • Add Constraints support
  • Show team and repo badges on README

1.16.0

  • Updated from global requirements
  • Updated from global requirements
  • Imported Translations from Zanata
  • TrivialFix: Remove default=None when set value in Config
  • Changed the home-page link

1.15.0

  • Enable release notes translation
  • Updated from global requirements
  • Updated from global requirements
  • Update reno for stable/newton
  • Updated from global requirements

1.14.0

  • Add usage example to documentation
  • Fix docstring for get_memoization_decorator
  • Correct help text for backend option

1.13.0

•
Updated from global requirements

1.12.0

  • Updated from global requirements
  • Fix OpenStack capitalization
  • Add Python 3.5 classifier and venv
  • Imported Translations from Zanata
  • Updated from global requirements

1.11.0

•
Updated from global requirements

1.10.0

  • Handle empty memcache pool corner case
  • Updated from global requirements
  • Imported Translations from Zanata
  • Fixup intersphinx docs
  • Use entrypoints for backends

1.9.0

  • Updated from global requirements
  • Add reno for releasenotes management

1.8.0

•
Trivial: ignore openstack/common in flake8 exclude list

1.7.0

  • Imported Translations from Zanata
  • Remove direct dependency on babel
  • Imported Translations from Zanata
  • Updated from global requirements
  • If caching is globally disabled force dogpile to use the null backend
  • Updated from global requirements
  • Updated from global requirements

1.5.0

  • Updated from global requirements
  • Updated from global requirements

1.4.0

•
Updated from global requirements

1.3.0

  • Move some of these noisy logs to trace level
  • Revert "Use assertTrue/False instead of assertEqual(T/F)"
  • Update translation setup
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Delete python bytecode before every test run

1.2.0

  • Use assertTrue/False instead of assertEqual(T/F)
  • Updated from global requirements
  • Replace deprecated LOG.warn with LOG.warning
  • Updated from global requirements

1.1.0

  • Updated from global requirements
  • Updated from global requirements
  • Trival: Remove 'MANIFEST.in'

1.0.0

  • Updated from global requirements
  • Remove Python 2.6 classifier
  • Remove python 2.6 and cleanup tox.ini
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements

0.9.0

  • Updated from global requirements
  • Export functions from __init__

0.8.0

  • Make CacheIsolatingProxy public
  • Add shields.io version/downloads links/badges into README.rst
  • add auto-generated docs for config options
  • Change ignore-errors to ignore_errors
  • Updated from global requirements

0.7.0

  • Updated from global requirements
  • Implement get/set/delete multiple keys for dictionary backend

0.6.0

  • Move optional backend dependencies into setup.cfg [extras]
  • Ignore the .eggs/ directory
  • Remove remnants of noop backend registration
  • Updated from global requirements
  • Updated from global requirements
  • Setup translations
  • flake8 - remove unused rules and fix imports
  • Updated from global requirements

0.5.0

  • Updated from global requirements
  • Updated from global requirements
  • Remove NoOp cache from oslo.cache

0.4.0

  • Added NO_VALUE to core file
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Fix some reminders of 'keystone' in oslo.cache
  • Updated from global requirements

0.3.0

  • Updated from global requirements
  • Fixes up the API docs and module index
  • Region handling
  • Don't register backends on import
  • Changed some comments and docs in DictCacheBackend
  • Implemented DictCacheBackend
  • Fixed typos

0.2.0

  • Usage docs
  • Document the backends
  • Remove unused _on_arguments
  • Fix up option help
  • Register backends in a cycle
  • Use "group" rather than "section"
  • swap the order of conf for a function
  • Don't use global conf
  • Make DebugProxy private
  • make REGION public
  • Fix docstring for configure_cache_region
  • Remove useless docs from private functions
  • Fix docs for get_memoization_decorator
  • Docs for configure()

0.1.2

  • Make symbols private
  • Module docs
  • Cleanup exceptions
  • handle utf8 encoding properly
  • Expose list_opts entry points for oslo-config-generator
  • Remove unnecessary file
  • Add tests for _memcache_pool

0.1.1

  • remove non-cache related options
  • Add oslo.i18n to requirements
  • Add tox target to find missing requirements
  • Update i18n domain to correct project name

0.1.0

  • Enable all commented out tests
  • Updated from global requirements
  • Move files into the right spot and get tests working
  • fix branch name in .gitreview
  • Updated from global requirements
  • Updated from global requirements
  • Remove unnecessary openstack-common.conf
  • Remove empty script reference
  • Fix name of oslotest base test case
  • Get project basics configured
  • Fixes use of dict methods for Python3
  • Handles Python3 builtin changes
  • Make memcache client reusable across threads
  • Make memcache client reusable across threads
  • Work with pymongo 3.0
  • Initial commit from oslo cookiecutter template
  • Work with pymongo 3.0
  • Prefer . to setattr()/getattr()
  • Address nits for default cache time more explicit
  • Fix the wrong order of parameters when using assertEqual
  • Fixes minor whitespace issues
  • Make the default cache time more explicit in code
  • Use dict comprehensions instead of dict constructor
  • Consistently use oslo_config.cfg.CONF
  • Fix invalid super() usage in memcache pool
  • Use oslo.log instead of incubator
  • Move existing tests to unit
  • Change oslo.utils to oslo_utils
  • Memcache connection pool excess check
  • Adds missing log hints for level E/I/W
  • Remove nonexistant param from docstring
  • Use importutils from oslo.utils
  • Address some late comments for memcache clients
  • Add a pool of memcached clients
  • Use functions in oslo.utils
  • Introduce pragma no cover to asbtract classes
  • Use oslo.i18n
  • Do not support toggling key_manglers in cache layer
  • Adds hacking check for debug logging translations
  • remove a few backslash line continuations
  • Fixed some typos throughout the codebase
  • Fix cache configuration checks
  • Safer noqa handling
  • Uses explicit imports for _
  • Support for mongo as dogpile cache backend
  • Remove copyright from empty files
  • Remove vim header
  • Documentation cleanup
  • Style improvements to logging format strings
  • Handle unicode at the caching layer more elegantly
  • Implement basic caching around assignment CRUD
  • Implement caching for Tokens and Token Validation
  • Add Memory Isolating Cache Proxy
  • Implement Caching for Token Revocation List
  • Keystone Caching Layer for Manager Calls
  • initial
  • Initial
  • first commit

Reference

oslo_cache

oslo_cache package

Subpackages

oslo_cache.backends package

Submodules

oslo_cache.backends.dictionary module

dogpile.cache backend that uses dictionary for storage

class oslo_cache.backends.dictionary.DictCacheBackend(arguments)
Bases: CacheBackend

A DictCacheBackend based on dictionary.

Arguments accepted in the arguments dictionary:

Parameters
expiration_time (real) -- interval in seconds to indicate maximum time-to-live value for each key in DictCacheBackend. Default expiration_time value is 0, that means that all keys have infinite time-to-live value.

delete(key)
Deletes the value associated with the key if it exists.
Parameters
key -- dictionary key


delete_multi(keys)
Deletes the value associated with each key in list if it exists.
Parameters
keys -- list of dictionary keys


get(key)
Retrieves the value for a key.
Parameters
key -- dictionary key
Returns
value for a key or oslo_cache.core.NO_VALUE for nonexistent or expired keys.


get_multi(keys)
Retrieves the value for a list of keys.

set(key, value)
Sets the value for a key.

Expunges expired keys during each set.

Parameters
  • key -- dictionary key
  • value -- value associated with the key



set_multi(mapping)
Set multiple values in the cache. Expunges expired keys during each set.
Parameters
mapping -- dictionary with key/value pairs



oslo_cache.backends.etcd3gw module

dogpile.cache backend that uses etcd 3.x for storage

class oslo_cache.backends.etcd3gw.Etcd3gwCacheBackend(arguments)
Bases: CacheBackend
DEFAULT_HOST = 'localhost'
Default hostname used when none is provided.

DEFAULT_PORT = 2379
Default port used if none provided (4001 or 2379 are the common ones).

DEFAULT_TIMEOUT = 30
Default socket/lock/member/leader timeout used when none is provided.

delete(key)
Delete a value from the cache.
Parameters
key -- String key that was passed to the CacheRegion.delete() method, which will also be processed by the "key mangling" function if one was present.

The behavior here should be idempotent, that is, can be called any number of times regardless of whether or not the key exists.


delete_multi(keys)
Delete multiple values from the cache.
Parameters
keys -- sequence of string keys that was passed to the CacheRegion.delete_multi() method, which will also be processed by the "key mangling" function if one was present.

The behavior here should be idempotent, that is, can be called any number of times regardless of whether or not the key exists.

Added in version 0.5.0.


get(key)
Retrieve an optionally serialized value from the cache.
Parameters
key -- String key that was passed to the CacheRegion.get() method, which will also be processed by the "key mangling" function if one was present.
Returns
the Python object that corresponds to what was established via the CacheBackend.set() method, or the NO_VALUE constant if not present.

If a serializer is in use, this method will only be called if the CacheBackend.get_serialized() method is not overridden.


get_multi(keys)
Retrieves the value for a list of keys.

set(key, value)
Set an optionally serialized value in the cache.
Parameters
  • key -- String key that was passed to the CacheRegion.set() method, which will also be processed by the "key mangling" function if one was present.
  • value -- The optionally serialized CachedValue object. May be an instance of CachedValue or a bytes object depending on if a serializer is in use with the region and if the CacheBackend.set_serialized() method is not overridden.


SEE ALSO:

CacheBackend.set_serialized()



set_multi(mapping)
Set multiple values in the cache.
Parameters
mapping -- a dict in which the key will be whatever was passed to the CacheRegion.set_multi() method, processed by the "key mangling" function, if any.

When implementing a new CacheBackend or cutomizing via ProxyBackend, be aware that when this method is invoked by Region.get_or_create_multi(), the mapping values are the same ones returned to the upstream caller. If the subclass alters the values in any way, it must not do so 'in-place' on the mapping dict -- that will have the undesirable effect of modifying the returned values as well.

If a serializer is in use, this method will only be called if the CacheBackend.set_serialized_multi() method is not overridden.

Added in version 0.5.0.



oslo_cache.backends.memcache_pool module

dogpile.cache backend that uses Memcached connection pool

class oslo_cache.backends.memcache_pool.ClientProxy(client_pool)
Bases: object

class oslo_cache.backends.memcache_pool.PooledMemcachedBackend(arguments)
Bases: MemcachedBackend

Memcached backend that does connection pooling.

This memcached backend only allows for reuse of a client object, prevents too many client object from being instantiated, and maintains proper tracking of dead servers so as to limit delays when a server (or all servers) become unavailable.

This backend doesn't allow to load balance things between servers.

Memcached isn't HA. Values aren't automatically replicated between servers unless the client went out and wrote the value multiple time.

The memcache server to use is determined by python-memcached itself by picking the host to use (from the given server list) based on a key hash.

property client
Return the memcached client.

This uses a threading.local by default as it appears most modern memcached libs aren't inherently threadsafe.



oslo_cache.backends.mongo module

class oslo_cache.backends.mongo.MongoCacheBackend(arguments)
Bases: CacheBackend

A MongoDB based caching backend implementing dogpile backend APIs.

Arguments accepted in the arguments dictionary:

Parameters
  • db_hosts -- string (required), hostname or IP address of the MongoDB server instance. This can be a single MongoDB connection URI, or a list of MongoDB connection URIs.
  • db_name -- string (required), the name of the database to be used.
  • cache_collection -- string (required), the name of collection to store cached data. Note: Different collection name can be provided if there is need to create separate container (i.e. collection) for cache data. So region configuration is done per collection.


Following are optional parameters for MongoDB backend configuration,

Parameters
  • username -- string, the name of the user to authenticate.
  • password -- string, the password of the user to authenticate.
  • max_pool_size -- integer, the maximum number of connections that the pool will open simultaneously. By default the pool size is 10.
  • w --

    integer, write acknowledgement for MongoDB client

    If not provided, then no default is set on MongoDB and then write acknowledgement behavior occurs as per MongoDB default. This parameter name is same as what is used in MongoDB docs. This value is specified at collection level so its applicable to cache_collection db write operations.

    If this is a replica set, write operations will block until they have been replicated to the specified number or tagged set of servers. Setting w=0 disables write acknowledgement and all other write concern options.

  • read_preference -- string, the read preference mode for MongoDB client Expected value is primary, primaryPreferred, secondary, secondaryPreferred, or nearest. This read_preference is specified at collection level so its applicable to cache_collection db read operations.
  • use_replica -- boolean, flag to indicate if replica client to be used. Default is False. replicaset_name value is required if True.
  • replicaset_name -- string, name of replica set. Becomes required if use_replica is True
  • son_manipulator --

    string, name of class with module name which implements MongoDB SONManipulator. Default manipulator used is BaseTransform.

    This manipulator is added per database. In multiple cache configurations, the manipulator name should be same if same database name db_name is used in those configurations.

    SONManipulator is used to manipulate custom data types as they are saved or retrieved from MongoDB. Custom impl is only needed if cached data is custom class and needs transformations when saving or reading from db. If dogpile cached value contains built-in data types, then BaseTransform class is sufficient as it already handles dogpile CachedValue class transformation.

  • mongo_ttl_seconds --

    integer, interval in seconds to indicate maximum time-to-live value. If value is greater than 0, then its assumed that cache_collection needs to be TTL type (has index at 'doc_date' field). By default, the value is -1 and its disabled. Reference: <http://docs.mongodb.org/manual/tutorial/expire-data/>

    NOTE:

This parameter is different from Dogpile own expiration_time, which is the number of seconds after which Dogpile will consider the value to be expired. When Dogpile considers a value to be expired, it continues to use the value until generation of a new value is complete, when using CacheRegion.get_or_create(). Therefore, if you are setting mongo_ttl_seconds, you will want to make sure it is greater than expiration_time by at least enough seconds for new values to be generated, else the value would not be available during a regeneration, forcing all threads to wait for a regeneration each time a value expires.


  • ssl -- boolean, If True, create the connection to the server using SSL. Default is False. Client SSL connection parameters depends on server side SSL setup. For further reference on SSL configuration: <http://docs.mongodb.org/manual/tutorial/configure-ssl/>
  • ssl_keyfile -- string, the private keyfile used to identify the local connection against mongod. If included with the certfile then only the ssl_certfile is needed. Used only when ssl is True.
  • ssl_certfile -- string, the certificate file used to identify the local connection against mongod. Used only when ssl is True.
  • ssl_ca_certs -- string, the ca_certs file contains a set of concatenated 'certification authority' certificates, which are used to validate certificates passed from the other end of the connection. Used only when ssl is True.
  • ssl_cert_reqs -- string, the parameter cert_reqs specifies whether a certificate is required from the other side of the connection, and whether it will be validated if provided. It must be one of the three values ssl.CERT_NONE (certificates ignored), ssl.CERT_OPTIONAL (not required, but validated if provided), or ssl.CERT_REQUIRED (required and validated). If the value of this parameter is not ssl.CERT_NONE, then the ssl_ca_certs parameter must point to a file of CA certificates. Used only when ssl is True.


Rest of arguments are passed to mongo calls for read, write and remove. So related options can be specified to pass to these operations.

Further details of various supported arguments can be referred from <http://api.mongodb.org/python/current/api/pymongo/>

client
Initializes MongoDB connection and collection defaults.

This initialization is done only once and performed as part of lazy inclusion of MongoDB dependency i.e. add imports only if related backend is used.

Returns
MongoApi instance


delete(key)
Delete a value from the cache.
Parameters
key -- String key that was passed to the CacheRegion.delete() method, which will also be processed by the "key mangling" function if one was present.

The behavior here should be idempotent, that is, can be called any number of times regardless of whether or not the key exists.


delete_multi(keys)
Delete multiple values from the cache.
Parameters
keys -- sequence of string keys that was passed to the CacheRegion.delete_multi() method, which will also be processed by the "key mangling" function if one was present.

The behavior here should be idempotent, that is, can be called any number of times regardless of whether or not the key exists.

Added in version 0.5.0.


get(key)
Retrieves the value for a key.
Parameters
key -- key to be retrieved.
Returns
value for a key or oslo_cache.core.NO_VALUE for nonexistent or expired keys.


get_multi(keys)
Return multiple values from the cache, based on the given keys.
Parameters
keys -- sequence of keys to be retrieved.
Returns
returns values (or oslo_cache.core.NO_VALUE) as a list matching the keys given.


set(key, value)
Set an optionally serialized value in the cache.
Parameters
  • key -- String key that was passed to the CacheRegion.set() method, which will also be processed by the "key mangling" function if one was present.
  • value -- The optionally serialized CachedValue object. May be an instance of CachedValue or a bytes object depending on if a serializer is in use with the region and if the CacheBackend.set_serialized() method is not overridden.


SEE ALSO:

CacheBackend.set_serialized()



set_multi(mapping)
Set multiple values in the cache.
Parameters
mapping -- a dict in which the key will be whatever was passed to the CacheRegion.set_multi() method, processed by the "key mangling" function, if any.

When implementing a new CacheBackend or cutomizing via ProxyBackend, be aware that when this method is invoked by Region.get_or_create_multi(), the mapping values are the same ones returned to the upstream caller. If the subclass alters the values in any way, it must not do so 'in-place' on the mapping dict -- that will have the undesirable effect of modifying the returned values as well.

If a serializer is in use, this method will only be called if the CacheBackend.set_serialized_multi() method is not overridden.

Added in version 0.5.0.



Module contents

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.NO_VALUE = <dogpile.cache.api.NoValue object>
Value returned for nonexistent or expired keys.

oslo_cache.core.configure(conf)
Configure the library.

Register the required oslo.cache config options into an oslo.config CONF object.

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
  • 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.exception module

exception oslo_cache.exception.ConfigurationError
Bases: Exception

Raised when the cache isn't configured correctly.


exception oslo_cache.exception.QueueEmpty
Bases: Exception

Raised when a connection cannot be acquired.


oslo_cache.testing module

Items useful for external testing.

class oslo_cache.testing.CacheIsolatingProxy(*arg, **kw)
Bases: 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 an optionally serialized value from the cache.
Parameters
key -- String key that was passed to the CacheRegion.get() method, which will also be processed by the "key mangling" function if one was present.
Returns
the Python object that corresponds to what was established via the CacheBackend.set() method, or the NO_VALUE constant if not present.

If a serializer is in use, this method will only be called if the CacheBackend.get_serialized() method is not overridden.


set(key, value)
Set an optionally serialized value in the cache.
Parameters
  • key -- String key that was passed to the CacheRegion.set() method, which will also be processed by the "key mangling" function if one was present.
  • value -- The optionally serialized CachedValue object. May be an instance of CachedValue or a bytes object depending on if a serializer is in use with the region and if the CacheBackend.set_serialized() method is not overridden.


SEE ALSO:

CacheBackend.set_serialized()




oslo_cache.version module

Module contents

oslo_cache.configure(conf)
Configure the library.

Register the required oslo.cache config options into an oslo.config CONF object.

This must be called before configure_cache_region().

Parameters
conf (oslo_config.cfg.ConfigOpts) -- The configuration object.


oslo_cache.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.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.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
  • 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


RELEASE NOTES

Read also the oslo.cache Release Notes.

INDICES AND TABLES

  • Index
  • Module Index
  • Search Page

AUTHOR

Author name not set

COPYRIGHT

2025, OpenStack Foundation

April 2, 2025 3.10.1