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

tigrbl/session/decorators.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+from .spec import SessionSpec, SessionCfg
+
+
+def _normalize(cfg: Optional[SessionCfg] = None, **kw: Any) -> SessionSpec:
+    if cfg is not None and kw:
+        raise ValueError("Pass either a mapping/spec or keyword args, not both")
+    return SessionSpec.from_any(cfg or kw) or SessionSpec()
+
+
+def session_ctx(cfg: Optional[SessionCfg] = None, /, **kw: Any):
+    """
+    Attach a SessionSpec to an App, API, Model/Table, or op handler.
+
+    Precedence is evaluated by the resolver using:
+        op > model > api > app
+    (Resolver is part of the runtime/engine layer and is independent of this decorator.)
+    """
+    spec = _normalize(cfg, **kw)
+
+    def _apply(obj: Any) -> Any:
+        setattr(obj, "__tigrbl_session_ctx__", spec)
+        return obj
+
+    return _apply
+
+
+def read_only_session(obj: Any = None, /, *, isolation: Optional[str] = None):
+    """
+    Convenience decorator for read-only sessions.
+    """
+
+    def _wrap(o: Any) -> Any:
+        setattr(
+            o,
+            "__tigrbl_session_ctx__",
+            SessionSpec(read_only=True, isolation=isolation),
+        )
+        return o
+
+    return _wrap(obj) if obj is not None else _wrap

tigrbl/session/default.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, Optional
+
+from .base import TigrblSessionBase
+from .spec import SessionSpec
+
+
+class DefaultSession(TigrblSessionBase):
+    """
+    Delegating session that wraps an underlying native session object
+    (sync or async) and exposes the Tigrbl Session ABC.
+
+    No third-party imports: we rely on duck-typed methods on the underlying
+    object (begin/commit/rollback, add/delete/flush/refresh/get/execute/close).
+    """
+
+    def __init__(self, underlying: Any, spec: Optional[SessionSpec] = None) -> None:
+        super().__init__(spec)
+        self._u = underlying
+
+    # ---- async marker ----
+    async def run_sync(self, fn: Callable[[Any], Any]) -> Any:
+        rv = fn(self._u)
+        if inspect.isawaitable(rv):
+            return await rv
+        return rv
+
+    # ---- TX primitives ----
+    async def _tx_begin_impl(self) -> None:
+        fn = getattr(self._u, "begin", None)
+        if not callable(fn):
+            raise RuntimeError("underlying session does not support begin()")
+        rv = fn()
+        if inspect.isawaitable(rv):
+            await rv
+
+    async def _tx_commit_impl(self) -> None:
+        fn = getattr(self._u, "commit", None)
+        if not callable(fn):
+            raise RuntimeError("underlying session does not support commit()")
+        rv = fn()
+        if inspect.isawaitable(rv):
+            await rv
+
+    async def _tx_rollback_impl(self) -> None:
+        fn = getattr(self._u, "rollback", None)
+        if not callable(fn):
+            raise RuntimeError("underlying session does not support rollback()")
+        rv = fn()
+        if inspect.isawaitable(rv):
+            await rv
+
+    def in_transaction(self) -> bool:
+        it = getattr(self._u, "in_transaction", None)
+        if callable(it):
+            try:
+                return bool(it())
+            except Exception:
+                pass
+        return super().in_transaction()
+
+    # ---- CRUD primitives ----
+    def _add_impl(self, obj: Any) -> Any:
+        fn = getattr(self._u, "add", None)
+        if not callable(fn):
+            raise NotImplementedError("underlying session does not implement add(obj)")
+        return fn(obj)
+
+    async def _delete_impl(self, obj: Any) -> None:
+        fn = getattr(self._u, "delete", None)
+        if not callable(fn):
+            raise NotImplementedError(
+                "underlying session does not implement delete(obj)"
+            )
+        rv = fn(obj)
+        if inspect.isawaitable(rv):
+            await rv
+
+    async def _flush_impl(self) -> None:
+        fn = getattr(self._u, "flush", None)
+        if callable(fn):
+            rv = fn()
+            if inspect.isawaitable(rv):
+                await rv
+
+    async def _refresh_impl(self, obj: Any) -> None:
+        fn = getattr(self._u, "refresh", None)
+        if callable(fn):
+            rv = fn(obj)
+            if inspect.isawaitable(rv):
+                await rv
+
+    async def _get_impl(self, model: type, ident: Any) -> Any | None:
+        fn = getattr(self._u, "get", None)
+        if not callable(fn):
+            raise NotImplementedError(
+                "underlying session does not implement get(model, ident)"
+            )
+        rv = fn(model, ident)
+        return await rv if inspect.isawaitable(rv) else rv
+
+    async def _execute_impl(self, stmt: Any) -> Any:
+        fn = getattr(self._u, "execute", None)
+        if not callable(fn):
+            raise NotImplementedError(
+                "underlying session does not implement execute(stmt)"
+            )
+        rv = fn(stmt)
+        return await rv if inspect.isawaitable(rv) else rv
+
+    async def _close_impl(self) -> None:
+        fn = getattr(self._u, "close", None)
+        if callable(fn):
+            rv = fn()
+            if inspect.isawaitable(rv):
+                await rv

tigrbl/session/shortcuts.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from .default import DefaultSession
+from .spec import SessionSpec, SessionCfg
+
+
+def session_spec(cfg: SessionCfg = None, /, **kw: Any) -> SessionSpec:
+    """
+    Build a SessionSpec from either a mapping/spec or kwargs.
+    """
+    if cfg is not None and kw:
+        raise ValueError("Provide either a mapping/spec or kwargs, not both")
+    return SessionSpec.from_any(cfg or kw) or SessionSpec()
+
+
+# Isolation presets
+def tx_read_committed(*, read_only: Optional[bool] = None) -> SessionSpec:
+    return SessionSpec(isolation="read_committed", read_only=read_only)
+
+
+def tx_repeatable_read(*, read_only: Optional[bool] = None) -> SessionSpec:
+    return SessionSpec(isolation="repeatable_read", read_only=read_only)
+
+
+def tx_serializable(*, read_only: Optional[bool] = None) -> SessionSpec:
+    return SessionSpec(isolation="serializable", read_only=read_only)
+
+
+def readonly() -> SessionSpec:
+    return SessionSpec(read_only=True)
+
+
+# Provider/sessionmaker wrapper
+def wrap_sessionmaker(
+    maker: Callable[[], Any], spec: SessionSpec
+) -> Callable[[], DefaultSession]:
+    """
+    Wrap any provider's session factory to yield DefaultSession instances that
+    enforce the Tigrbl Session ABC and policy.
+    """
+
+    def _mk() -> DefaultSession:
+        underlying = maker()
+        s = DefaultSession(underlying, spec)
+        s.apply_spec(spec)
+        return s
+
+    return _mk

tigrbl/session/spec.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import Any, Mapping, MutableMapping, Optional, Union
+
+SessionCfg = Union["SessionSpec", Mapping[str, Any], None]
+
+
+@dataclass(frozen=True)
+class SessionSpec:
+    """
+    Per-session policy for Tigrbl sessions.
+
+    These fields are backend-agnostic hints and constraints. Adapters should
+    validate and apply them where supported; critical ones (like isolation and
+    read_only) SHOULD be validated and enforced.
+    """
+
+    # Transaction policy
+    isolation: Optional[str] = (
+        None  # "read_committed" | "repeatable_read" | "snapshot" | "serializable"
+    )
+    read_only: Optional[bool] = None
+    autobegin: Optional[bool] = True
+    expire_on_commit: Optional[bool] = None
+
+    # Retries & backoff
+    retry_on_conflict: Optional[bool] = None
+    max_retries: int = 0
+    backoff_ms: int = 0
+    backoff_jitter: bool = True
+
+    # Timeouts / resources
+    statement_timeout_ms: Optional[int] = None
+    lock_timeout_ms: Optional[int] = None
+    fetch_rows: Optional[int] = None
+    stream_chunk_rows: Optional[int] = None
+
+    # Consistency coordinates
+    min_lsn: Optional[str] = None
+    as_of_ts: Optional[str] = None
+    consistency: Optional[str] = None  # "strong" | "bounded_staleness" | "eventual"
+    staleness_ms: Optional[int] = None
+
+    # Tenancy & security
+    tenant_id: Optional[str] = None
+    role: Optional[str] = None
+    rls_context: Mapping[str, str] = None
+
+    # Observability
+    trace_id: Optional[str] = None
+    query_tag: Optional[str] = None
+    tag: Optional[str] = None
+    tracing_sample: Optional[float] = None
+
+    # Cache / index hints
+    cache_read: Optional[bool] = None
+    cache_write: Optional[bool] = None
+    namespace: Optional[str] = None
+
+    # Data protection / compliance
+    kms_key_alias: Optional[str] = None
+    classification: Optional[str] = None
+    audit: Optional[bool] = None
+
+    # Idempotency & pagination
+    idempotency_key: Optional[str] = None
+    page_snapshot: Optional[str] = None
+
+    def merge(self, higher: "SessionSpec | Mapping[str, Any] | None") -> "SessionSpec":
+        """
+        Overlay another spec on top of this one (non-None fields take precedence).
+        Use to implement op > model > api > app precedence.
+        """
+        if higher is None:
+            return self
+        h = higher if isinstance(higher, SessionSpec) else SessionSpec.from_any(higher)
+        if h is None:
+            return self
+        vals: MutableMapping[str, Any] = {
+            f.name: getattr(self, f.name) for f in fields(SessionSpec)
+        }
+        for f in fields(SessionSpec):
+            hv = getattr(h, f.name)
+            if hv is not None:
+                vals[f.name] = hv
+        return SessionSpec(**vals)  # type: ignore[arg-type]
+
+    def to_kwargs(self) -> dict[str, Any]:
+        """Return only non-None items as a plain dict (adapters can **kwargs this)."""
+        return {
+            f.name: getattr(self, f.name)
+            for f in fields(SessionSpec)
+            if getattr(self, f.name) is not None
+        }
+
+    @staticmethod
+    def from_any(x: SessionCfg) -> Optional["SessionSpec"]:
+        if x is None:
+            return None
+        if isinstance(x, SessionSpec):
+            return x
+        if isinstance(x, Mapping):
+            m = dict(x)
+            # aliases
+            if "readonly" in m and "read_only" not in m:
+                m["read_only"] = bool(m.pop("readonly"))
+            if "iso" in m and "isolation" not in m:
+                m["isolation"] = str(m.pop("iso"))
+            allowed = {f.name for f in fields(SessionSpec)}
+            return SessionSpec(**{k: v for k, v in m.items() if k in allowed})
+        raise TypeError(f"Unsupported SessionSpec input: {type(x)}")

tigrbl/shortcuts.py

@@ -0,0 +1,22 @@
+# tigrbl/tigrbl/v3/shortcuts.py
+from __future__ import annotations
+
+from .app import shortcuts as app_shortcuts
+from .api import shortcuts as api_shortcuts
+from .engine import shortcuts as engine_shortcuts
+from .specs import shortcuts as specs_shortcuts
+from .table import shortcuts as table_shortcuts
+
+from .app.shortcuts import *  # noqa: F401,F403
+from .api.shortcuts import *  # noqa: F401,F403
+from .engine.shortcuts import *  # noqa: F401,F403
+from .specs.shortcuts import *  # noqa: F401,F403
+from .table.shortcuts import *  # noqa: F401,F403
+
+__all__ = [
+    *app_shortcuts.__all__,
+    *api_shortcuts.__all__,
+    *engine_shortcuts.__all__,
+    *specs_shortcuts.__all__,
+    *table_shortcuts.__all__,
+]

tigrbl/specs.py

@@ -0,0 +1,44 @@
+# tigrbl/v3/specs.py
+"""Compatibility layer that re-exports column specs.
+
+Importing from ``tigrbl.specs`` remains supported but the
+implementation now lives under :mod:`tigrbl.column`.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .column import *  # noqa: F401,F403
+from .column import (
+    __all__ as _all,
+    column_spec as _column_spec,
+    field_spec as _field_spec,
+    infer as _infer,
+    io_spec as _io_spec,
+    shortcuts as _shortcuts,
+    storage_spec as _storage_spec,
+)
+
+__all__ = list(_all)
+
+# Allow submodule imports like ``tigrbl.specs.storage_spec``
+__path__: list[str] = []
+_mod = sys.modules[__name__]
+_mod.column_spec = _column_spec
+_mod.field_spec = _field_spec
+_mod.infer = _infer
+_mod.io_spec = _io_spec
+_mod.shortcuts = _shortcuts
+_mod.storage_spec = _storage_spec
+
+sys.modules[f"{__name__}.column_spec"] = _column_spec
+sys.modules[f"{__name__}.field_spec"] = _field_spec
+sys.modules[f"{__name__}.infer"] = _infer
+sys.modules[f"{__name__}.io_spec"] = _io_spec
+sys.modules[f"{__name__}.shortcuts"] = _shortcuts
+sys.modules[f"{__name__}.storage_spec"] = _storage_spec
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

tigrbl/system/__init__.py

@@ -0,0 +1,13 @@
+# tigrbl/v3/system/__init__.py
+"""
+Tigrbl v3 – System/Diagnostics helpers.
+
+- mount_diagnostics(api, *, get_db=None) -> Router
+"""
+
+from __future__ import annotations
+
+from .diagnostics import mount_diagnostics
+from .uvicorn import stop_uvicorn_server
+
+__all__ = ["mount_diagnostics", "stop_uvicorn_server"]

tigrbl/system/diagnostics/__init__.py

@@ -0,0 +1,24 @@
+from ...runtime.kernel import _default_kernel, build_phase_chains
+from .router import mount_diagnostics
+from .methodz import build_methodz_endpoint as _build_methodz_endpoint
+from .hookz import build_hookz_endpoint as _build_hookz_endpoint
+from .kernelz import build_kernelz_endpoint as _build_kernelz_endpoint
+from .utils import (
+    model_iter as _model_iter,
+    opspecs as _opspecs,
+    label_callable as _label_callable,
+    label_hook as _label_hook,
+)
+
+__all__ = [
+    "mount_diagnostics",
+    "_build_methodz_endpoint",
+    "_build_hookz_endpoint",
+    "_build_kernelz_endpoint",
+    "_model_iter",
+    "_opspecs",
+    "_label_callable",
+    "_label_hook",
+    "build_phase_chains",
+    "_default_kernel",
+]

tigrbl/system/diagnostics/compat.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Sequence
+from types import SimpleNamespace
+
+try:
+    from ...types import Router, Request, Depends
+    from fastapi.responses import JSONResponse
+except Exception:  # pragma: no cover
+
+    class Router:  # type: ignore
+        def __init__(self, *a, **kw):
+            self.routes = []
+
+        def add_api_route(
+            self, path: str, endpoint: Callable, methods: Sequence[str], **opts
+        ):
+            self.routes.append((path, methods, endpoint, opts))
+
+    class Request:  # type: ignore
+        def __init__(self, scope=None):
+            self.scope = scope or {}
+            self.state = SimpleNamespace()
+            self.query_params = {}
+
+    class JSONResponse(dict):  # type: ignore
+        def __init__(self, content: Any, status_code: int = 200):
+            super().__init__(content=content, status_code=status_code)
+
+    def Depends(fn: Callable[..., Any]):  # type: ignore
+        return fn

tigrbl/system/diagnostics/healthz.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional
+
+from .compat import Depends, JSONResponse, Request
+from .utils import maybe_execute
+
+logger = logging.getLogger(__name__)
+
+
+def build_healthz_endpoint(dep: Optional[Callable[..., Any]]):
+    """
+    Returns a FastAPI endpoint function for /healthz.
+    If `dep` is provided, it's used as a dependency to supply `db`.
+    Otherwise, we try request.state.db.
+    """
+    if dep is not None:
+
+        async def _healthz(db: Any = Depends(dep)):
+            try:
+                await maybe_execute(db, "SELECT 1")
+                return {"ok": True}
+            except Exception as e:  # pragma: no cover
+                logger.exception("/healthz failed")
+                return JSONResponse({"ok": False, "error": str(e)}, status_code=500)
+
+        return _healthz
+
+    async def _healthz(request: Request):
+        db = getattr(request.state, "db", None)
+        if db is None:
+            return {"ok": True, "warning": "no-db"}
+        try:
+            await maybe_execute(db, "SELECT 1")
+            return {"ok": True}
+        except Exception as e:  # pragma: no cover
+            logger.exception("/healthz failed")
+            return JSONResponse({"ok": False, "error": str(e)}, status_code=500)
+
+    return _healthz

tigrbl/system/diagnostics/hookz.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from types import SimpleNamespace
+
+from ...op.types import PHASES
+
+
+def build_hookz_endpoint(api: Any):
+    cache: Optional[Dict[str, Dict[str, Dict[str, List[str]]]]] = None
+
+    async def _hookz():
+        nonlocal cache
+        """
+        Expose hook execution order for each method.
+
+        Phases appear in runner order; error phases trail.
+        Within each phase, hooks are listed in execution order: global (None) hooks,
+        then method-specific hooks.
+        """
+        if cache is not None:
+            return cache
+
+        from . import _model_iter, _opspecs, _label_callable
+
+        out: Dict[str, Dict[str, Dict[str, List[str]]]] = {}
+        for model in _model_iter(api):
+            mname = getattr(model, "__name__", "Model")
+            hooks_root = getattr(model, "hooks", SimpleNamespace())
+            alias_sources = set()
+            rpc_ns = getattr(model, "rpc", SimpleNamespace())
+            alias_sources.update(getattr(rpc_ns, "__dict__", {}).keys())
+            for sp in _opspecs(model):
+                alias_sources.add(sp.alias)
+
+            model_map: Dict[str, Dict[str, List[str]]] = {}
+            for alias in sorted(alias_sources):
+                alias_ns = getattr(hooks_root, alias, None) or SimpleNamespace()
+                phase_map: Dict[str, List[str]] = {}
+                for ph in PHASES:
+                    steps = list(getattr(alias_ns, ph, []) or [])
+                    if steps:
+                        phase_map[ph] = [_label_callable(fn) for fn in steps]
+                if phase_map:
+                    model_map[alias] = phase_map
+            if model_map:
+                out[mname] = model_map
+        cache = out
+        return cache
+
+    return _hookz

tigrbl/system/diagnostics/kernelz.py

@@ -0,0 +1,20 @@
+"""Diagnostic endpoint exposing kernel phase plans."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...runtime.kernel import _default_kernel as K
+
+
+def build_kernelz_endpoint(api: Any):
+    """Return an async handler that serves the Kernel's cached plan."""
+
+    async def _kernelz():
+        K.ensure_primed(api)
+        return K.kernelz_payload(api)
+
+    return _kernelz
+
+
+__all__ = ["build_kernelz_endpoint"]

tigrbl/system/diagnostics/methodz.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+def build_methodz_endpoint(api: Any):
+    cache: Optional[Dict[str, List[Dict[str, Any]]]] = None
+
+    async def _methodz():
+        nonlocal cache
+        """Ordered, canonical operation list."""
+        if cache is not None:
+            return cache
+
+        from . import _model_iter, _opspecs
+
+        methods: List[Dict[str, Any]] = []
+        for model in _model_iter(api):
+            mname = getattr(model, "__name__", "Model")
+            for sp in _opspecs(model):
+                if not getattr(sp, "expose_rpc", True):
+                    continue
+                methods.append(
+                    {
+                        "method": f"{mname}.{sp.alias}",
+                        "model": mname,
+                        "alias": sp.alias,
+                        "target": sp.target,
+                        "arity": sp.arity,
+                        "persist": sp.persist,
+                        "request_model": getattr(sp, "request_model", None) is not None,
+                        "response_model": getattr(sp, "response_model", None)
+                        is not None,
+                        "routes": bool(getattr(sp, "expose_routes", True)),
+                        "rpc": bool(getattr(sp, "expose_rpc", True)),
+                        "tags": list(getattr(sp, "tags", ()) or (mname,)),
+                    }
+                )
+        methods.sort(key=lambda x: (x["model"], x["alias"]))
+        cache = {"methods": methods}
+        return cache
+
+    return _methodz