svc-infra 0.1.589__py3-none-any.whl → 0.1.706__py3-none-any.whl

svc_infra/cache/decorators.py

@@ -7,6 +7,7 @@ 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
 
@@ -16,16 +17,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__)
 
@@ -98,23 +95,40 @@ 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:
             try:
-                wrapped = _cache.cache(ttl_val, template, prefix=namespace, **cache_kwargs)(func)
+                wrapped = _cache.cache(
+                    ttl_val, template, prefix=namespace, **cache_kwargs
+                )(func)
             except TypeError as e:
                 error_msgs.append(f"prefix parameter: {e}")
 
@@ -126,23 +140,72 @@ def cache_read(
                     if namespace and not template.startswith(f"{namespace}:")
                     else template
                 )
-                wrapped = _cache.cache(ttl_val, key_with_namespace, **cache_kwargs)(func)
+                wrapped = _cache.cache(ttl_val, key_with_namespace, **cache_kwargs)(
+                    func
+                )
             except TypeError as e:
                 error_msgs.append(f"embedded namespace: {e}")
 
         # Attempt 3: Minimal fallback
         if wrapped is None:
             try:
-                key_with_namespace = f"{namespace}:{template}" if namespace else template
+                key_with_namespace = (
+                    f"{namespace}:{template}" if namespace else template
+                )
                 wrapped = _cache.cache(ttl_val, key_with_namespace)(func)
             except Exception as e:
                 error_msgs.append(f"minimal fallback: {e}")
                 logger.error(f"All cache decorator attempts failed: {error_msgs}")
-                raise RuntimeError(f"Failed to apply cache decorator: {error_msgs[-1]}") from e
+                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
+
+        # 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
+
+        setattr(
+            _wrapped_with_dynamic_tags,
+            "__svc_key_variants__",
+            getattr(wrapped, "__svc_key_variants__", None),
+        )
+        return _wrapped_with_dynamic_tags
 
     return _decorator
 
@@ -203,7 +266,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

@@ -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

@@ -61,7 +61,9 @@ def recache(
     Returns:
         RecachePlan instance
     """
-    return RecachePlan(getter=getter, include=include, rename=rename, extra=extra, key=key)
+    return RecachePlan(
+        getter=getter, include=include, rename=rename, extra=extra, key=key
+    )
 
 
 RecacheSpec = Union[
@@ -165,7 +167,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 +175,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 +184,31 @@ 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}")
+                    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(
@@ -224,7 +232,9 @@ async def execute_recache(
                         try:
                             await _cache.delete(key_variant)
                         except Exception as e:
-                            logger.debug(f"Failed to delete cache key {key_variant}: {e}")
+                            logger.debug(
+                                f"Failed to delete cache key {key_variant}: {e}"
+                            )
 
                 # Execute the getter to warm the cache
                 await getter(**call_kwargs)
@@ -233,4 +243,6 @@ async def execute_recache(
                 logger.error(f"Recache operation failed: {e}")
 
     # Execute all recache operations concurrently
-    await asyncio.gather(*[_run_single_recache(spec) for spec in specs], return_exceptions=True)
+    await asyncio.gather(
+        *[_run_single_recache(spec) for spec in specs], return_exceptions=True
+    )

svc_infra/cache/resources.py

@@ -63,7 +63,9 @@ class Resource:
 
         def _decorator(func: Callable):
             try:
-                return _cache(ttl=ttl, key=key_template, tags=tags_template, lock=lock)(func)
+                return _cache(ttl=ttl, key=key_template, tags=tags_template, lock=lock)(
+                    func
+                )
             except TypeError:
                 # Fallback for older cashews versions
                 return _cache(ttl=ttl, key=key_template, tags=tags_template)(func)
@@ -97,7 +99,9 @@ class Resource:
             """Delete all cache keys for a specific entity."""
             namespace = _alias() or ""
             namespace_prefix = (
-                f"{namespace}:" if namespace and not namespace.endswith(":") else namespace
+                f"{namespace}:"
+                if namespace and not namespace.endswith(":")
+                else namespace
             )
 
             # Generate candidate keys to delete
@@ -133,7 +137,9 @@ class Resource:
                     # Namespaced wildcard
                     if namespace_prefix:
                         await _maybe_await(
-                            delete_match(f"{namespace_prefix}{entity_name}:*:{entity_id}*")
+                            delete_match(
+                                f"{namespace_prefix}{entity_name}:*:{entity_id}*"
+                            )
                         )
                     # Non-namespaced wildcard
                     await _maybe_await(delete_match(f"{entity_name}:*:{entity_id}*"))
@@ -157,7 +163,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):
@@ -171,7 +178,9 @@ class Resource:
                         # Tag invalidation
                         invalidate_func = getattr(_cache, "invalidate", None)
                         if callable(invalidate_func):
-                            await _maybe_await(invalidate_func(f"{self.name}:{entity_id}"))
+                            await _maybe_await(
+                                invalidate_func(f"{self.name}:{entity_id}")
+                            )
 
                         # Precise key deletion
                         await _delete_entity_keys(self.name, str(entity_id))

svc_infra/cache/tags.py

@@ -28,50 +28,25 @@ async def invalidate_tags(*tags: str) -> int:
     if not tags:
         return 0
 
-    count = 0
+    # Preserve order while de-duplicating.
+    tags_to_delete = list(dict.fromkeys(tags))
 
-    # Strategy 1: Modern cashews invalidate with tags parameter
+    # Cashews supports explicit tag deletion via delete_tags().
     try:
-        result = await _cache.invalidate(tags=list(tags))
-        return int(result) if isinstance(result, int) else len(tags)
-    except (TypeError, AttributeError):
-        pass
+        if hasattr(_cache, "delete_tags"):
+            await _cache.delete_tags(*tags_to_delete)
+            return len(tags_to_delete)
     except Exception as e:
-        logger.warning(f"Modern tag invalidation failed: {e}")
-
-    # Strategy 2: Legacy cashews invalidate with positional args
-    try:
-        result = await _cache.invalidate(*tags)
-        return int(result) if isinstance(result, int) else len(tags)
-    except (TypeError, AttributeError):
-        pass
-    except Exception as e:
-        logger.warning(f"Legacy tag invalidation failed: {e}")
-
-    # Strategy 3: Individual tag methods
-    for tag in tags:
-        for method_name in ("delete_tag", "invalidate_tag", "tag_invalidate"):
-            if hasattr(_cache, method_name):
-                try:
-                    method = getattr(_cache, method_name)
-                    result = await method(tag)
-                    count += int(result) if isinstance(result, int) else 1
-                    break
-                except Exception as e:
-                    logger.debug(f"Tag method {method_name} failed for tag {tag}: {e}")
-                    continue
-        else:
-            # Strategy 4: Pattern matching fallback
-            for method_name in ("delete_match", "invalidate_match", "invalidate"):
-                if hasattr(_cache, method_name):
-                    try:
-                        method = getattr(_cache, method_name)
-                        pattern = f"*{tag}*"
-                        result = await method(pattern)
-                        count += int(result) if isinstance(result, int) else 1
-                        break
-                    except Exception as e:
-                        logger.debug(f"Pattern method {method_name} failed for tag {tag}: {e}")
-                        continue
-
-    return count
+        logger.warning(f"Cache tag invalidation failed: {e}")
+
+    # Fallback: attempt private per-tag deletion when available.
+    deleted = 0
+    for tag in tags_to_delete:
+        try:
+            if hasattr(_cache, "_delete_tag"):
+                await _cache._delete_tag(tag)
+                deleted += 1
+        except Exception as e:
+            logger.debug(f"Tag deletion failed for tag {tag}: {e}")
+
+    return deleted

svc_infra/cache/utils.py

@@ -33,7 +33,9 @@ def stable_hash(*args: Any, **kwargs: Any) -> str:
     """
     try:
         # Use JSON serialization for stable, deterministic output
-        raw = json.dumps([args, kwargs], default=str, sort_keys=True, separators=(",", ":"))
+        raw = json.dumps(
+            [args, kwargs], default=str, sort_keys=True, separators=(",", ":")
+        )
     except (TypeError, ValueError) as e:
         # Fallback to repr if JSON serialization fails
         logger.warning(f"JSON serialization failed for hash input, using repr: {e}")

svc_infra/cli/__init__.py

@@ -4,10 +4,17 @@ import typer
 
 from svc_infra.cli.cmds import (
     _HELP,
+    jobs_app,
     register_alembic,
+    register_db_ops,
+    register_docs,
+    register_dx,
+    register_health,
     register_mongo,
     register_mongo_scaffold,
     register_obs,
+    register_sdk,
+    register_sql_export,
     register_sql_scaffold,
 )
 from svc_infra.cli.foundation.typer_bootstrap import pre_cli
@@ -15,16 +22,53 @@ from svc_infra.cli.foundation.typer_bootstrap import pre_cli
 app = typer.Typer(no_args_is_help=True, add_completion=False, help=_HELP)
 pre_cli(app)
 
-# --- sql commands ---
-register_alembic(app)
-register_sql_scaffold(app)
+# --- db ops group ---
+db_app = typer.Typer(
+    no_args_is_help=True, add_completion=False, help="Database operations"
+)
+register_db_ops(db_app)
+app.add_typer(db_app, name="db")
+
+# --- sql group ---
+sql_app = typer.Typer(no_args_is_help=True, add_completion=False, help="SQL commands")
+register_alembic(sql_app)
+register_sql_scaffold(sql_app)
+register_sql_export(sql_app)
+app.add_typer(sql_app, name="sql")
+
+# --- mongo group ---
+mongo_app = typer.Typer(
+    no_args_is_help=True, add_completion=False, help="MongoDB commands"
+)
+register_mongo(mongo_app)
+register_mongo_scaffold(mongo_app)
+app.add_typer(mongo_app, name="mongo")
+
+# --- health group ---
+health_app = typer.Typer(
+    no_args_is_help=True, add_completion=False, help="Health checks"
+)
+register_health(health_app)
+app.add_typer(health_app, name="health")
+
+# -- obs group ---
+obs_app = typer.Typer(
+    no_args_is_help=True, add_completion=False, help="Observability commands"
+)
+register_obs(obs_app)
+app.add_typer(obs_app, name="obs")
+
+# -- dx commands ---
+register_dx(app)
+
+# -- jobs commands ---
+app.add_typer(jobs_app, name="jobs")
 
-# --- nosql commands ---
-register_mongo(app)
-register_mongo_scaffold(app)
+# -- sdk commands ---
+register_sdk(app)
 
-# -- observability commands ---
-register_obs(app)
+# -- docs commands ---
+register_docs(app)
 
 
 def main():

svc_infra/cli/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

svc_infra/cli/cmds/__init__.py

@@ -1,18 +1,55 @@
-from svc_infra.cli.cmds.db.nosql.mongo.mongo_cmds import register as register_mongo
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+try:
+    from svc_infra.cli.cmds.db.nosql.mongo.mongo_cmds import register as register_mongo
+except ModuleNotFoundError as exc:
+    _mongo_import_error = exc
+
+    def register_mongo(app: typer.Typer) -> None:  # type: ignore[no-redef]
+        def _unavailable() -> Any:
+            raise ModuleNotFoundError(
+                "MongoDB CLI commands require optional dependencies. Install pymongo and motor "
+                "to enable `svc-infra mongo ...` commands."
+            ) from _mongo_import_error
+
+        # Provide a single helpful command instead of failing CLI import.
+        app.command("unavailable")(_unavailable)
+
+
 from svc_infra.cli.cmds.db.nosql.mongo.mongo_scaffold_cmds import (
     register as register_mongo_scaffold,
 )
+from svc_infra.cli.cmds.db.ops_cmds import register as register_db_ops
 from svc_infra.cli.cmds.db.sql.alembic_cmds import register as register_alembic
-from svc_infra.cli.cmds.db.sql.sql_scaffold_cmds import register as register_sql_scaffold
+from svc_infra.cli.cmds.db.sql.sql_export_cmds import register as register_sql_export
+from svc_infra.cli.cmds.db.sql.sql_scaffold_cmds import (
+    register as register_sql_scaffold,
+)
+from svc_infra.cli.cmds.docs.docs_cmds import register as register_docs
+from svc_infra.cli.cmds.dx import register_dx
+from svc_infra.cli.cmds.health.health_cmds import register as register_health
+from svc_infra.cli.cmds.jobs.jobs_cmds import app as jobs_app
 from svc_infra.cli.cmds.obs.obs_cmds import register as register_obs
+from svc_infra.cli.cmds.sdk.sdk_cmds import register as register_sdk
 
 from .help import _HELP
 
 __all__ = [
     "register_alembic",
     "register_sql_scaffold",
+    "register_sql_export",
     "register_mongo",
     "register_mongo_scaffold",
+    "register_db_ops",
     "register_obs",
+    "jobs_app",
+    "register_sdk",
+    "register_dx",
+    "register_docs",
+    "register_health",
     "_HELP",
 ]

svc_infra/cli/cmds/db/nosql/mongo/mongo_cmds.py

@@ -172,7 +172,9 @@ def cmd_ping(
 
     import asyncio
 
-    from svc_infra.db.nosql.mongo.client import acquire_db  # local import to avoid side effects
+    from svc_infra.db.nosql.mongo.client import (
+        acquire_db,
+    )  # local import to avoid side effects
 
     async def _run():
         await init_mongo()
@@ -188,6 +190,7 @@ def cmd_ping(
 
 
 def register(app: typer.Typer) -> None:
-    app.command("mongo-prepare")(cmd_prepare)
-    app.command("mongo-setup-and-prepare")(cmd_setup_and_prepare)
-    app.command("mongo-ping")(cmd_ping)
+    # Attach to 'mongo' group app
+    app.command("prepare")(cmd_prepare)
+    app.command("setup-and-prepare")(cmd_setup_and_prepare)
+    app.command("ping")(cmd_ping)

svc_infra/cli/cmds/db/nosql/mongo/mongo_scaffold_cmds.py

@@ -17,7 +17,9 @@ def cmd_scaffold(
     entity_name: str = typer.Option(
         "Item", help="Entity class name (e.g., User, Member, Product)."
     ),
-    documents_dir: Path = typer.Option(..., help="Directory for Mongo document models."),
+    documents_dir: Path = typer.Option(
+        ..., help="Directory for Mongo document models."
+    ),
     schemas_dir: Path = typer.Option(..., help="Directory for Pydantic CRUD schemas."),
     overwrite: bool = typer.Option(False, help="Overwrite existing files."),
     same_dir: bool = typer.Option(
@@ -127,7 +129,7 @@ def register(app: typer.Typer) -> None:
       • mongo-scaffold-schemas
       • mongo-scaffold-resources
     """
-    app.command("mongo-scaffold")(cmd_scaffold)
-    app.command("mongo-scaffold-documents")(cmd_scaffold_documents)
-    app.command("mongo-scaffold-schemas")(cmd_scaffold_schemas)
-    app.command("mongo-scaffold-resources")(cmd_scaffold_resources)
+    app.command("scaffold")(cmd_scaffold)
+    app.command("scaffold-documents")(cmd_scaffold_documents)
+    app.command("scaffold-schemas")(cmd_scaffold_schemas)
+    app.command("scaffold-resources")(cmd_scaffold_resources)