Install & Compatibility
Where this runs
tested against v0.12.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.353s · 23.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.307s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Cache
✓ from aiocache import Cache
cached
✓ from aiocache.cached import cached
RedisCache
✓ from aiocache.backends.redis import RedisCache
✗ from aiocache.backends.aioredis import RedisCache
As of v0.12.0, aiocache migrated from aioredis to the official redis library.
MemcachedCache
✓ from aiocache.backends.memcached import MemcachedCache
SimpleMemoryCache
✓ from aiocache.backends.memory import SimpleMemoryCache
This quickstart demonstrates how to initialize and use the Redis backend with `aiocache` using the `Cache` factory. It leverages `async with` for automatic connection management and shows setting and getting a key-value pair. Ensure a Redis server is running and accessible.
import asyncio
import os
from aiocache import Cache
async def main():
# Configure Redis cache using environment variables or fallbacks
redis_endpoint = os.environ.get('REDIS_ENDPOINT', 'localhost')
redis_port = int(os.environ.get('REDIS_PORT', '6379'))
# Use async with for proper resource management (auto-closes connection)
async with Cache(Cache.REDIS, endpoint=redis_endpoint, port=redis_port) as cache:
key = "my_async_key"
value = "hello from aiocache"
ttl_seconds = 60
print(f"Setting '{key}' = '{value}' with TTL {ttl_seconds}s")
await cache.set(key, value, ttl=ttl_seconds)
retrieved_value = await cache.get(key)
print(f"Retrieved value for '{key}': {retrieved_value}")
if retrieved_value == value:
print("Value successfully cached and retrieved!")
else:
print("Cache retrieval failed.")
if __name__ == '__main__':
# Ensure Redis server is running at REDIS_ENDPOINT:REDIS_PORT
# e.g., docker run --name some-redis -p 6379:6379 -d redis
asyncio.run(main())
Debug
Known issues
breakingBreaking change: aiocache migrated from `aioredis` to the official `redis` Python library. Existing code using `aioredis` specific APIs or directly importing `aioredis` backend classes will break.fixEnsure `pip install aiocache[redis]` is used. Update any imports or direct usage of `aioredis` client methods to align with the `redis` library's API. For `Cache` factory, connection parameters might need review.
affects: 0.12.0+
breakingBreaking change: The `SimpleMemoryBackend` (and `SimpleMemoryCache`) is no longer a global singleton. Each instance now has its own isolated cache.fixIf your application relied on `SimpleMemoryBackend` instances sharing a global state, you will need to refactor to pass a single `SimpleMemoryCache` instance around or adapt to its new instance-scoped behavior.
affects: 0.12.0+
deprecatedDeprecated `loop` parameters have been removed from most methods and constructors, including `Cache.create()`. Passing an explicit `loop` will now raise an error.fixRemove the `loop` parameter from all `aiocache` calls. `aiocache` now relies on `asyncio`'s default event loop mechanisms.
affects: 0.12.0+
gotchaTyping support was removed in `v0.12.1` due to issues and is planned to be re-introduced in `v1.0`. Users expecting comprehensive type hints will find them missing or causing unresolvable errors.fixDo not rely on `aiocache` for strict type checking until `v1.0`. Temporarily, you might need to use `# type: ignore` for specific `aiocache` related lines if your linter complains.
affects: 0.12.1+ (until v1.0)
gotchaAttempting to use `aiocache` with the Redis backend requires a running Redis server accessible from your application. A `redis.exceptions.ConnectionError` indicates the Redis server is not reachable at the configured host and port (defaulting to `localhost:6379`).fixEnsure a Redis server is running and accessible from the application's environment. Verify Redis host and port configuration, for example, via environment variables like `REDIS_HOST`, `REDIS_PORT`, or directly in `aiocache.Cache` connection parameters.
affects: 0.12.0+
gotchaWhen using the Redis backend, `aiocache` requires a running and accessible Redis server. A `redis.exceptions.ConnectionError` indicates that the connection to the configured Redis server failed.fixEnsure a Redis server is running and accessible from the application's environment, typically on `localhost:6379`. Verify the `endpoint` and `port` parameters when initializing `aiocache.Cache.create(backend='redis', ...)`.
affects: 0.12.0+
Errors
Common errors & fixes
AttributeError: module 'aiocache' has no attribute 'cached'
The 'cached' decorator is not directly accessible from the 'aiocache' module.
fixImport the 'cached' decorator explicitly: 'from aiocache.decorators import cached'.
ImportError: cannot import name 'SimpleMemoryCache' from 'aiocache'
The 'SimpleMemoryCache' class is not directly accessible from the 'aiocache' module.
fixImport 'SimpleMemoryCache' explicitly: 'from aiocache.backends.memory import SimpleMemoryCache'.
AttributeError: 'cached' object has no attribute '__code__'. Did you mean: '__call__'?
The 'cached' decorator does not preserve the '__code__' attribute of the original function, affecting introspection.
fixAvoid relying on the '__code__' attribute for functions wrapped with the 'cached' decorator.
TypeError: 'cached' object is not callable
The 'cached' decorator was applied incorrectly, possibly missing parentheses.
fixEnsure the 'cached' decorator is applied with parentheses: '@cached()'.
RuntimeError: This event loop is already running
Attempting to run an asyncio event loop that is already running, often in interactive environments like Jupyter notebooks.
fixUse 'await' instead of 'asyncio.run()' in interactive environments to avoid running a new event loop.
Upgrade
Version history
0.12.3latest on PyPI · released Sep 25, 2024
Audit
Dependencies
redisoptionalRequired for the Redis backend. Install with `pip install aiocache[redis]`.
aiomcacheoptionalRequired for the Memcached backend. Install with `pip install aiocache[memcached]`.