tigrbl 0.3.0.dev3__py3-none-any.whl → 0.3.1__py3-none-any.whl

tigrbl/runtime/kernel.py

@@ -11,6 +11,7 @@ from types import SimpleNamespace
 from typing import (
     Any,
     Callable,
+    ClassVar,
     Dict,
     Iterable,
     List,
@@ -262,18 +263,27 @@ class Kernel:
     Auto-primed under the hood. Downstream users never touch this.
     """
 
+    _instance: ClassVar["Kernel | None"] = None
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> "Kernel":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
     def __init__(self, atoms: Optional[Sequence[_DiscoveredAtom]] = None):
-        self._atoms_cache: Optional[list[_DiscoveredAtom]] = (
-            list(atoms) if atoms else None
-        )
+        if atoms is None and getattr(self, "_singleton_initialized", False):
+            self._reset(atoms)
+            return
+        self._reset(atoms)
+        if atoms is None:
+            self._singleton_initialized = True
+
+    def _reset(self, atoms: Optional[Sequence[_DiscoveredAtom]] = None) -> None:
+        self._atoms_cache = list(atoms) if atoms else None
         self._specs_cache = _SpecsOnceCache()
-        self._opviews: _WeakMaybeDict[Any, Dict[Tuple[type, str], OpView]] = (
-            _WeakMaybeDict()
-        )
-        self._kernelz_payload: _WeakMaybeDict[Any, Dict[str, Dict[str, List[str]]]] = (
-            _WeakMaybeDict()
-        )
-        self._primed: _WeakMaybeDict[Any, bool] = _WeakMaybeDict()
+        self._opviews = _WeakMaybeDict()
+        self._kernelz_payload = _WeakMaybeDict()
+        self._primed = _WeakMaybeDict()
         self._lock = threading.Lock()
 
     # ——— atoms ———
@@ -396,9 +406,15 @@ class Kernel:
 
     def get_opview(self, app: Any, model: type, alias: str) -> OpView:
         """Return OpView for (model, alias); compile on-demand if missing."""
+        ov_map = self._opviews.get(app)
+        if isinstance(ov_map, dict):
+            ov = ov_map.get((model, alias))
+            if ov is not None:
+                return ov
+
         self.ensure_primed(app)
 
-        ov_map: Dict[Tuple[type, str], OpView] = self._opviews.setdefault(app, {})
+        ov_map = self._opviews.setdefault(app, {})
         ov = ov_map.get((model, alias))
         if ov is not None:
             return ov

tigrbl/runtime/opview.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 from typing import Any, Mapping, Dict
 from types import SimpleNamespace
 
-from .kernel import _default_kernel as K  # single, app-scoped kernel
+from . import kernel as _kernel  # single, app-scoped kernel
 
 
 def _ensure_temp(ctx: Any) -> Dict[str, Any]:
@@ -36,12 +36,14 @@ def opview_from_ctx(ctx: Any):
 
     if app and model and alias:
         # One-kernel-per-app, prime once; raises if not compiled
-        return K.get_opview(app, model, alias)
+        return _kernel._default_kernel.get_opview(app, model, alias)
 
     if alias:
         specs = getattr(ctx, "specs", None)
         if specs is not None:
-            return K._compile_opview_from_specs(specs, SimpleNamespace(alias=alias))
+            return _kernel._default_kernel._compile_opview_from_specs(
+                specs, SimpleNamespace(alias=alias)
+            )
 
     missing = []
     if not alias:

tigrbl/schema/collect.py

@@ -9,6 +9,7 @@ from typing import Dict
 from ..config.constants import TIGRBL_SCHEMA_DECLS_ATTR
 
 from .decorators import _SchemaDecl
+from pydantic import BaseModel, create_model
 
 logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
@@ -20,6 +21,24 @@ def collect_decorated_schemas(model: type) -> Dict[str, Dict[str, type]]:
     logger.info("Collecting decorated schemas for %s", model.__name__)
     out: Dict[str, Dict[str, type]] = {}
 
+    def _promote_schema(schema_cls: type) -> type:
+        if issubclass(schema_cls, BaseModel):
+            return schema_cls
+        annotations = getattr(schema_cls, "__annotations__", {}) or {}
+        fields = {}
+        for name, anno in annotations.items():
+            default = getattr(schema_cls, name, ...)
+            fields[name] = (anno, default)
+        promoted = create_model(  # type: ignore[call-arg]
+            schema_cls.__name__,
+            __base__=BaseModel,
+            **fields,
+        )
+        promoted.__module__ = schema_cls.__module__
+        promoted.__qualname__ = schema_cls.__qualname__
+        promoted.__doc__ = schema_cls.__doc__
+        return promoted
+
     # Explicit registrations (MRO-merged)
     for base in reversed(model.__mro__):
         mapping: Dict[str, Dict[str, type]] = (
@@ -31,7 +50,12 @@ def collect_decorated_schemas(model: type) -> Dict[str, Dict[str, type]]:
             )
         for alias, kinds in mapping.items():
             bucket = out.setdefault(alias, {})
-            bucket.update(kinds or {})
+            bucket.update(
+                {
+                    kind: _promote_schema(schema)
+                    for kind, schema in (kinds or {}).items()
+                }
+            )
 
     # Nested classes with __tigrbl_schema_decl__
     for base in reversed(model.__mro__):
@@ -46,7 +70,7 @@ def collect_decorated_schemas(model: type) -> Dict[str, Dict[str, type]]:
                 )
                 continue
             bucket = out.setdefault(decl.alias, {})
-            bucket[decl.kind] = obj
+            bucket[decl.kind] = _promote_schema(obj)
 
     logger.debug("Collected schema aliases: %s", list(out.keys()))
     return out

tigrbl/session/README.md

@@ -0,0 +1,14 @@
+
+# tigrbl.session
+
+`tigrbl.session` provides the transaction-aware session contract and helpers for Tigrbl:
+
+- `SessionABC`: required interface (native transactions).
+- `SessionSpec`: per-session policy (isolation, read-only, timeouts, retries, etc.).
+- `TigrblSessionBase`: abstract base with guardrails (read-only enforcement, queued add()).
+- `DefaultSession`: delegating wrapper for native driver sessions.
+- `session_ctx` / `read_only_session`: decorators to attach policy at app/api/model/op scopes.
+- `session_spec` / `tx_*` / `readonly`: shortcuts to build policy objects.
+- `wrap_sessionmaker`: helper to adapt provider session factories to Tigrbl sessions.
+
+This module is backend-agnostic and does not import any database libraries.

tigrbl/session/__init__.py

@@ -0,0 +1,28 @@
+from .abc import SessionABC
+from .spec import SessionSpec
+from .base import TigrblSessionBase
+from .default import DefaultSession
+from .decorators import session_ctx, read_only_session
+from .shortcuts import (
+    session_spec,
+    tx_read_committed,
+    tx_repeatable_read,
+    tx_serializable,
+    readonly,
+    wrap_sessionmaker,
+)
+
+__all__ = [
+    "SessionABC",
+    "SessionSpec",
+    "TigrblSessionBase",
+    "DefaultSession",
+    "session_ctx",
+    "read_only_session",
+    "session_spec",
+    "tx_read_committed",
+    "tx_repeatable_read",
+    "tx_serializable",
+    "readonly",
+    "wrap_sessionmaker",
+]

tigrbl/session/abc.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+
+class SessionABC(ABC):
+    """
+    Authoritative Tigrbl session interface.
+
+    All concrete sessions MUST be natively transactional and implement the
+    methods below. This ABC is intentionally minimal and backend-agnostic.
+    """
+
+    # ---- Transactions ----
+    @abstractmethod
+    async def begin(self) -> None:
+        """Open a native transaction for this session."""
+
+    @abstractmethod
+    async def commit(self) -> None:
+        """Commit the current transaction."""
+
+    @abstractmethod
+    async def rollback(self) -> None:
+        """Rollback the current transaction."""
+
+    @abstractmethod
+    def in_transaction(self) -> bool:
+        """Return True iff a transaction is currently open."""
+
+    # ---- CRUD surface ----
+    @abstractmethod
+    async def get(self, model: type, ident: Any) -> Any | None:
+        """Fetch one instance by primary key (model, ident)."""
+
+    @abstractmethod
+    def add(self, obj: Any) -> None:
+        """Stage a new/dirty object for persistence."""
+
+    @abstractmethod
+    async def delete(self, obj: Any) -> None:
+        """Stage an object for deletion."""
+
+    @abstractmethod
+    async def flush(self) -> None:
+        """Flush staged changes to the underlying store (still in TX)."""
+
+    @abstractmethod
+    async def refresh(self, obj: Any) -> None:
+        """Refresh the object from the store (respecting the current TX view)."""
+
+    @abstractmethod
+    async def execute(self, stmt: Any) -> Any:
+        """
+        Execute a backend-native statement.
+
+        The result (if any) SHOULD provide a minimal facade compatible with:
+          - .scalars().all()
+          - .scalar_one()
+        to ease integration with higher-level helpers.
+        """
+
+    # ---- Lifecycle / async marker ----
+    @abstractmethod
+    async def close(self) -> None:
+        """Release underlying resources (connections, cursors, etc.)."""
+
+    @abstractmethod
+    async def run_sync(self, fn: Callable[[Any], Any]) -> Any:
+        """
+        Execute a callback against the underlying native handle.
+
+        Presence of this method also acts as the "async session" marker for code
+        paths that need to distinguish sync-vs-async sessions.
+        """

tigrbl/session/base.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Callable, List, Optional
+
+from .abc import SessionABC
+from .spec import SessionSpec
+
+
+@dataclass
+class TigrblSessionBase(SessionABC):
+    """
+    Common session behavior:
+      - Tracks SessionSpec
+      - Tracks transaction state (_open) and write intent (_dirty)
+      - Queues accidentally-async add() work and resolves on flush/commit
+      - Enforces read-only both on write calls and at commit
+    """
+
+    _spec: Optional[SessionSpec] = None
+
+    _open: bool = field(default=False, init=False)
+    _dirty: bool = field(default=False, init=False)
+    _pending: List[asyncio.Task] = field(default_factory=list, init=False)
+
+    # ---- utilities ----
+    def apply_spec(self, spec: SessionSpec | None) -> None:
+        self._spec = spec
+
+    async def run_sync(self, fn: Callable[[Any], Any]) -> Any:
+        """
+        Default async marker: run the callback against *this* session.
+        Subclasses may override to pass the native handle.
+        """
+        rv = fn(self)
+        if inspect.isawaitable(rv):
+            return await rv
+        return rv
+
+    # ---- TX template methods ----
+    async def begin(self) -> None:
+        await self._tx_begin_impl()
+        self._open = True
+
+    async def commit(self) -> None:
+        # late guard
+        if self._spec and self._spec.read_only and self._dirty:
+            raise RuntimeError("read-only session: writes detected before commit")
+        await self.flush()
+        await self._tx_commit_impl()
+        self._open = False
+        self._dirty = False
+
+    async def rollback(self) -> None:
+        # cancel queued add() tasks
+        for t in self._pending:
+            try:
+                t.cancel()
+            except Exception:
+                pass
+        self._pending.clear()
+        await self._tx_rollback_impl()
+        self._open = False
+        self._dirty = False
+
+    def in_transaction(self) -> bool:
+        return bool(self._open)
+
+    # ---- CRUD surface (template) ----
+    def add(self, obj: Any) -> None:
+        if self._spec and self._spec.read_only:
+            raise RuntimeError("write attempted in read-only session (add)")
+        self._dirty = True
+        rv = self._add_impl(obj)
+        if inspect.isawaitable(rv):
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                asyncio.run(rv)
+            else:
+                self._pending.append(loop.create_task(rv))
+
+    async def delete(self, obj: Any) -> None:
+        if self._spec and self._spec.read_only:
+            raise RuntimeError("write attempted in read-only session (delete)")
+        self._dirty = True
+        await self._delete_impl(obj)
+
+    async def flush(self) -> None:
+        if self._pending:
+            done, _ = await asyncio.wait(
+                self._pending, return_when=asyncio.ALL_COMPLETED
+            )
+            self._pending = []
+            # surface any exception
+            for t in done:
+                _ = t.result()
+        await self._flush_impl()
+
+    async def refresh(self, obj: Any) -> None:
+        await self._refresh_impl(obj)
+
+    async def get(self, model: type, ident: Any) -> Any | None:
+        return await self._get_impl(model, ident)
+
+    async def execute(self, stmt: Any) -> Any:
+        return await self._execute_impl(stmt)
+
+    async def close(self) -> None:
+        for t in self._pending:
+            try:
+                t.cancel()
+            except Exception:
+                pass
+        self._pending = []
+        await self._close_impl()
+
+    # ---- abstract primitives ----
+    async def _tx_begin_impl(self) -> None:  # pragma: no cover - abstract hook
+        raise NotImplementedError
+
+    async def _tx_commit_impl(self) -> None:  # pragma: no cover - abstract hook
+        raise NotImplementedError
+
+    async def _tx_rollback_impl(self) -> None:  # pragma: no cover - abstract hook
+        raise NotImplementedError
+
+    def _add_impl(self, obj: Any) -> Any:  # pragma: no cover - abstract hook
+        raise NotImplementedError
+
+    async def _delete_impl(self, obj: Any) -> None:  # pragma: no cover - abstract hook
+        raise NotImplementedError
+
+    async def _flush_impl(self) -> None:  # pragma: no cover - abstract hook
+        return
+
+    async def _refresh_impl(self, obj: Any) -> None:  # pragma: no cover - abstract hook
+        return
+
+    async def _get_impl(
+        self, model: type, ident: Any
+    ) -> Any | None:  # pragma: no cover
+        raise NotImplementedError
+
+    async def _execute_impl(self, stmt: Any) -> Any:  # pragma: no cover - abstract hook
+        raise NotImplementedError
+
+    async def _close_impl(self) -> None:  # pragma: no cover - abstract hook
+        return

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