svc-infra 0.1.595__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/cache/__init__.py

@@ -5,17 +5,29 @@ This module offers high-level decorators for read/write caching, cache invalidat
 and resource-based cache management.
 """
 
+from .add import add_cache
+
+# Cache instance access for object-oriented usage
+from .backend import get_cache
+
 # Core decorators - main public API
-from .decorators import cached  # alias for cache_read
-from .decorators import mutates  # alias for cache_write
-from .decorators import cache_read, cache_write, init_cache, init_cache_async
+from .decorators import (
+    cache_read,
+    cache_write,
+    cached,  # alias for cache_read
+    init_cache,
+    init_cache_async,
+    mutates,  # alias for cache_write
+)
 
 # Recaching functionality for advanced use cases
 from .recache import RecachePlan, recache
 
 # Resource management for entity-based caching
-from .resources import entity  # legacy alias
-from .resources import resource
+from .resources import (
+    entity,  # legacy alias
+    resource,
+)
 
 __all__ = [
     # Primary decorators developers use
@@ -32,4 +44,8 @@ __all__ = [
     # Resource-based caching
     "resource",
     "entity",
+    # Easy integration helper
+    "add_cache",
+    # Cache instance access
+    "get_cache",
 ]

svc_infra/cache/add.py

@@ -0,0 +1,167 @@
+"""Easy integration helper to wire the cache backend into an ASGI app lifecycle.
+
+Contract:
+- Idempotent: multiple calls are safe; startup/shutdown handlers are registered once.
+- Env-driven defaults: respects CACHE_URL/REDIS_URL, CACHE_PREFIX, CACHE_VERSION, APP_ENV.
+- Lifecycle: registers startup (init + readiness probe) and shutdown (graceful close).
+- Ergonomics: exposes the underlying cache instance at app.state.cache by default.
+
+This does not replace the per-function decorators (`cache_read`, `cache_write`) and
+does not alter existing direct APIs; it simply standardizes initialization and wiring.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Callable
+from typing import Any
+
+from svc_infra.cache.backend import DEFAULT_READINESS_TIMEOUT
+from svc_infra.cache.backend import get_cache as _get_cache
+from svc_infra.cache.backend import setup_cache as _setup_cache
+from svc_infra.cache.backend import shutdown_cache as _shutdown_cache
+from svc_infra.cache.backend import wait_ready as _wait_ready
+
+logger = logging.getLogger(__name__)
+
+
+def _instance() -> Any:
+    """Return the current cache instance.
+
+    This is a thin compatibility shim used by tests and older callers.
+    """
+
+    return _get_cache()
+
+
+def _derive_settings(
+    url: str | None, prefix: str | None, version: str | None
+) -> tuple[str, str, str]:
+    """Derive cache settings from parameters or environment variables.
+
+    Precedence:
+      - explicit function arguments
+      - environment variables (CACHE_URL/REDIS_URL, CACHE_PREFIX, CACHE_VERSION)
+      - sensible defaults (mem://, "svc", "v1")
+    """
+
+    derived_url = url or os.getenv("CACHE_URL") or os.getenv("REDIS_URL") or "mem://"
+    derived_prefix = prefix or os.getenv("CACHE_PREFIX") or "svc"
+    derived_version = version or os.getenv("CACHE_VERSION") or "v1"
+    return derived_url, derived_prefix, derived_version
+
+
+def add_cache(
+    app: Any | None = None,
+    *,
+    url: str | None = None,
+    prefix: str | None = None,
+    version: str | None = None,
+    readiness_timeout: float | None = None,
+    expose_state: bool = True,
+    state_key: str = "cache",
+) -> Callable[[], None]:
+    """Wire cache initialization and lifecycle into the ASGI app.
+
+    If an app is provided, registers startup/shutdown handlers. Otherwise performs
+    immediate initialization (best-effort) without awaiting readiness.
+
+    Returns a no-op shutdown callable for API symmetry with other helpers.
+    """
+
+    # Compute effective settings
+    eff_url, eff_prefix, eff_version = _derive_settings(url, prefix, version)
+
+    # If no app provided, do a simple init and return
+    if app is None:
+        try:
+            _setup_cache(url=eff_url, prefix=eff_prefix, version=eff_version)
+            logger.info(
+                "Cache initialized (no app wiring): backend=%s namespace=%s",
+                eff_url,
+                f"{eff_prefix}:{eff_version}",
+            )
+        except Exception:
+            logger.exception("Cache initialization failed (no app wiring)")
+        return lambda: None
+
+    # Idempotence: avoid duplicate wiring
+    try:
+        state = getattr(app, "state", None)
+        already = bool(getattr(state, "_svc_cache_wired", False))
+    except Exception:
+        state = None
+        already = False
+
+    if already:
+        logger.debug("add_cache: app already wired; skipping re-registration")
+        return lambda: None
+
+    # Define lifecycle handlers
+    async def _startup():
+        _setup_cache(url=eff_url, prefix=eff_prefix, version=eff_version)
+        try:
+            await _wait_ready(timeout=readiness_timeout or DEFAULT_READINESS_TIMEOUT)
+        except Exception:
+            # Bubble up to fail fast on startup; tests and prod prefer visibility
+            logger.exception("Cache readiness probe failed during startup")
+            raise
+        # Expose cache instance for convenience
+        if expose_state and hasattr(app, "state"):
+            try:
+                setattr(app.state, state_key, _instance())
+            except Exception:
+                logger.debug("Unable to expose cache instance on app.state", exc_info=True)
+
+    async def _shutdown():
+        try:
+            await _shutdown_cache()
+        except Exception:
+            # Best-effort; shutdown should not crash the app
+            logger.debug("Cache shutdown encountered errors (ignored)", exc_info=True)
+
+    # Register event handlers when supported
+    register_ok = False
+    try:
+        if hasattr(app, "add_event_handler"):
+            app.add_event_handler("startup", _startup)
+            app.add_event_handler("shutdown", _shutdown)
+            register_ok = True
+    except Exception:
+        register_ok = False
+
+    if not register_ok:
+        # Fallback: attempt FastAPI/Starlette .on_event decorators dynamically
+        try:
+            on_event = getattr(app, "on_event", None)
+            if callable(on_event):
+                on_event("startup")(_startup)
+                on_event("shutdown")(_shutdown)
+                register_ok = True
+        except Exception:
+            register_ok = False
+
+    # Mark wired and expose state immediately if desired
+    if hasattr(app, "state"):
+        try:
+            app.state._svc_cache_wired = True
+            if expose_state and not hasattr(app.state, state_key):
+                setattr(app.state, state_key, _instance())
+        except Exception:
+            pass
+
+    if register_ok:
+        logger.info("Cache wired: url=%s namespace=%s", eff_url, f"{eff_prefix}:{eff_version}")
+    else:
+        # If we cannot register handlers, at least initialize now
+        try:
+            _setup_cache(url=eff_url, prefix=eff_prefix, version=eff_version)
+        except Exception:
+            logger.exception("Cache initialization failed (no event registration)")
+
+    # Return a simple shutdown handle for symmetry with other add_* helpers
+    return lambda: None
+
+
+__all__ = ["add_cache"]

svc_infra/cache/backend.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import logging
-from typing import Optional
 
 from cashews import cache as _cache
 
@@ -42,10 +41,10 @@ def _full_prefix() -> str:
 
 
 def setup_cache(
-    url: Optional[str] = None,
+    url: str | None = None,
     *,
-    prefix: Optional[str] = None,
-    version: Optional[str] = None,
+    prefix: str | None = None,
+    version: str | None = None,
 ):
     """
     Configure Cashews and set a global key prefix for namespacing.
@@ -80,9 +79,12 @@ def setup_cache(
         logger.info(f"Cache version updated to: {_current_version}")
 
     # Setup backend connection
+    # Newer cashews versions require an explicit settings_url; default to in-memory
+    # backend when no URL is provided so acceptance/unit tests work out of the box.
     try:
-        setup_awaitable = _cache.setup(url) if url else _cache.setup()
-        logger.info(f"Cache backend setup initiated with URL: {url or 'default'}")
+        settings_url = url or "mem://"
+        setup_awaitable = _cache.setup(settings_url)
+        logger.info(f"Cache backend setup initiated with URL: {settings_url}")
     except Exception as e:
         logger.error(f"Failed to setup cache backend: {e}")
         raise
@@ -144,7 +146,7 @@ async def shutdown_cache() -> None:
         logger.warning(f"Error during cache shutdown (ignored): {e}")
 
 
-def instance():
+def get_cache():
     """
     Get the underlying cashews cache instance.
 

svc_infra/cache/decorators.py

@@ -7,8 +7,10 @@ invalidating cache on write operations, and managing cache recaching strategies.
 
 from __future__ import annotations
 
+import inspect
 import logging
-from typing import Any, Awaitable, Callable, Iterable, Optional, Union
+from collections.abc import Awaitable, Callable, Iterable
+from typing import Any
 
 from cashews import cache as _cache
 
@@ -16,16 +18,12 @@ from svc_infra.cache.backend import alias as _alias
 from svc_infra.cache.backend import setup_cache as _setup_cache
 from svc_infra.cache.backend import wait_ready as _wait_ready
 
-from .keys import (
-    build_key_template,
-    build_key_variants_renderer,
-    create_tags_function,
-    resolve_tags,
-)
+from .keys import build_key_template, build_key_variants_renderer, resolve_tags
 from .recache import RecachePlan, RecacheSpec, execute_recache, recache
 from .resources import Resource, entity, resource
 from .tags import invalidate_tags
 from .ttl import validate_ttl
+from .utils import validate_cache_key
 
 logger = logging.getLogger(__name__)
 
@@ -67,11 +65,11 @@ async def init_cache_async(
 
 def cache_read(
     *,
-    key: Union[str, tuple[str, ...]],
-    ttl: Optional[int] = None,
-    tags: Optional[Union[Iterable[str], Callable[..., Iterable[str]]]] = None,
-    early_ttl: Optional[int] = None,
-    refresh: Optional[bool] = None,
+    key: str | tuple[str, ...],
+    ttl: int | None = None,
+    tags: Iterable[str] | Callable[..., Iterable[str]] | None = None,
+    early_ttl: int | None = None,
+    refresh: bool | None = None,
 ):
     """
     Cache decorator for read operations with version-resilient key handling.
@@ -98,18 +96,33 @@ def cache_read(
     ttl_val = validate_ttl(ttl)
     template = build_key_template(key)
     namespace = _alias() or ""
-    tags_func = create_tags_function(tags)
+    # Cashews expects `tags` to be an iterable of (template) strings.
+    # If no explicit tags are provided, default to tagging by the key template.
+    # This enables the common pattern:
+    #   @cache_read(key="thing:{id}")
+    #   @cache_write(tags=["thing:{id}"])
+    # where writes invalidate reads without requiring tags on every read.
+    dynamic_tags_func: Callable[..., Iterable[str]] | None = None
+    if tags is None:
+        tags_param: Iterable[str] = (template,)
+    elif callable(tags):
+        # Preserve API surface area, but cashews doesn't accept callables here.
+        # We'll attach tag mappings manually after each call.
+        dynamic_tags_func = tags
+        tags_param = ()
+    else:
+        tags_param = tags
 
     def _decorator(func: Callable[..., Awaitable[Any]]):
         # Try different cashews cache decorator signatures for compatibility
-        cache_kwargs = {"tags": tags_func}
+        cache_kwargs: dict[str, Any] = {"tags": tuple(tags_param)}
         if early_ttl is not None:
             cache_kwargs["early_ttl"] = early_ttl
         if refresh is not None:
             cache_kwargs["refresh"] = refresh
 
         wrapped = None
-        error_msgs = []
+        error_msgs: list[str] = []
 
         # Attempt 1: With prefix parameter (preferred)
         if namespace:
@@ -141,8 +154,47 @@ def cache_read(
                 raise RuntimeError(f"Failed to apply cache decorator: {error_msgs[-1]}") from e
 
         # Attach key variants renderer for cache writers
-        setattr(wrapped, "__svc_key_variants__", build_key_variants_renderer(template))
-        return wrapped
+        wrapped.__svc_key_variants__ = build_key_variants_renderer(template)  # type: ignore[attr-defined]
+
+        # If tags were provided as a callable, populate cashews tag sets manually.
+        # This is best-effort and only affects invalidation-by-tag behavior.
+        if dynamic_tags_func is None:
+            return wrapped
+
+        sig = inspect.signature(func)
+        tag_key_prefix = getattr(_cache, "_tags_key_prefix", "_tag:")
+
+        async def _wrapped_with_dynamic_tags(*args, **kwargs):
+            result = await wrapped(*args, **kwargs)
+
+            try:
+                bound = sig.bind_partial(*args, **kwargs)
+                bound.apply_defaults()
+                ctx = dict(bound.arguments)
+
+                rendered_key = validate_cache_key(template.format(**ctx))
+                full_key = f"{namespace}:{rendered_key}" if namespace else rendered_key
+
+                raw_tags = dynamic_tags_func(*args, **kwargs)
+                for t in list(raw_tags) if raw_tags is not None else []:
+                    tag_val = str(t)
+                    if "{" in tag_val and "}" in tag_val:
+                        try:
+                            tag_val = tag_val.format(**ctx)
+                        except Exception:
+                            pass
+                    if tag_val:
+                        await _cache.set_add(tag_key_prefix + tag_val, full_key, expire=ttl_val)
+            except Exception:
+                # Don't let best-effort tag mapping break cache reads.
+                pass
+
+            return result
+
+        _wrapped_with_dynamic_tags.__svc_key_variants__ = getattr(  # type: ignore[attr-defined]
+            wrapped, "__svc_key_variants__", None
+        )
+        return _wrapped_with_dynamic_tags
 
     return _decorator
 
@@ -156,8 +208,8 @@ cached = cache_read
 
 def cache_write(
     *,
-    tags: Union[Iterable[str], Callable[..., Iterable[str]]],
-    recache: Optional[Iterable[RecacheSpec]] = None,
+    tags: Iterable[str] | Callable[..., Iterable[str]],
+    recache: Iterable[RecacheSpec] | None = None,
     recache_max_concurrency: int = 5,
 ):
     """
@@ -203,7 +255,10 @@ def cache_write(
                 if recache:
                     try:
                         await execute_recache(
-                            recache, *args, max_concurrency=recache_max_concurrency, **kwargs
+                            recache,
+                            *args,
+                            max_concurrency=recache_max_concurrency,
+                            **kwargs,
                         )
                     except Exception as e:
                         logger.error(f"Cache recaching failed: {e}")

svc_infra/cache/demo.py

@@ -83,10 +83,10 @@ async def main():
     # Try to fetch deleted user - should hit DB and get KeyError
     try:
         p4 = await get_user_profile(user_id=uid)
-        print("❌ ERROR: Fetched profile after delete:", p4)
+        print("[ERROR] Fetched profile after delete:", p4)
         print("This shouldn't happen - user should be deleted!")
     except KeyError as e:
-        print(f"✅ User successfully deleted - {e}")
+        print(f"[OK] User successfully deleted - {e}")
         print("Cache invalidation and deletion worked perfectly!")
 
 

svc_infra/cache/keys.py

@@ -6,7 +6,7 @@ with version-resilient handling and namespace support.
 """
 
 import logging
-from typing import Callable, Union
+from collections.abc import Callable
 
 from svc_infra.cache.backend import alias as _alias
 
@@ -15,7 +15,7 @@ from .utils import validate_cache_key
 logger = logging.getLogger(__name__)
 
 
-def build_key_template(key: Union[str, tuple[str, ...]]) -> str:
+def build_key_template(key: str | tuple[str, ...]) -> str:
     """Convert key to template string."""
     if isinstance(key, tuple):
         parts = [part for part in key if part]
@@ -88,12 +88,32 @@ def build_key_variants_renderer(template: str) -> Callable[..., list[str]]:
 
 
 def resolve_tags(tags, *args, **kwargs) -> list[str]:
-    """Resolve tags from static list or callable."""
+    """Resolve tags from static list or callable and render templates with kwargs.
+
+    Supports entries like "thing:{id}" which will be formatted using provided kwargs.
+    Non-string items are passed through as str(). Missing keys are skipped with a warning.
+    """
     try:
+        # 1) Obtain raw tags list
         if callable(tags):
-            result = tags(*args, **kwargs)
-            return list(result) if result is not None else []
-        return list(tags)
+            raw = tags(*args, **kwargs)
+            raw_list = list(raw) if raw is not None else []
+        else:
+            raw_list = list(tags)
+
+        # 2) Render any templates using kwargs
+        rendered: list[str] = []
+        for t in raw_list:
+            try:
+                if isinstance(t, str) and ("{" in t and "}" in t):
+                    rendered.append(t.format(**kwargs))
+                else:
+                    rendered.append(str(t))
+            except KeyError as e:
+                logger.warning(f"Tag template missing key {e} in '{t}'")
+            except Exception as e:
+                logger.warning(f"Failed to render tag '{t}': {e}")
+        return [r for r in rendered if r]
     except Exception as e:
         logger.error(f"Failed to resolve cache tags: {e}")
         return []

svc_infra/cache/recache.py

@@ -7,9 +7,10 @@ including recache plans and execution strategies.
 
 import asyncio
 import logging
+from collections.abc import Awaitable, Callable, Iterable
 from dataclasses import dataclass
 from inspect import Parameter, signature
-from typing import Any, Awaitable, Callable, Iterable, Optional, Union
+from typing import Any
 
 from cashews import cache as _cache
 
@@ -34,19 +35,19 @@ class RecachePlan:
     """
 
     getter: Callable[..., Awaitable[Any]]
-    include: Optional[Iterable[str]] = None
-    rename: Optional[dict[str, str]] = None
-    extra: Optional[dict[str, Any]] = None
-    key: Optional[Union[str, tuple[str, ...]]] = None
+    include: Iterable[str] | None = None
+    rename: dict[str, str] | None = None
+    extra: dict[str, Any] | None = None
+    key: str | tuple[str, ...] | None = None
 
 
 def recache(
     getter: Callable[..., Awaitable[Any]],
     *,
-    include: Optional[Iterable[str]] = None,
-    rename: Optional[dict[str, str]] = None,
-    extra: Optional[dict[str, Any]] = None,
-    key: Optional[Union[str, tuple[str, ...]]] = None,
+    include: Iterable[str] | None = None,
+    rename: dict[str, str] | None = None,
+    extra: dict[str, Any] | None = None,
+    key: str | tuple[str, ...] | None = None,
 ) -> RecachePlan:
     """
     Create a recache plan for cache warming after invalidation.
@@ -64,16 +65,14 @@ def recache(
     return RecachePlan(getter=getter, include=include, rename=rename, extra=extra, key=key)
 
 
-RecacheSpec = Union[
-    Callable[..., Awaitable[Any]],
-    RecachePlan,
-    tuple[Callable[..., Awaitable[Any]], Any],  # Legacy format
-]
+RecacheSpec = (
+    Callable[..., Awaitable[Any]]
+    | RecachePlan
+    | tuple[Callable[..., Awaitable[Any]], Any]  # Legacy format
+)
 
 
-def generate_key_variants(
-    template: Union[str, tuple[str, ...]], params: dict[str, Any]
-) -> list[str]:
+def generate_key_variants(template: str | tuple[str, ...], params: dict[str, Any]) -> list[str]:
     """
     Generate all possible cache key variants for deletion.
 
@@ -165,7 +164,7 @@ def build_getter_kwargs(
     if isinstance(spec, tuple):
         getter, mapping_or_builder = spec
         getter_params = signature(getter).parameters
-        call_kwargs: dict[str, Any] = {}
+        legacy_call_kwargs: dict[str, Any] = {}
 
         if callable(mapping_or_builder):
             try:
@@ -173,7 +172,7 @@ def build_getter_kwargs(
                 if isinstance(produced, dict):
                     for param_name, value in produced.items():
                         if param_name in getter_params:
-                            call_kwargs[param_name] = value
+                            legacy_call_kwargs[param_name] = value
             except Exception as e:
                 logger.warning(f"Recache mapping function failed: {e}")
         elif isinstance(mapping_or_builder, dict):
@@ -182,25 +181,25 @@ def build_getter_kwargs(
                     continue
                 try:
                     if callable(source):
-                        call_kwargs[getter_param] = source(*mut_args, **mut_kwargs)
+                        legacy_call_kwargs[getter_param] = source(*mut_args, **mut_kwargs)
                     elif isinstance(source, str) and source in mut_kwargs:
-                        call_kwargs[getter_param] = mut_kwargs[source]
+                        legacy_call_kwargs[getter_param] = mut_kwargs[source]
                 except Exception as e:
                     logger.warning(f"Recache parameter mapping failed for {getter_param}: {e}")
 
         # Add direct parameter matches
         for param_name in getter_params.keys():
-            if param_name not in call_kwargs and param_name in mut_kwargs:
-                call_kwargs[param_name] = mut_kwargs[param_name]
+            if param_name not in legacy_call_kwargs and param_name in mut_kwargs:
+                legacy_call_kwargs[param_name] = mut_kwargs[param_name]
 
-        call_kwargs = {k: v for k, v in call_kwargs.items() if k in getter_params}
-        return getter, call_kwargs
+        legacy_call_kwargs = {k: v for k, v in legacy_call_kwargs.items() if k in getter_params}
+        return getter, legacy_call_kwargs
 
     # Handle simple getter function
     getter = spec
     getter_params = signature(getter).parameters
-    call_kwargs = {k: v for k, v in mut_kwargs.items() if k in getter_params}
-    return getter, call_kwargs
+    simple_call_kwargs = {k: v for k, v in mut_kwargs.items() if k in getter_params}
+    return getter, simple_call_kwargs
 
 
 async def execute_recache(

svc_infra/cache/resources.py

@@ -8,7 +8,7 @@ with standardized key patterns and tag management.
 import asyncio
 import inspect
 import logging
-from typing import Callable, Optional, Tuple
+from collections.abc import Callable
 
 from cashews import cache as _cache
 
@@ -41,8 +41,8 @@ class Resource:
         *,
         suffix: str,
         ttl: int,
-        key_template: Optional[str] = None,
-        tags_template: Optional[Tuple[str, ...]] = None,
+        key_template: str | None = None,
+        tags_template: tuple[str, ...] | None = None,
         lock: bool = True,
     ):
         """
@@ -73,7 +73,7 @@ class Resource:
     def cache_write(
         self,
         *,
-        recache: Optional[list[tuple[Callable, Callable]]] = None,
+        recache: list[tuple[Callable, Callable]] | None = None,
         recache_max_concurrency: int = 5,
     ):
         """
@@ -157,7 +157,8 @@ class Resource:
                     logger.error(f"Resource recache failed: {e}")
 
             await asyncio.gather(
-                *[_run_single_resource_recache(spec) for spec in specs], return_exceptions=True
+                *[_run_single_resource_recache(spec) for spec in specs],
+                return_exceptions=True,
             )
 
         def _decorator(mutator: Callable):