Problem
DefaultBackendProvider always resolves to Redis regardless of which environment variables are set. Setting CACHEKIT_API_KEY has no effect unless you explicitly use @cache.io(), set_default_backend(CachekitIOBackend()), or pass backend=CachekitIOBackend().
This contradicts the "zero config" principle — a user who sets CACHEKIT_API_KEY clearly wants CachekitIO, but @cache.production silently ignores it and tries to connect to Redis.
Current Behavior
import os
os.environ["CACHEKIT_API_KEY"] = "ck_live_..."
@cache.production(ttl=300)
def get_product(product_id: str) -> dict: ...
# ❌ Tries to connect to Redis, not CachekitIO
Proposed Behavior
DefaultBackendProvider.get_backend() should resolve based on env var presence, with this priority:
CACHEKIT_API_KEY set → CachekitIOBackend (managed service gets priority)
CACHEKIT_REDIS_URL or REDIS_URL set → RedisBackend
CACHEKIT_MEMCACHED_SERVERS set → MemcachedBackend
- Nothing set → L1 only (no backend, current zero-config behavior)
import os
os.environ["CACHEKIT_API_KEY"] = "ck_live_..."
@cache.production(ttl=300)
def get_product(product_id: str) -> dict: ...
# ✅ Auto-detects CachekitIO from CACHEKIT_API_KEY
Edge Cases
- Both
CACHEKIT_API_KEY and CACHEKIT_REDIS_URL set: CachekitIO wins (priority 1). Log a warning noting both are configured.
@cache.io() with no CACHEKIT_API_KEY: Should still raise ConfigurationError immediately (fail-fast, current behavior).
- Explicit
backend= parameter: Always takes precedence over auto-detection (current behavior, unchanged).
set_default_backend() called: Always takes precedence over auto-detection (current behavior, unchanged).
Impact
@cache.io() becomes a convenience alias that validates the key upfront, rather than the only way to use CachekitIO
- All presets (
@cache.production, @cache.secure, @cache.minimal, etc.) become genuinely backend-agnostic
- Docs can honestly say "switch backends by changing an environment variable"
Files
src/cachekit/backends/provider.py — DefaultBackendProvider.get_backend()
src/cachekit/cache_handler.py — get_backend_provider()
- Tests for priority resolution and edge cases
Context
Found while writing docs for docs.cachekit.io — the "Switching Backends" section originally claimed you could switch by swapping env vars, but that's not how DefaultBackendProvider works today.
Problem
DefaultBackendProvideralways resolves to Redis regardless of which environment variables are set. SettingCACHEKIT_API_KEYhas no effect unless you explicitly use@cache.io(),set_default_backend(CachekitIOBackend()), or passbackend=CachekitIOBackend().This contradicts the "zero config" principle — a user who sets
CACHEKIT_API_KEYclearly wants CachekitIO, but@cache.productionsilently ignores it and tries to connect to Redis.Current Behavior
Proposed Behavior
DefaultBackendProvider.get_backend()should resolve based on env var presence, with this priority:CACHEKIT_API_KEYset →CachekitIOBackend(managed service gets priority)CACHEKIT_REDIS_URLorREDIS_URLset →RedisBackendCACHEKIT_MEMCACHED_SERVERSset →MemcachedBackendEdge Cases
CACHEKIT_API_KEYandCACHEKIT_REDIS_URLset: CachekitIO wins (priority 1). Log a warning noting both are configured.@cache.io()with noCACHEKIT_API_KEY: Should still raiseConfigurationErrorimmediately (fail-fast, current behavior).backend=parameter: Always takes precedence over auto-detection (current behavior, unchanged).set_default_backend()called: Always takes precedence over auto-detection (current behavior, unchanged).Impact
@cache.io()becomes a convenience alias that validates the key upfront, rather than the only way to use CachekitIO@cache.production,@cache.secure,@cache.minimal, etc.) become genuinely backend-agnosticFiles
src/cachekit/backends/provider.py—DefaultBackendProvider.get_backend()src/cachekit/cache_handler.py—get_backend_provider()Context
Found while writing docs for
docs.cachekit.io— the "Switching Backends" section originally claimed you could switch by swapping env vars, but that's not howDefaultBackendProviderworks today.