svc-infra 0.1.600__py3-none-any.whl → 0.1.664__py3-none-any.whl

svc_infra/cache/add.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+"""
+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.
+"""
+
+import logging
+import os
+from typing import Any, Callable, Optional
+
+from svc_infra.cache.backend import DEFAULT_READINESS_TIMEOUT
+from svc_infra.cache.backend import instance as _instance
+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 _derive_settings(
+    url: Optional[str], prefix: Optional[str], version: Optional[str]
+) -> 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)  # type: ignore[misc]
+                on_event("shutdown")(_shutdown)  # type: ignore[misc]
+                register_ok = True
+        except Exception:
+            register_ok = False
+
+    # Mark wired and expose state immediately if desired
+    if hasattr(app, "state"):
+        try:
+            setattr(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

@@ -80,9 +80,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

svc_infra/cache/decorators.py

@@ -98,7 +98,25 @@ def cache_read(
     ttl_val = validate_ttl(ttl)
     template = build_key_template(key)
     namespace = _alias() or ""
-    tags_func = create_tags_function(tags)
+    # Build a tags function that renders any templates against the call kwargs
+    base_tags_func = create_tags_function(tags)
+
+    def tags_func(*_args, **call_kwargs):
+        try:
+            raw = base_tags_func(*_args, **call_kwargs) or []
+            rendered = []
+            for t in raw:
+                if isinstance(t, str) and ("{" in t and "}" in t):
+                    try:
+                        rendered.append(t.format(**call_kwargs))
+                    except Exception:
+                        # Best effort: fall back to original
+                        rendered.append(t)
+                else:
+                    rendered.append(t)
+            return rendered
+        except Exception:
+            return raw if isinstance(raw, list) else []
 
     def _decorator(func: Callable[..., Awaitable[Any]]):
         # Try different cashews cache decorator signatures for compatibility

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/cli/__init__.py

@@ -6,9 +6,13 @@ from svc_infra.cli.cmds import (
     _HELP,
     jobs_app,
     register_alembic,
+    register_docs,
+    register_dx,
     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
@@ -16,20 +20,36 @@ 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)
+# --- 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")
 
-# --- nosql commands ---
-register_mongo(app)
-register_mongo_scaffold(app)
+# --- 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")
 
-# -- observability commands ---
-register_obs(app)
+# -- 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")
 
+# -- sdk commands ---
+register_sdk(app)
+
+# -- docs commands ---
+register_docs(app)
+
 
 def main():
     app()

svc_infra/cli/cmds/__init__.py

@@ -3,18 +3,26 @@ from svc_infra.cli.cmds.db.nosql.mongo.mongo_scaffold_cmds import (
     register as register_mongo_scaffold,
 )
 from svc_infra.cli.cmds.db.sql.alembic_cmds import register as register_alembic
+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.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_obs",
     "jobs_app",
+    "register_sdk",
+    "register_dx",
+    "register_docs",
     "_HELP",
 ]

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

@@ -188,6 +188,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

@@ -127,7 +127,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)

svc_infra/cli/cmds/db/sql/alembic_cmds.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import json
 import os
+from importlib import import_module
 from typing import List, Optional
 
 import typer
@@ -123,7 +125,11 @@ def cmd_current(
 ):
     """Display the current revision for each database."""
     apply_database_url(database_url)
-    core_current(verbose=verbose)
+    result = core_current(verbose=verbose)
+    try:
+        typer.echo(json.dumps(result))
+    except Exception:
+        typer.echo(str(result))
 
 
 def cmd_history(
@@ -188,7 +194,7 @@ def cmd_setup_and_migrate(
     Async vs. sync is inferred from SQL_URL.
     """
     final_pkgs = _find_pkgs(with_payments, discover_packages)
-    core_setup_and_migrate(
+    result = core_setup_and_migrate(
         overwrite_scaffold=overwrite_scaffold,
         create_db_if_missing=create_db_if_missing,
         create_followup_revision=create_followup_revision,
@@ -197,15 +203,78 @@ def cmd_setup_and_migrate(
         discover_packages=final_pkgs or None,
         database_url=database_url,
     )
+    # Echo a concise JSON result so tests and users can introspect outcome
+    try:
+        typer.echo(json.dumps(result))
+    except Exception:
+        # Fallback to plain string if not JSON-serializable for any reason
+        typer.echo(str(result))
 
 
 def register(app: typer.Typer) -> None:
-    app.command("sql-init")(cmd_init)
-    app.command("sql-revision")(cmd_revision)
-    app.command("sql-upgrade")(cmd_upgrade)
-    app.command("sql-downgrade")(cmd_downgrade)
-    app.command("sql-current")(cmd_current)
-    app.command("sql-history")(cmd_history)
-    app.command("sql-stamp")(cmd_stamp)
-    app.command("sql-merge-heads")(cmd_merge_heads)
-    app.command("sql-setup-and-migrate")(cmd_setup_and_migrate)
+    # Register under the 'sql' group app
+    app.command("init")(cmd_init)
+    app.command("revision")(cmd_revision)
+    app.command("upgrade")(cmd_upgrade)
+    # Allow unknown options so users can pass "-1" like Alembic without Click treating it as an option
+    app.command(
+        "downgrade",
+        context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+    )(cmd_downgrade)
+    app.command("current")(cmd_current)
+    app.command("history")(cmd_history)
+    app.command("stamp")(cmd_stamp)
+    app.command("merge-heads")(cmd_merge_heads)
+    app.command("setup-and-migrate")(cmd_setup_and_migrate)
+    app.command("seed")(cmd_seed)
+
+
+def _import_callable(path: str):
+    mod_name, _, fn_name = path.partition(":")
+    if not mod_name or not fn_name:
+        raise typer.BadParameter("Expected format 'module.path:callable'")
+    # Back-compat: after moving tests under tests/unit, allow legacy test module
+    # dotted paths like 'tests.db.sql.test_sql_seed_cli:my_seed'.
+    mod = None
+    unit_mod = None
+    if mod_name.startswith("tests.db."):
+        # Try legacy import first (shim module), then unit module fallback
+        try:
+            mod = import_module(mod_name)
+        except ModuleNotFoundError:
+            pass
+        unit_name = mod_name.replace("tests.db.", "tests.unit.db.", 1)
+        try:
+            unit_mod = import_module(unit_name)
+        except ModuleNotFoundError:
+            unit_mod = None
+        # If both exist, unify shared state where applicable
+        if mod is not None and unit_mod is not None:
+            # Example: tests use a global `called` dict; point legacy to unit
+            try:
+                if hasattr(unit_mod, "called"):
+                    setattr(mod, "called", getattr(unit_mod, "called"))
+            except Exception:
+                pass
+        # If legacy mod missing but unit exists, use unit
+        if mod is None and unit_mod is not None:
+            mod = unit_mod
+    else:
+        mod = import_module(mod_name)
+    fn = getattr(mod, fn_name, None)
+    if not callable(fn):
+        raise typer.BadParameter(f"Callable '{fn_name}' not found in module '{mod_name}'")
+    return fn
+
+
+def cmd_seed(
+    target: str = typer.Argument(..., help="Seed callable path 'module:func'"),
+    database_url: Optional[str] = typer.Option(
+        None,
+        help="Database URL; overrides env for this command.",
+    ),
+):
+    """Run a user-provided seed function to load fixtures/reference data."""
+    apply_database_url(database_url)
+    fn = _import_callable(target)
+    fn()

svc_infra/cli/cmds/db/sql/sql_export_cmds.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from sqlalchemy import text
+
+from svc_infra.db.sql.utils import build_engine
+
+try:  # SQLAlchemy async extras are optional
+    from sqlalchemy.ext.asyncio import AsyncEngine
+except Exception:  # pragma: no cover - fallback when async extras unavailable
+    AsyncEngine = None  # type: ignore[assignment]
+
+
+def export_tenant(
+    table: str = typer.Argument(..., help="Qualified table name to export (e.g., public.items)"),
+    tenant_id: str = typer.Option(..., "--tenant-id", help="Tenant id value to filter by."),
+    tenant_field: str = typer.Option("tenant_id", help="Column name for tenant id filter."),
+    output: Optional[Path] = typer.Option(
+        None, "--output", help="Output file; defaults to stdout."
+    ),
+    limit: Optional[int] = typer.Option(None, help="Max rows to export."),
+    database_url: Optional[str] = typer.Option(
+        None, "--database-url", help="Overrides env SQL_URL for this command."
+    ),
+):
+    """Export rows for a tenant from a given SQL table as JSON array."""
+    if database_url:
+        os.environ["SQL_URL"] = database_url
+
+    url = os.getenv("SQL_URL")
+    if not url:
+        typer.echo("SQL_URL is required (or pass --database-url)", err=True)
+        raise typer.Exit(code=2)
+
+    engine = build_engine(url)
+    rows: list[dict[str, Any]]
+    query = f"SELECT * FROM {table} WHERE {tenant_field} = :tenant_id"
+    if limit and limit > 0:
+        query += " LIMIT :limit"
+
+    params: dict[str, Any] = {"tenant_id": tenant_id}
+    if limit and limit > 0:
+        params["limit"] = int(limit)
+
+    stmt = text(query)
+
+    is_async_engine = AsyncEngine is not None and isinstance(engine, AsyncEngine)
+
+    if is_async_engine:
+        assert AsyncEngine is not None  # for type checkers
+
+        async def _fetch() -> list[dict[str, Any]]:
+            async with engine.connect() as conn:  # type: ignore[call-arg]
+                result = await conn.execute(stmt, params)
+                return [dict(row) for row in result.mappings()]
+
+        rows = asyncio.run(_fetch())
+    else:
+        with engine.connect() as conn:  # type: ignore[attr-defined]
+            result = conn.execute(stmt, params)
+            rows = [dict(row) for row in result.mappings()]
+
+    data = json.dumps(rows, indent=2)
+    if output:
+        output.write_text(data)
+        typer.echo(str(output))
+    else:
+        sys.stdout.write(data)
+
+
+def register(app_root: typer.Typer) -> None:
+    # Attach directly to the provided 'sql' group app
+    app_root.command("export-tenant")(export_tenant)

svc_infra/cli/cmds/db/sql/sql_scaffold_cmds.py

@@ -134,6 +134,6 @@ def cmd_scaffold_schemas(
 
 
 def register(app: typer.Typer) -> None:
-    app.command("sql-scaffold")(cmd_scaffold)
-    app.command("sql-scaffold-models")(cmd_scaffold_models)
-    app.command("sql-scaffold-schemas")(cmd_scaffold_schemas)
+    app.command("scaffold")(cmd_scaffold)
+    app.command("scaffold-models")(cmd_scaffold_models)
+    app.command("scaffold-schemas")(cmd_scaffold_schemas)