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

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",
+]

tigrbl/hook/__init__.py

@@ -0,0 +1,21 @@
+from ..config.constants import HOOK_DECLS_ATTR
+from .decorators import hook_ctx
+from .types import PHASE, HookPhase, PHASES, Ctx, StepFn, HookPredicate
+from .shortcuts import hook, hook_spec
+from ._hook import Hook
+from .hook_spec import HookSpec
+
+__all__ = [
+    "hook_ctx",
+    "HOOK_DECLS_ATTR",
+    "Hook",
+    "PHASE",
+    "HookPhase",
+    "PHASES",
+    "Ctx",
+    "StepFn",
+    "HookPredicate",
+    "hook",
+    "hook_spec",
+    "HookSpec",
+]

tigrbl/hook/_hook.py

@@ -0,0 +1,22 @@
+"""Runtime hook wrapper for Tigrbl v3."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Optional, Union
+
+from .types import HookPhase, StepFn
+
+
+@dataclass(frozen=True, slots=True)
+class Hook:
+    """Concrete hook bound to a phase and one or more ops."""
+
+    phase: HookPhase
+    fn: StepFn
+    ops: Union[str, Iterable[str]]
+    name: Optional[str] = None
+    description: Optional[str] = None
+
+
+__all__ = ["Hook"]

tigrbl/hook/decorators.py

@@ -0,0 +1,28 @@
+"""Hook-related decorators for Tigrbl v3."""
+
+from __future__ import annotations
+
+from typing import Iterable, Union
+
+from ..config.constants import HOOK_DECLS_ATTR
+from ._hook import Hook
+
+
+def hook_ctx(ops: Union[str, Iterable[str]], *, phase: str):
+    """Declare a ctx-only hook for one/many ops at a given phase."""
+
+    def deco(fn):
+        from ..op.decorators import _ensure_cm, _unwrap
+
+        cm = _ensure_cm(fn)
+        f = _unwrap(cm)
+        f.__tigrbl_ctx_only__ = True
+        lst = getattr(f, HOOK_DECLS_ATTR, [])
+        lst.append(Hook(phase=phase, fn=f, ops=ops))
+        setattr(f, HOOK_DECLS_ATTR, lst)
+        return cm
+
+    return deco
+
+
+__all__ = ["hook_ctx", "HOOK_DECLS_ATTR"]

tigrbl/hook/hook_spec.py

@@ -0,0 +1,24 @@
+"""Hook specification for Tigrbl v3."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .types import HookPhase, StepFn, HookPredicate
+
+
+@dataclass(frozen=True, slots=True)
+class HookSpec:
+    phase: HookPhase
+    fn: StepFn
+    order: int = 0
+    when: Optional[HookPredicate] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+
+
+# Backwards compatibility alias
+OpHook = HookSpec
+
+__all__ = ["HookSpec", "OpHook"]

tigrbl/hook/mro_collect.py

@@ -0,0 +1,98 @@
+"""Helpers for collecting ctx-only hooks."""
+
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Any, Callable, Dict, Iterable, Union
+
+from ..runtime.executor import _Ctx
+from ..op.collect import apply_alias
+from ..op.mro_collect import mro_alias_map_for
+from ..op.decorators import _maybe_await, _unwrap
+from .decorators import HOOK_DECLS_ATTR, Hook
+
+logger = logging.getLogger("uvicorn")
+
+
+def _phase_io_key(phase: str) -> str | None:
+    p = str(phase)
+    if p.startswith("PRE_"):
+        return "payload"
+    if p.startswith("POST_"):
+        return "result"
+    if p.startswith("ON_"):
+        return "error"
+    return None
+
+
+def _wrap_ctx_hook(
+    table: type, func: Callable[..., Any], phase: str
+) -> Callable[..., Any]:
+    io_key = _phase_io_key(phase)
+
+    async def hook(
+        value=None, *, db=None, request=None, ctx: Dict[str, Any] | None = None
+    ):
+        ctx = _Ctx.ensure(request=request, db=db, seed=ctx)
+        if io_key is not None and value is not None:
+            ctx[io_key] = value
+        bound = func.__get__(table, table)
+        _ = await _maybe_await(bound(ctx))
+        if io_key is None:
+            return None
+        return ctx.get(io_key, value)
+
+    hook.__name__ = getattr(func, "__name__", "hook")
+    hook.__qualname__ = getattr(func, "__qualname__", hook.__name__)
+    return hook
+
+
+@lru_cache(maxsize=None)
+def _mro_collect_decorated_hooks_cached(
+    table: type, visible_aliases_fs: frozenset[str]
+) -> Dict[str, Dict[str, list[Callable[..., Any]]]]:
+    """Cached helper for :func:`mro_collect_decorated_hooks`."""
+
+    visible_aliases = set(visible_aliases_fs)
+    logger.info("Collecting hooks for %s", table.__name__)
+    mapping: Dict[str, Dict[str, list[Callable[..., Any]]]] = {}
+    aliases = mro_alias_map_for(table)
+
+    def _resolve_ops(spec: Union[str, Iterable[str]]) -> Iterable[str]:
+        if spec == "*":
+            return visible_aliases
+        if isinstance(spec, str):
+            return [spec if spec in visible_aliases else apply_alias(spec, aliases)]
+        out: list[str] = []
+        for x in spec:
+            out.append(x if x in visible_aliases else apply_alias(x, aliases))
+        return out
+
+    for base in reversed(table.__mro__):
+        for name, attr in base.__dict__.items():
+            func = _unwrap(attr)
+            decls: list[Hook] | None = getattr(func, HOOK_DECLS_ATTR, None)
+            if not decls:
+                continue
+            for d in decls:
+                for op in _resolve_ops(d.ops):
+                    if op not in visible_aliases:
+                        continue
+                    ph = d.phase
+                    mapping.setdefault(op, {}).setdefault(ph, []).append(
+                        _wrap_ctx_hook(table, d.fn, ph)
+                    )
+    logger.debug("Collected hooks for aliases: %s", list(mapping.keys()))
+    return mapping
+
+
+def mro_collect_decorated_hooks(
+    table: type, *, visible_aliases: set[str]
+) -> Dict[str, Dict[str, list[Callable[..., Any]]]]:
+    """Collect alias→phase→[hook] declarations across a table's MRO."""
+
+    return _mro_collect_decorated_hooks_cached(table, frozenset(visible_aliases))
+
+
+__all__ = ["mro_collect_decorated_hooks"]

tigrbl/hook/shortcuts.py

@@ -0,0 +1,44 @@
+"""Shortcut helpers for building Hook specs."""
+
+from __future__ import annotations
+
+from typing import Iterable, Union
+
+from .types import HookPhase, HookPredicate, StepFn
+from ._hook import Hook
+from .hook_spec import HookSpec
+
+
+def hook(
+    phase: HookPhase,
+    ops: Union[str, Iterable[str]],
+    fn: StepFn,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Hook:
+    """Build a :class:`Hook` instance."""
+    return Hook(phase=phase, fn=fn, ops=ops, name=name, description=description)
+
+
+def hook_spec(
+    phase: HookPhase,
+    fn: StepFn,
+    *,
+    order: int = 0,
+    when: HookPredicate | None = None,
+    name: str | None = None,
+    description: str | None = None,
+) -> HookSpec:
+    """Build a :class:`HookSpec` instance."""
+    return HookSpec(
+        phase=phase,
+        fn=fn,
+        order=order,
+        when=when,
+        name=name,
+        description=description,
+    )
+
+
+__all__ = ["hook", "hook_spec"]