aiocache

aiocache Caching

context7: If the context7 tools are available, resolve and load the full aiocache documentation before making changes:

context7_resolve-library-id: "aiocache"
context7_query-docs: /aio-libs/aiocache

The caching layer is defined in {{cookiecutter.__package_slug}}/services/cache.py. It provides helper functions and a NoOpCache fallback for when caching is disabled.

---

Cache Aliases

Three cache backends are configured by configure_caches():

Alias	Backend	Default TTL
memory	Always in-memory	cache_default_ttl (300s)
persistent	Redis if configured, else memory	cache_persistent_ttl (3600s)
default	Same as memory	cache_persistent_ttl (3600s)*

* Note: set_cached() applies cache_default_ttl only when alias == "memory", so default falls through to cache_persistent_ttl.

---

Using the Helpers

from {{cookiecutter.__package_slug}}.services.cache import get_cached, set_cached, delete_cached, clear_cache

# Get (returns None on miss)
value = await get_cached("user:123")

# Set with default TTL
await set_cached("user:123", user_data)

# Set with custom TTL
await set_cached("user:123", user_data, ttl=600, alias="persistent")

# Delete
await delete_cached("user:123", alias="persistent")

# Clear entire cache
await clear_cache(alias="persistent")

---

Direct Cache Access

For operations not covered by the helpers:

from {{cookiecutter.__package_slug}}.services.cache import get_cache

cache = get_cache("memory")
exists = await cache.exists("key")

---

Cache Decorator

Use @cached to automatically cache function return values. The decorator takes a cache instance (not an alias string) as its first argument. Retrieve the instance with get_cache():

from aiocache import cached
from {{cookiecutter.__package_slug}}.services.cache import get_cache

@cached(get_cache("memory"), ttl=300, key_builder=lambda f, *args, **kwargs: f"user:{args[0]}")
async def get_user(user_id: int) -> dict[str, str] | None:
    # Expensive DB call — cached for 300s
    return await fetch_user_from_db(user_id)