Cache Developer Guide
Overview
This guide explains how to add caching to new endpoints, use cache decorators, implement cache invalidation, and follow best practices for cache development.
Adding Caching to Endpoints
Basic Caching
Add the @cached decorator to automatically cache function results:
from app.core.cache.decorator import cached
from app.core.cache.ttl import TTL_LONG
@cached(ttl=TTL_LONG)
async def get_automations():
"""Get all automations."""
# Function implementation
...
Using TTL Presets
Use TTL presets based on data volatility:
from app.core.cache.decorator import cached
from app.core.cache.ttl import TTL_VERY_LONG, TTL_LONG, TTL_MEDIUM, TTL_SHORT
# Very stable data (1 hour)
@cached(ttl=TTL_VERY_LONG)
async def get_areas():
...
# Stable data (30 minutes)
@cached(ttl=TTL_LONG)
async def get_automations():
...
# Moderately stable data (5 minutes)
@cached(ttl=TTL_MEDIUM)
async def get_integrations():
...
# Semi-dynamic data (1 minute)
@cached(ttl=TTL_SHORT)
async def get_entity_state(entity_id: str):
...
Custom TTL
Specify a custom TTL value:
Dynamic TTL
Use a callable function for dynamic TTL based on function parameters:
def get_entities_ttl(args: tuple, kwargs: dict, result: Any) -> int:
"""Return TTL based on lean parameter."""
if kwargs.get("lean", False):
return TTL_LONG # Metadata only, longer TTL
return TTL_SHORT # Includes state, shorter TTL
@cached(ttl=get_entities_ttl)
async def get_entities(lean: bool = False):
"""Get entities with optional lean format."""
...
Custom Key Prefix
Specify a custom key prefix:
Parameter Filtering
Include or exclude specific parameters from the cache key:
# Include only specific parameters
@cached(ttl=TTL_LONG, include_params=["domain", "entity_id"])
async def get_entity(domain: str, entity_id: str, detailed: bool = False):
...
# Exclude specific parameters
@cached(ttl=TTL_LONG, exclude_params=["detailed", "verbose"])
async def get_entities(domain: str, detailed: bool = False, verbose: bool = False):
...
Conditional Caching
Cache only when a condition is met:
def should_cache_entity_state(args: tuple, kwargs: dict, result: Any) -> bool:
"""Only cache if state is not 'unknown' or 'unavailable'."""
if isinstance(result, dict):
state = result.get("state", "")
return state not in ("unknown", "unavailable")
return True
@cached(ttl=TTL_SHORT, condition=should_cache_entity_state)
async def get_entity_state(entity_id: str):
"""Get entity state with conditional caching."""
...
Cache Invalidation
Basic Invalidation
Add @invalidate_cache decorator to invalidate cache on mutations:
from app.core.cache.decorator import invalidate_cache
@invalidate_cache(pattern="automations:*")
async def create_automation(config: dict):
"""Create automation and invalidate cache."""
...
Pattern-Based Invalidation
Use wildcard patterns to invalidate multiple cache entries:
# Invalidate all entity caches
@invalidate_cache(pattern="entities:*")
async def update_entity(entity_id: str, state: dict):
...
# Invalidate specific entity state
@invalidate_cache(pattern="entities:state:id=light.living_room*")
async def turn_on_light(entity_id: str):
...
Multiple Patterns
Invalidate multiple patterns:
@invalidate_cache(
patterns=[
"entities:state:*",
"entities:list:*",
"entities:domain:*"
]
)
async def update_entity(entity_id: str, state: dict):
...
Template-Based Invalidation
Use template variables for dynamic invalidation:
@invalidate_cache(pattern="entities:state:id={entity_id}*")
async def entity_action(entity_id: str, action: str):
"""Invalidate cache for specific entity."""
...
The decorator automatically extracts entity_id from function arguments.
Invalidation Chains
Use pre-configured invalidation chains:
@invalidate_cache(chain="entity_update", template_vars={"entity_id": "entity_id"})
async def update_entity(entity_id: str, state: dict):
"""Use entity_update chain to invalidate related caches."""
...
Available chains:
- entity_update: Invalidates entity state, list, domain summary, and area entities
- automation_update: Invalidates automation config and list
- area_update: Invalidates area list and area entities
- zone_update: Invalidates zone list
- scene_update: Invalidates scene list
- tag_update: Invalidates tag list
- integration_update: Invalidates integration config and list
Conditional Invalidation
Invalidate only when a condition is met:
@invalidate_cache(
pattern="automations:*",
condition=lambda args, kwargs, result: result.get("status") == "success"
)
async def create_automation(config: dict):
"""Only invalidate if operation succeeds."""
...
Hierarchical Invalidation
Hierarchical invalidation is automatic:
# Invalidating "entities:*" also invalidates:
# - entities:state:*
# - entities:list:*
# - entities:domain:*
@invalidate_cache(pattern="entities:*")
async def update_entity(entity_id: str, state: dict):
...
Best Practices
1. Choose Appropriate TTL
- Very Long (1 hour): Very stable data (areas, zones, system config)
- Long (30 minutes): Stable data (automations, scripts, scenes)
- Medium (5 minutes): Moderately stable data (integrations, statistics)
- Short (1 minute): Semi-dynamic data (entity states)
2. Use Conditional Caching
Don't cache error responses or invalid states:
def should_cache(result: Any) -> bool:
"""Only cache successful responses."""
if isinstance(result, dict):
return "error" not in result
return True
@cached(ttl=TTL_LONG, condition=should_cache)
async def get_data():
...
3. Invalidate on Mutations
Always invalidate cache when data is modified:
@invalidate_cache(pattern="entities:*")
async def create_entity(config: dict):
...
@invalidate_cache(pattern="entities:*")
async def update_entity(entity_id: str, state: dict):
...
@invalidate_cache(pattern="entities:*")
async def delete_entity(entity_id: str):
...
4. Use Invalidation Chains
Use pre-configured chains for common operations:
@invalidate_cache(chain="entity_update", template_vars={"entity_id": "entity_id"})
async def entity_action(entity_id: str, action: str):
...
5. Exclude Dynamic Data
Don't cache highly dynamic data:
# Don't cache logbook, history, statistics
# These are explicitly excluded from caching
async def get_logbook():
"""Logbook is not cached - always fresh."""
...
6. Test Cache Behavior
Test cache hit/miss behavior:
import pytest
from app.core.cache.manager import get_cache_manager
@pytest.mark.asyncio
async def test_cache_behavior():
"""Test cache hit/miss behavior."""
manager = await get_cache_manager()
await manager.clear()
# First call: Cache miss
result1 = await get_entity_state("light.living_room")
assert manager.get_statistics()["misses"] == 1
# Second call: Cache hit
result2 = await get_entity_state("light.living_room")
assert manager.get_statistics()["hits"] == 1
Examples
Example 1: Basic Caching
from app.core.cache.decorator import cached
from app.core.cache.ttl import TTL_LONG
@cached(ttl=TTL_LONG)
async def get_automations():
"""Get all automations."""
client = await get_client()
response = await client.get(f"{HA_URL}/api/automation", headers=get_ha_headers())
response.raise_for_status()
return response.json()
Example 2: Conditional Caching
from app.core.cache.decorator import cached
from app.core.cache.ttl import TTL_SHORT
def should_cache_entity_state(args: tuple, kwargs: dict, result: Any) -> bool:
"""Only cache if state is valid."""
if isinstance(result, dict):
state = result.get("state", "")
return state not in ("unknown", "unavailable")
return True
@cached(ttl=TTL_SHORT, condition=should_cache_entity_state)
async def get_entity_state(entity_id: str):
"""Get entity state with conditional caching."""
client = await get_client()
response = await client.get(
f"{HA_URL}/api/states/{entity_id}",
headers=get_ha_headers()
)
response.raise_for_status()
return response.json()
Example 3: Dynamic TTL
from app.core.cache.decorator import cached
from app.core.cache.ttl import TTL_LONG, TTL_SHORT
def get_entities_ttl(args: tuple, kwargs: dict, result: Any) -> int:
"""Return TTL based on lean parameter."""
if kwargs.get("lean", False):
return TTL_LONG # Metadata only
return TTL_SHORT # Includes state
@cached(ttl=get_entities_ttl)
async def get_entities(lean: bool = False):
"""Get entities with dynamic TTL."""
client = await get_client()
response = await client.get(f"{HA_URL}/api/states", headers=get_ha_headers())
response.raise_for_status()
entities = response.json()
if lean:
# Return only metadata
return [{"entity_id": e["entity_id"]} for e in entities]
# Return full data with state
return entities
Example 4: Cache Invalidation
from app.core.cache.decorator import invalidate_cache
@invalidate_cache(pattern="automations:*")
async def create_automation(config: dict):
"""Create automation and invalidate cache."""
client = await get_client()
response = await client.post(
f"{HA_URL}/api/automation",
json=config,
headers=get_ha_headers()
)
response.raise_for_status()
return response.json()
Example 5: Template-Based Invalidation
from app.core.cache.decorator import invalidate_cache
@invalidate_cache(pattern="entities:state:id={entity_id}*")
async def entity_action(entity_id: str, action: str):
"""Perform entity action and invalidate cache."""
client = await get_client()
response = await client.post(
f"{HA_URL}/api/services/{entity_id.split('.')[0]}/{action}",
json={"entity_id": entity_id},
headers=get_ha_headers()
)
response.raise_for_status()
return response.json()
Example 6: Invalidation Chain
from app.core.cache.decorator import invalidate_cache
@invalidate_cache(chain="entity_update", template_vars={"entity_id": "entity_id"})
async def update_entity(entity_id: str, state: dict):
"""Update entity using invalidation chain."""
client = await get_client()
response = await client.post(
f"{HA_URL}/api/states/{entity_id}",
json=state,
headers=get_ha_headers()
)
response.raise_for_status()
return response.json()
Testing Cache Code
Test Cache Hit/Miss
import pytest
from app.core.cache.manager import get_cache_manager
@pytest.mark.asyncio
async def test_cache_hit_miss():
"""Test cache hit and miss behavior."""
manager = await get_cache_manager()
await manager.clear()
# First call: Cache miss
result1 = await get_entity_state("light.living_room")
stats = manager.get_statistics()
assert stats["misses"] == 1
assert stats["hits"] == 0
# Second call: Cache hit
result2 = await get_entity_state("light.living_room")
stats = manager.get_statistics()
assert stats["misses"] == 1
assert stats["hits"] == 1
Test Cache Invalidation
import pytest
from app.core.cache.manager import get_cache_manager
@pytest.mark.asyncio
async def test_cache_invalidation():
"""Test cache invalidation."""
manager = await get_cache_manager()
await manager.clear()
# Cache entity state
state1 = await get_entity_state("light.living_room")
assert await manager.get("entities:state:id=light.living_room") is not None
# Invalidate cache
await entity_action("light.living_room", "turn_off")
# Cache should be invalidated
assert await manager.get("entities:state:id=light.living_room") is None
Test Conditional Caching
import pytest
from app.core.cache.manager import get_cache_manager
@pytest.mark.asyncio
async def test_conditional_caching():
"""Test conditional caching."""
manager = await get_cache_manager()
await manager.clear()
# Cache valid state
state1 = await get_entity_state("light.living_room")
assert await manager.get("entities:state:id=light.living_room") is not None
# Don't cache invalid state
# (Assuming entity returns "unknown" state)
state2 = await get_entity_state("sensor.unknown")
assert await manager.get("entities:state:id=sensor.unknown") is None
Common Patterns
Pattern 1: Read Operations
Pattern 2: Write Operations
@invalidate_cache(pattern="data:*")
async def create_data(config: dict):
"""Write operation - invalidate cache."""
...
Pattern 3: Update Operations
@invalidate_cache(pattern="data:*")
async def update_data(id: str, config: dict):
"""Update operation - invalidate cache."""
...
Pattern 4: Delete Operations
@invalidate_cache(pattern="data:*")
async def delete_data(id: str):
"""Delete operation - invalidate cache."""
...
Troubleshooting
Cache Not Working
- Check if caching is enabled
- Verify decorator is applied correctly
- Check logs for cache errors
- Verify cache key generation
Cache Not Invalidating
- Check invalidation pattern matches cache keys
- Verify decorator is applied to mutation functions
- Check logs for invalidation errors
- Verify hierarchical invalidation is working
Low Hit Rate
- Check TTL values (may be too short)
- Verify cache keys are consistent
- Check if parameters are changing
- Review cache invalidation patterns