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

svc_infra/billing/service.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Callable, Optional
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from .models import Invoice, InvoiceLine, UsageAggregate, UsageEvent
+
+ProviderSyncHook = Callable[[Invoice, list[InvoiceLine]], None]
+
+
+@dataclass
+class BillingService:
+    session: Session
+    tenant_id: str
+    provider_sync: Optional[ProviderSyncHook] = None
+
+    def record_usage(
+        self, *, metric: str, amount: int, at: datetime, idempotency_key: str, metadata: dict | None
+    ) -> str:
+        # Ensure UTC
+        if at.tzinfo is None:
+            at = at.replace(tzinfo=timezone.utc)
+        evt = UsageEvent(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            metric=metric,
+            amount=amount,
+            at_ts=at,
+            idempotency_key=idempotency_key,
+            metadata_json=metadata or {},
+        )
+        self.session.add(evt)
+        self.session.flush()
+        return evt.id
+
+    def aggregate_daily(self, *, metric: str, day_start: datetime) -> None:
+        # Compute [day_start, day_start+1d)
+        next_day = day_start.replace(hour=0, minute=0, second=0, microsecond=0) + timedelta(days=1)
+        total = 0
+        rows = self.session.execute(
+            select(UsageEvent).where(
+                UsageEvent.tenant_id == self.tenant_id,
+                UsageEvent.metric == metric,
+                UsageEvent.at_ts >= day_start,
+                UsageEvent.at_ts < next_day,
+            )
+        ).scalars()
+        for r in rows:
+            total += int(r.amount)
+        # upsert aggregate
+        agg = self.session.execute(
+            select(UsageAggregate).where(
+                UsageAggregate.tenant_id == self.tenant_id,
+                UsageAggregate.metric == metric,
+                UsageAggregate.period_start == day_start,
+                UsageAggregate.granularity == "day",
+            )
+        ).scalar_one_or_none()
+        if agg:
+            agg.total = total
+        else:
+            self.session.add(
+                UsageAggregate(
+                    id=str(uuid.uuid4()),
+                    tenant_id=self.tenant_id,
+                    metric=metric,
+                    period_start=day_start,
+                    granularity="day",
+                    total=total,
+                )
+            )
+
+    def generate_monthly_invoice(
+        self, *, period_start: datetime, period_end: datetime, currency: str
+    ) -> str:
+        # Minimal: sum all daily aggregates and produce one line
+        total = 0
+        rows = self.session.execute(
+            select(UsageAggregate).where(
+                UsageAggregate.tenant_id == self.tenant_id,
+                UsageAggregate.period_start >= period_start,
+                UsageAggregate.period_start < period_end,
+                UsageAggregate.granularity == "day",
+            )
+        ).scalars()
+        for r in rows:
+            total += int(r.total)
+        inv = Invoice(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            period_start=period_start,
+            period_end=period_end,
+            status="created",
+            total_amount=total,
+            currency=currency,
+        )
+        self.session.add(inv)
+        self.session.flush()
+        line = InvoiceLine(
+            id=str(uuid.uuid4()),
+            invoice_id=inv.id,
+            price_id=None,
+            metric=None,
+            quantity=1,
+            amount=total,
+        )
+        self.session.add(line)
+        if self.provider_sync:
+            self.provider_sync(inv, [line])
+        return inv.id

svc_infra/bundled_docs/README.md

@@ -0,0 +1,5 @@
+# Bundled Docs
+
+This directory contains a minimal set of Markdown files that the `svc-infra docs` CLI can fall back to when the project running the CLI doesn't have a local `docs/` directory.
+
+You can add more topics here as needed; each `*.md` file becomes a topic named after its stem (e.g., `getting-started.md` -> `getting-started`).

svc_infra/bundled_docs/__init__.py

@@ -0,0 +1 @@
+# Bundled docs package for zip-safe importlib.resources access

svc_infra/bundled_docs/getting-started.md

@@ -0,0 +1,6 @@
+# Getting Started
+
+Welcome to svc-infra docs. Use `svc-infra docs list` to see topics.
+
+- This content is bundled with the package.
+- If your project doesn't have a local `docs/` folder, you'll still see this.

svc_infra/cache/__init__.py

@@ -5,6 +5,8 @@ This module offers high-level decorators for read/write caching, cache invalidat
 and resource-based cache management.
 """
 
+from .add import add_cache
+
 # Core decorators - main public API
 from .decorators import cached  # alias for cache_read
 from .decorators import mutates  # alias for cache_write
@@ -32,4 +34,6 @@ __all__ = [
     # Resource-based caching
     "resource",
     "entity",
+    # Easy integration helper
+    "add_cache",
 ]

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()