{"id":2486,"library":"dogpile-cache","title":"dogpile-cache","description":"dogpile.cache is a Python caching API, currently at version 1.5.0, designed to prevent the 'cache stampede' or 'dogpile effect' by using a coordinated locking mechanism. It provides a generic interface to various caching backends (e.g., Redis, Memcached, DBM, Valkey, in-memory) through configurable 'cache regions.' The library emphasizes a succinct API for defining cache characteristics, including storage, expiration, and custom key generation, supporting both direct `get_or_create` and function decorator patterns. It is actively developed with a consistent release cadence, offering robust solutions for managing cache invalidation and data regeneration in high-concurrency environments.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/sqlalchemy/dogpile.cache","tags":["caching","cache","dogpile","locking","redis","memcached","valkey","dbm"],"install":[{"cmd":"pip install dogpile-cache","lang":"bash","label":"Install core library"},{"cmd":"pip install dogpile-cache[redis]","lang":"bash","label":"Install with Redis backend"},{"cmd":"pip install dogpile-cache[pylibmc]","lang":"bash","label":"Install with Pylibmc (Memcached) backend"}],"dependencies":[{"reason":"Required for function decorators like @cache_on_arguments.","package":"decorator","optional":false},{"reason":"Used for loading backend plugins.","package":"stevedore","optional":false},{"reason":"Required for the RedisBackend and RedisClusterBackend.","package":"redis","optional":true},{"reason":"Required for the ValkeyBackend.","package":"valkey-py","optional":true},{"reason":"Required for the PylibmcBackend (a Memcached client).","package":"pylibmc","optional":true},{"reason":"Required for the MemcachedBackend (another Memcached client).","package":"python-memcached","optional":true},{"reason":"Required for the PyMemcacheBackend (another Memcached client).","package":"pymemcache","optional":true}],"imports":[{"note":"The primary entry point for creating a cache region.","symbol":"make_region","correct":"from dogpile.cache import make_region"},{"note":"The class representing a configured cache region, often instantiated via make_region().","symbol":"CacheRegion","correct":"from dogpile.cache.region import CacheRegion"},{"note":"A sentinel value indicating a cache miss, distinct from `None`.","symbol":"NO_VALUE","correct":"from dogpile.cache.api import NO_VALUE"}],"quickstart":{"code":"from dogpile.cache import make_region\nimport time\nimport os\n\n# Configure a region using the DBM backend (file-based cache)\n# Replace with 'dogpile.cache.redis' or 'dogpile.cache.pylibmc' for other backends\nregion = make_region(name='my_cache').configure(\n    backend='dogpile.cache.dbm',\n    expiration_time=3600, # seconds\n    arguments={'filename': 'cache.dbm'}\n)\n\n@region.cache_on_arguments()\ndef get_expensive_data(param1, param2):\n    \"\"\"Simulate an expensive computation.\"\"\"\n    print(f\"--- Computing data for {param1}, {param2} ---\")\n    time.sleep(1) # Simulate work\n    return f\"Data for {param1}-{param2} at {time.time()}\"\n\nprint(\"First call (should compute):\")\nprint(get_expensive_data(\"arg_a\", 1))\n\nprint(\"Second call (should be cached):\")\nprint(get_expensive_data(\"arg_a\", 1))\n\nprint(\"Third call with different arguments (should compute):\")\nprint(get_expensive_data(\"arg_b\", 2))\n\n# Clean up the cache file created for the DBM backend\nif os.path.exists('cache.dbm'):\n    os.remove('cache.dbm')\n","lang":"python","description":"This quickstart demonstrates how to set up a cache region with the DBM file-based backend and use the `@region.cache_on_arguments()` decorator to cache the result of an expensive function. Subsequent calls with the same arguments will retrieve the cached value until it expires."},"warnings":[{"fix":"Upgrade Python to 3.10 or newer, or pin `dogpile-cache < 1.4.0`.","message":"Python 3.8 support was dropped in `dogpile.cache` version 1.4.0. The minimum required Python version is now 3.10. Users on older Python versions must remain on `dogpile.cache < 1.4.0`. [cite: rel_1_4_0, 5]","severity":"breaking","affected_versions":"<=1.3.x"},{"fix":"Consult `dogpile.cache` and SQLAlchemy documentation for updated SQLAlchemy caching recipes utilizing the `do_orm_execute()` event model and the unified `Session.scalars(select(...))` interface.","message":"When integrating with SQLAlchemy, caching mechanics changed in SQLAlchemy 1.4 (and 2.0+). The `CachingQuery` subclass approach from `dogpile.cache` examples for SQLAlchemy 1.3 is deprecated; new implementations should use the `do_orm_execute()` event model for caching with `Session.scalars(select(Thing))` interface.","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Review the documentation for the `RedisBackend` or `ValkeyBackend` to understand and configure these new locking parameters as needed for your application's concurrency and key management requirements.","message":"New parameters `lock_blocking_timeout`, `lock_blocking` were added to Redis and Valkey backends in 1.4.1, and `lock_prefix` in 1.5.0. These control the distributed locking behavior and prefixing of lock keys. [cite: rel_1_4_1, rel_1_5_0]","severity":"gotcha","affected_versions":"All versions, especially when upgrading to >=1.4.1"},{"fix":"Upgrade to `dogpile.cache` version 1.3.4 or later if using or planning to use `RedisClusterBackend`.","message":"The `RedisClusterBackend` introduced in version 1.3.2 had runtime typing errors that were fixed in version 1.3.4. Users attempting to use Redis Cluster support should ensure they are on `dogpile.cache` 1.3.4 or a newer version to avoid these issues. [cite: rel_1_3_2, rel_1_3_4]","severity":"gotcha","affected_versions":"1.3.2, 1.3.3"},{"fix":"Carefully design your caching strategy, consider `expiration_time` values, and monitor application performance, especially in scenarios with many concurrent requests. Optimize key generation and data creation functions to minimize lock contention.","message":"While `dogpile.cache` is designed to prevent 'cache stampede' using a 'dogpile lock,' misconfiguration or over-reliance on locks in extremely high-traffic or complex scenarios can still introduce performance bottlenecks or potential deadlocks.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}