tigrbl 0.0.1.dev1__py3-none-any.whl → 0.3.0.dev3__py3-none-any.whl

tigrbl/engine/engine_spec.py

@@ -0,0 +1,261 @@
+# tigrbl/v3/engine/engine_spec.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+from typing import Optional, Mapping, Union, Any, Tuple
+from urllib.parse import urlsplit, urlunsplit
+
+from ._engine import Engine, Provider, SessionFactory
+from .builders import (
+    async_postgres_engine,
+    async_sqlite_engine,
+    blocking_postgres_engine,
+    blocking_sqlite_engine,
+)
+
+# The value stored by @engine_ctx on App/API/Table/Op.
+# Accept either a DSN string, structured mapping, or pre-built objects.
+EngineCfg = Union[str, Mapping[str, object], "EngineSpec", Provider, Engine]
+
+
+@dataclass
+class EngineSpec:
+    """
+    Canonical, normalized engine spec → Provider factory.
+
+    Input comes from @engine_ctx attached to an App/API/Table/Op:
+      • DSN string:
+          "sqlite://:memory:" ,
+          "sqlite:///./file.db" ,
+          "sqlite+aiosqlite:///./file.db" ,
+          "postgresql://user:pwd@host:5432/db" ,
+          "postgresql+asyncpg://user:pwd@host:5432/db"
+      • Mapping (recommended for clarity/portability):
+          {
+            "kind": "sqlite" | "postgres",
+            "async": bool,                 # default False
+            # sqlite:
+            "path": "./file.db",           # file-backed
+            "mode": "memory" | None,       # memory uses StaticPool
+            # postgres:
+            "user": "app", "pwd": "secret",
+            "host": "localhost", "port": 5432, "db": "app_db",
+            "pool_size": 10, "max": 20     # max_overflow (sync) or max_size (async)
+          }
+
+    This class *does not* open connections; call .to_provider() to obtain
+    a lazy Provider that builds (engine, sessionmaker) on first use.
+    """
+
+    # normalized fields
+    kind: Optional[str] = None  # "sqlite" | "postgres"
+    async_: bool = False
+
+    # sqlite
+    path: Optional[str] = None  # file path (None when memory=True)
+    memory: bool = False
+
+    # postgres
+    user: Optional[str] = None
+    pwd: Optional[str] = field(default=None, repr=False)
+    host: Optional[str] = None
+    port: Optional[int] = None
+    name: Optional[str] = None
+    pool_size: int = 10
+    max: int = 20  # max_overflow (sync) or max_size (async)
+
+    # raw passthroughs (for diagnostics)
+    dsn: Optional[str] = None
+    mapping: Optional[Mapping[str, object]] = field(default=None, repr=False)
+
+    def __repr__(self) -> str:  # pragma: no cover - representation logic
+        parts = []
+        for f in fields(self):
+            if not f.repr:
+                continue
+            value = getattr(self, f.name)
+            if f.name == "dsn":
+                value = self._redact_dsn(value)
+            if value is not None:
+                parts.append(f"{f.name}={value!r}")
+        return f"EngineSpec({', '.join(parts)})"
+
+    @staticmethod
+    def _redact_dsn(dsn: Optional[str]) -> Optional[str]:
+        if not dsn:
+            return dsn
+        try:
+            parts = urlsplit(dsn)
+            if parts.password:
+                netloc = parts.netloc.replace(parts.password, "***")
+                return urlunsplit(
+                    (parts.scheme, netloc, parts.path, parts.query, parts.fragment)
+                )
+        except Exception:
+            pass
+        return dsn
+
+    # ---------- parsing / normalization ----------
+
+    @staticmethod
+    def from_any(x: EngineCfg | None) -> Optional["EngineSpec"]:
+        """
+        Parse a DSN or mapping (as attached by @engine_ctx) into an EngineSpec.
+        """
+        if x is None:
+            return None
+
+        if isinstance(x, EngineSpec):
+            return x
+
+        if isinstance(x, Provider):
+            return x.spec
+
+        if isinstance(x, Engine):
+            return x.spec
+
+        # String DSN
+        if isinstance(x, str):
+            s = x.strip()
+            # sqlite memory
+            if s == "sqlite://:memory:" or s.startswith("sqlite+memory://"):
+                return EngineSpec(
+                    kind="sqlite",
+                    async_=s.startswith("sqlite+aiosqlite://"),
+                    memory=True,
+                    dsn=s,
+                )
+            # sqlite async file
+            if s.startswith("sqlite+aiosqlite:///"):
+                return EngineSpec(
+                    kind="sqlite", async_=True, path=s.split(":///")[1], dsn=s
+                )
+            # sqlite sync file
+            if s.startswith("sqlite:///"):
+                return EngineSpec(
+                    kind="sqlite", async_=False, path=s.split(":///")[1], dsn=s
+                )
+            # postgres async
+            if s.startswith("postgresql+asyncpg://"):
+                return EngineSpec(kind="postgres", async_=True, dsn=s)
+            # postgres sync
+            if s.startswith("postgresql://"):
+                return EngineSpec(kind="postgres", async_=False, dsn=s)
+            raise ValueError(f"Unsupported DSN: {s}")
+
+        # Mapping
+        m = x  # type: ignore[assignment]
+
+        # allow a few common aliases for ergonomics
+        def _get_bool(key: str, *aliases: str, default: bool = False) -> bool:
+            for k in (key, *aliases):
+                if k in m:
+                    return bool(m[k])  # type: ignore[index]
+            return default
+
+        def _get_str(
+            key: str, *aliases: str, default: Optional[str] = None
+        ) -> Optional[str]:
+            for k in (key, *aliases):
+                if k in m and m[k] is not None:
+                    return str(m[k])  # type: ignore[index]
+            return default
+
+        def _get_int(
+            key: str, *aliases: str, default: Optional[int] = None
+        ) -> Optional[int]:
+            for k in (key, *aliases):
+                if k in m and m[k] is not None:
+                    return int(m[k])  # type: ignore[index]
+            return default
+
+        k = str(m.get("kind", m.get("engine", ""))).lower()  # type: ignore[index]
+        if k == "sqlite":
+            async_ = _get_bool("async", "async_", default=False)
+            path = _get_str("path")
+            # support either {"mode": "memory"} or {"memory": True} or no path
+            memory = (
+                _get_bool("memory", default=False)
+                or (str(m.get("mode", "")).lower() == "memory")
+                or (path is None)
+            )
+            return EngineSpec(
+                kind="sqlite",
+                async_=async_,
+                path=None if memory else path,
+                memory=memory,
+                mapping=m,
+            )
+
+        if k == "postgres":
+            async_ = _get_bool("async", "async_", default=False)
+            return EngineSpec(
+                kind="postgres",
+                async_=async_,
+                user=_get_str("user"),
+                pwd=_get_str("pwd", "password"),
+                host=_get_str("host"),
+                port=_get_int("port"),
+                name=_get_str("db", "name"),
+                pool_size=_get_int("pool_size", default=10) or 10,
+                max=_get_int("max", "max_overflow", "max_size", default=20) or 20,
+                mapping=m,
+            )
+
+        raise ValueError(f"Unsupported provider kind: {k!r}")
+
+    # ---------- realization ----------
+
+    def build(self) -> Tuple[Any, SessionFactory]:
+        """Construct the engine and sessionmaker for this spec."""
+        if self.kind == "sqlite":
+            if self.memory:
+                if self.async_:
+                    return async_sqlite_engine(path=None)
+                return blocking_sqlite_engine(path=None)
+            if not self.path:
+                raise ValueError("sqlite file requires 'path'")
+            if self.async_:
+                return async_sqlite_engine(path=self.path)
+            return blocking_sqlite_engine(path=self.path)
+
+        if self.kind == "postgres":
+            if self.dsn:
+                if self.async_:
+                    return async_postgres_engine(
+                        dsn=self.dsn,
+                        pool_size=self.pool_size,
+                        max_size=self.max,
+                    )
+                return blocking_postgres_engine(
+                    dsn=self.dsn,
+                    pool_size=self.pool_size,
+                    max_overflow=self.max,
+                )
+
+            kwargs = {
+                "pool_size": self.pool_size,
+            }
+            if self.async_:
+                kwargs["max_size"] = self.max
+            else:
+                kwargs["max_overflow"] = self.max
+            if self.user is not None:
+                kwargs["user"] = self.user
+            if self.pwd is not None:
+                kwargs["pwd"] = self.pwd
+            if self.host is not None:
+                kwargs["host"] = self.host
+            if self.port is not None:
+                kwargs["port"] = self.port
+            if self.name is not None:
+                kwargs["db"] = self.name
+            if self.async_:
+                return async_postgres_engine(**kwargs)
+            return blocking_postgres_engine(**kwargs)
+
+        raise ValueError("EngineSpec has no kind")
+
+    def to_provider(self) -> Provider:
+        """Materialize a lazy :class:`Provider` for this spec."""
+        return Provider(self)

tigrbl/engine/resolver.py

@@ -0,0 +1,224 @@
+# tigrbl/tigrbl/v3/engine/resolver.py
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import threading
+from typing import Any, Callable, Optional
+
+from ._engine import AsyncSession, Engine, Provider, Session
+from .engine_spec import EngineSpec, EngineCfg
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+
+# Registry with strict precedence: op > model > api > app
+_LOCK = threading.RLock()
+_DEFAULT: Optional[Provider] = None
+_API: dict[int, Provider] = {}
+_TAB: dict[Any, Provider] = {}
+_OP: dict[tuple[Any, str], Provider] = {}
+
+
+def _with_class(obj: Any) -> list[Any]:
+    """Return ``obj`` and its class when ``obj`` is an instance.
+
+    This allows resolution to honor providers registered on classes even when
+    an instance is supplied at lookup time.
+    """
+    return [obj] if isinstance(obj, type) else [obj, type(obj)]
+
+
+def _coerce(ctx: Optional[EngineCfg]) -> Optional[Provider]:
+    """
+    Promote an @engine_ctx value to a lazy Provider.
+    """
+    logger.debug("_coerce called with ctx=%r", ctx)
+    if ctx is None:
+        logger.debug("_coerce: ctx is None")
+        return None
+    if isinstance(ctx, Provider):
+        logger.debug("_coerce: ctx is already a Provider")
+        return ctx
+    if isinstance(ctx, Engine):
+        logger.debug("_coerce: ctx is an Engine; returning provider")
+        return ctx.provider
+    if isinstance(ctx, EngineSpec):
+        logger.debug("_coerce: ctx is an EngineSpec; converting to provider")
+        return ctx.to_provider()
+    spec = EngineSpec.from_any(ctx)
+    logger.debug("_coerce: EngineSpec.from_any returned %r", spec)
+    return spec.to_provider() if spec else None
+
+
+# ---- registration -----------------------------------------------------------
+
+
+def set_default(ctx: EngineCfg | None) -> None:
+    """
+    Register the app-level default Provider used when no API/table/op binds.
+    """
+    global _DEFAULT
+    prov = _coerce(ctx)
+    logger.debug("set_default: setting default provider to %r", prov)
+    with _LOCK:
+        _DEFAULT = prov
+
+
+def register_api(api: Any, ctx: EngineCfg | None) -> None:
+    """
+    Register an API-level Provider.
+    """
+    prov = _coerce(ctx)
+    logger.debug("register_api: api=%r coerced provider=%r", api, prov)
+    if prov is None:
+        logger.debug("register_api: no provider; skipping registration")
+        return
+    with _LOCK:
+        _API[id(api)] = prov
+        logger.debug("register_api: registered provider for api id %s", id(api))
+
+
+def register_table(model: Any, ctx: EngineCfg | None) -> None:
+    """
+    Register a table/model-level Provider.
+    """
+    prov = _coerce(ctx)
+    logger.debug("register_table: model=%r coerced provider=%r", model, prov)
+    if prov is None:
+        logger.debug("register_table: no provider; skipping registration")
+        return
+    with _LOCK:
+        _TAB[model] = prov
+        logger.debug("register_table: registered provider for model %r", model)
+
+
+def register_op(model: Any, alias: str, ctx: EngineCfg | None) -> None:
+    """
+    Register an op-level Provider for (model, alias).
+    """
+    prov = _coerce(ctx)
+    logger.debug(
+        "register_op: model=%r alias=%r coerced provider=%r", model, alias, prov
+    )
+    if prov is None:
+        logger.debug("register_op: no provider; skipping registration")
+        return
+    with _LOCK:
+        _OP[(model, alias)] = prov
+        logger.debug(
+            "register_op: registered provider for model %r alias %s", model, alias
+        )
+
+
+# ---- resolution -------------------------------------------------------------
+
+
+def resolve_provider(
+    *,
+    api: Any = None,
+    model: Any = None,
+    op_alias: str | None = None,
+) -> Optional[Provider]:
+    """
+    Resolve the effective Provider using precedence:
+        op > model > api > app(default)
+    """
+    logger.debug(
+        "resolve_provider called with api=%r model=%r op_alias=%r",
+        api,
+        model,
+        op_alias,
+    )
+    with _LOCK:
+        if model is not None and op_alias is not None:
+            logger.debug("resolve_provider: checking op-level provider")
+            for m in _with_class(model):
+                logger.debug(
+                    "resolve_provider: looking for op provider for %r alias %s",
+                    m,
+                    op_alias,
+                )
+                p = _OP.get((m, op_alias))
+                if p:
+                    logger.debug("resolve_provider: found op-level provider %r", p)
+                    return p
+        if model is not None:
+            logger.debug("resolve_provider: checking model-level provider")
+            for m in _with_class(model):
+                logger.debug("resolve_provider: looking for model provider %r", m)
+                p = _TAB.get(m)
+                if p:
+                    logger.debug("resolve_provider: found model-level provider %r", p)
+                    return p
+        if api is not None:
+            logger.debug("resolve_provider: checking api-level provider")
+            for a in _with_class(api):
+                logger.debug("resolve_provider: looking for api provider %r", a)
+                # APIs are keyed by ``id`` to avoid relying on ``__hash__``
+                p = _API.get(id(a))
+                if p:
+                    logger.debug("resolve_provider: found api-level provider %r", p)
+                    return p
+        logger.debug("resolve_provider: returning default provider %r", _DEFAULT)
+        return _DEFAULT
+
+
+SessionT = Session | AsyncSession
+
+
+def acquire(
+    *,
+    api: Any = None,
+    model: Any = None,
+    op_alias: str | None = None,
+) -> tuple[SessionT, Callable[[], None]]:
+    """
+    Acquire a DB session from the resolved Provider.
+
+    Returns:
+        (session, release_fn)
+
+    Raises:
+        RuntimeError: if no Provider can be resolved and no default is set.
+    """
+    logger.debug(
+        "acquire called with api=%r model=%r op_alias=%r", api, model, op_alias
+    )
+    p = resolve_provider(api=api, model=model, op_alias=op_alias)
+    if p is None:
+        logger.debug("acquire: no provider resolved; raising error")
+        raise RuntimeError(
+            f"No database provider configured for op={op_alias} "
+            f"model={getattr(model, '__name__', model)} "
+            f"api={type(api).__name__ if api else None} and no default"
+        )
+    db: SessionT = p.session()
+    logger.debug("acquire: session %r acquired from provider %r", db, p)
+
+    def _release() -> None:
+        logger.debug("_release: attempting to release session %r", db)
+        close = getattr(db, "close", None)
+        if callable(close):
+            try:
+                rv = close()
+                logger.debug("_release: close returned %r", rv)
+                if inspect.isawaitable(rv):
+                    logger.debug("_release: awaiting asynchronous close")
+                    try:
+                        loop = asyncio.get_running_loop()
+                    except RuntimeError:
+                        logger.debug("_release: no running loop; using asyncio.run")
+                        asyncio.run(rv)
+                    else:
+                        logger.debug("_release: scheduling close on running loop")
+                        loop.create_task(rv)
+                # If close is sync, it has already executed
+            except Exception:
+                logger.debug("_release: error during close", exc_info=True)
+                # best-effort close; swallow to avoid masking handler errors
+                pass
+        logger.debug("_release: release complete for session %r", db)
+
+    return db, _release

tigrbl/engine/shortcuts.py

@@ -0,0 +1,216 @@
+# tigrbl/tigrbl/v3/engine/shortcuts.py
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Union
+
+from .engine_spec import EngineSpec
+from ._engine import Provider, Engine
+
+EngineCfg = Union[str, Mapping[str, object]]  # DSN string or structured mapping
+
+
+# ---------------------------------------------------------------------------
+# EngineSpec / Provider / Engine helpers  (ctx builder collapsed into
+# engine_spec)
+# ---------------------------------------------------------------------------
+
+
+def engine_spec(
+    spec: Union[EngineCfg, Mapping[str, Any], str, None] = None, **kw: Any
+) -> EngineSpec:
+    """Build an :class:`EngineSpec` from a DSN string, mapping, or keyword fields."""
+    if spec is None and kw:
+        # Inline the former ctx builder behavior (no double wrap)
+        dsn: Optional[str] = kw.get("dsn")
+        if dsn:
+            spec = dsn
+        else:
+            kind = kw.get("kind")
+            if not kind:
+                raise ValueError(
+                    "Provide spec=<DSN|mapping> or kind=('sqlite'|'postgres') with appropriate fields"
+                )
+
+            async_kw = kw.get("async_")
+            if async_kw is None:
+                async_kw = kw.get("async")
+
+            if kind == "sqlite":
+                path = kw.get("path")
+                mode = kw.get("mode")
+                memory_flag = kw.get("memory")
+                memory = (
+                    (mode == "memory")
+                    or (memory_flag is True)
+                    or (not path and mode != "file")
+                )
+                async_default = True if async_kw is None and memory else False
+                async_ = bool(async_kw) if async_kw is not None else async_default
+                if memory:
+                    spec = {"kind": "sqlite", "async": async_, "mode": "memory"}
+                else:
+                    if not path:
+                        raise ValueError("sqlite file requires 'path'")
+                    spec = {"kind": "sqlite", "async": async_, "path": path}
+
+            elif kind == "postgres":
+                async_ = bool(async_kw) if async_kw is not None else False
+                spec = {
+                    "kind": "postgres",
+                    "async": async_,
+                    "user": kw.get("user", "app"),
+                    "pwd": kw.get("pwd", "secret"),
+                    "host": kw.get("host", "localhost"),
+                    "port": kw.get("port", 5432),
+                    "db": kw.get("name", kw.get("db", "app_db")),
+                    "pool_size": kw.get("pool_size", 10),
+                    "max": kw.get("max", 20),
+                }
+            else:
+                raise ValueError("kind must be 'sqlite' or 'postgres'")
+
+    return EngineSpec.from_any(spec)
+
+
+def prov(
+    spec: Union[EngineSpec, EngineCfg, Mapping[str, Any], str, None] = None, **kw: Any
+) -> Provider:
+    """
+    Get a lazy Provider (engine+sessionmaker).
+    Accepts EngineSpec, EngineCfg (mapping/DSN), or kw fields (collapsed former ctxS).
+    """
+    if isinstance(spec, EngineSpec):
+        return spec.to_provider()
+    return engine_spec(spec, **kw).to_provider()
+
+
+def engine(
+    spec: Union[EngineSpec, EngineCfg, Mapping[str, Any], str, None] = None, **kw: Any
+) -> Engine:
+    """Return an Engine façade for convenience in ad-hoc flows."""
+    if isinstance(spec, EngineSpec):
+        return Engine(spec)
+    return Engine(engine_spec(spec, **kw))
+
+
+# ---------------------------------------------------------------------------
+# Convenience helpers (construct EngineCfg mappings directly; no ctxS needed)
+# ---------------------------------------------------------------------------
+
+
+def sqlite_cfg(
+    path: Optional[str] = None, *, async_: bool = True, memory: Optional[bool] = None
+) -> EngineCfg:
+    return (
+        {"kind": "sqlite", "async": async_, "mode": "memory"}
+        if (memory or path is None)
+        else {"kind": "sqlite", "async": async_, "path": path}
+    )
+
+
+def pg_cfg(
+    *,
+    async_: bool = False,
+    user: str = "app",
+    pwd: str = "secret",
+    host: str = "localhost",
+    port: int = 5432,
+    name: str = "app_db",
+    pool_size: int = 10,
+    max: int = 20,
+) -> EngineCfg:
+    return {
+        "kind": "postgres",
+        "async": async_,
+        "user": user,
+        "pwd": pwd,
+        "host": host,
+        "port": port,
+        "db": name,
+        "pool_size": pool_size,
+        "max": max,
+    }
+
+
+def mem(async_: bool = True) -> EngineCfg:
+    """SQLite in-memory (StaticPool) EngineCfg mapping."""
+    return {"kind": "sqlite", "async": async_, "mode": "memory"}
+
+
+def sqlitef(path: str, *, async_: bool = False) -> EngineCfg:
+    """SQLite file EngineCfg mapping."""
+    return {"kind": "sqlite", "async": async_, "path": path}
+
+
+def pg(**kw: Any) -> EngineCfg:
+    """Postgres EngineCfg; set async_=True for asyncpg."""
+    return pg_cfg(**kw)
+
+
+def pga(**kw: Any) -> EngineCfg:
+    """Async Postgres EngineCfg (asyncpg)."""
+    kw.setdefault("async_", True)
+    return pg_cfg(**kw)
+
+
+def pgs(**kw: Any) -> EngineCfg:
+    """Sync Postgres EngineCfg (psycopg/pg8000 depending on your builders)."""
+    kw.setdefault("async_", False)
+    return pg_cfg(**kw)
+
+
+# ---------------------------------------------------------------------------
+# Provider one-liners
+# ---------------------------------------------------------------------------
+
+
+def provider_sqlite_memory(async_: bool = True) -> Provider:
+    return engine_spec(kind="sqlite", mode="memory", async_=async_).to_provider()
+
+
+def provider_sqlite_file(path: str, async_: bool = False) -> Provider:
+    return engine_spec(kind="sqlite", path=path, async_=async_).to_provider()
+
+
+def provider_postgres(
+    *,
+    async_: bool = False,
+    user: str = "app",
+    pwd: str = "secret",
+    host: str = "localhost",
+    port: int = 5432,
+    name: str = "app_db",
+    pool_size: int = 10,
+    max: int = 20,
+) -> Provider:
+    return engine_spec(
+        kind="postgres",
+        async_=async_,
+        user=user,
+        pwd=pwd,
+        host=host,
+        port=port,
+        name=name,
+        pool_size=pool_size,
+        max=max,
+    ).to_provider()
+
+
+__all__ = [
+    # EngineSpec / Provider / Engine helpers
+    "engine_spec",
+    "prov",
+    "engine",
+    # convenience EngineCfg helpers
+    "sqlite_cfg",
+    "pg_cfg",
+    "mem",
+    "sqlitef",
+    "pg",
+    "pga",
+    "pgs",
+    # direct providers
+    "provider_sqlite_memory",
+    "provider_sqlite_file",
+    "provider_postgres",
+]