tigrbl 0.3.0.dev4__py3-none-any.whl → 0.3.2__py3-none-any.whl

tigrbl/engine/plugins.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+
+_loaded = False
+
+
+def load_engine_plugins() -> None:
+    """Discover and load external engine plugins via entry points.
+    Safe and idempotent; does nothing if already loaded.
+    """
+    global _loaded
+    if _loaded:
+        return
+
+    # importlib.metadata API differs across Python versions; support both.
+    eps = None
+    try:
+        from importlib.metadata import entry_points  # Python >= 3.10
+
+        eps = entry_points()
+        # New API: .select(group="tigrbl.engine")
+        selected = (
+            eps.select(group="tigrbl.engine")
+            if hasattr(eps, "select")
+            else eps.get("tigrbl.engine", [])
+        )
+    except Exception:
+        try:
+            from importlib_metadata import entry_points as entry_points_backport
+
+            eps = entry_points_backport()
+            selected = (
+                eps.select(group="tigrbl.engine")
+                if hasattr(eps, "select")
+                else eps.get("tigrbl.engine", [])
+            )
+        except Exception:
+            selected = []
+
+    for ep in selected or []:
+        try:
+            fn = ep.load()
+        except Exception:
+            # Ignore broken entry points; the engine remains unavailable.
+            continue
+        try:
+            fn()  # call plugin's register() to register_engine(kind, build, ...)
+        except Exception:
+            # Defensive: a broken plugin must not crash core import
+            continue
+
+    _loaded = True

tigrbl/engine/registry.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Tuple, Dict
+
+
+# A registration for an engine kind provided by an external (or built-in) package.
+@dataclass
+class EngineRegistration:
+    build: Callable[..., Tuple[Any, Callable[[], Any]]]
+    capabilities: Optional[Callable[[], Any]] = None
+
+
+_registry: Dict[str, EngineRegistration] = {}
+
+
+def register_engine(
+    kind: str,
+    build: Callable[..., Tuple[Any, Callable[[], Any]]],
+    capabilities: Optional[Callable[[], Any]] = None,
+) -> None:
+    """Register an engine kind → (builder, capabilities). Idempotent."""
+    k = (kind or "").strip().lower()
+    if not k:
+        raise ValueError("engine kind must be a non-empty string")
+    if k in _registry:
+        # idempotent registration
+        return
+    _registry[k] = EngineRegistration(build=build, capabilities=capabilities)
+
+
+def get_engine_registration(kind: str) -> Optional[EngineRegistration]:
+    return _registry.get((kind or "").strip().lower())
+
+
+def known_engine_kinds() -> list[str]:
+    return sorted(_registry.keys())

tigrbl/engine/resolver.py

@@ -10,7 +10,6 @@ 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

tigrbl/orm/mixins/upsertable.py

@@ -1,6 +1,8 @@
 # tigrbl/v3/mixins/upsertable.py
 from __future__ import annotations
 
+import warnings
+
 from typing import Any, Mapping, Sequence, Optional, Tuple
 from sqlalchemy import and_, inspect as sa_inspect
 from tigrbl.types import Session
@@ -18,6 +20,11 @@ class Upsertable:
 
     def __init_subclass__(cls, **kw):
         super().__init_subclass__(**kw)
+        warnings.warn(
+            "Upsertable is deprecated and will be removed in a future release.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         cls._install_upsertable_hooks()
 
     @classmethod

tigrbl/response/shortcuts.py

@@ -5,6 +5,7 @@ from pathlib import Path
 import json
 import os
 import mimetypes
+import base64
 
 from ..deps.starlette import (
     JSONResponse,
@@ -16,13 +17,39 @@ from ..deps.starlette import (
     Response,
 )
 
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return base64.b64encode(bytes(value)).decode("ascii")
+    if isinstance(value, Path):
+        return str(value)
+    return str(value)
+
+
 try:
     import orjson as _orjson
 
+    _ORJSON_OPTIONS = (
+        getattr(_orjson, "OPT_NON_STR_KEYS", 0)
+        | getattr(_orjson, "OPT_SERIALIZE_NUMPY", 0)
+        | getattr(_orjson, "OPT_SERIALIZE_BYTES", 0)
+    )
+
     def _dumps(obj: Any) -> bytes:
-        return _orjson.dumps(
-            obj, option=_orjson.OPT_NON_STR_KEYS | _orjson.OPT_SERIALIZE_NUMPY
-        )
+        try:
+            return _orjson.dumps(
+                obj,
+                option=_ORJSON_OPTIONS,
+                default=_json_default,
+            )
+        except TypeError:
+            # Fallback for older orjson builds missing optional flags
+            return json.dumps(
+                obj,
+                separators=(",", ":"),
+                ensure_ascii=False,
+                default=_json_default,
+            ).encode("utf-8")
 except Exception:  # pragma: no cover - fallback
 
     def _dumps(obj: Any) -> bytes:
@@ -30,7 +57,7 @@ except Exception:  # pragma: no cover - fallback
             obj,
             separators=(",", ":"),
             ensure_ascii=False,
-            default=str,
+            default=_json_default,
         ).encode("utf-8")
 
 

tigrbl/runtime/atoms/__init__.py

@@ -23,7 +23,6 @@ RunFn = Callable[[Optional[object], Any], None]
 #:   { (domain, subject): (anchor, runner) }
 REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {}
 
-logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
 
 

tigrbl/runtime/atoms/response/__init__.py

@@ -5,12 +5,14 @@ from ... import events as _ev
 from .template import run as _template
 from .negotiate import run as _negotiate
 from .render import run as _render
+from . import headers_from_payload as _hdr_payload
 
 RunFn = Callable[[Optional[object], Any], Any]
 
 REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
     ("response", "template"): (_ev.OUT_DUMP, _template),
     ("response", "negotiate"): (_ev.OUT_DUMP, _negotiate),
+    ("response", "headers_from_payload"): (_hdr_payload.ANCHOR, _hdr_payload.run),
     ("response", "render"): (_ev.OUT_DUMP, _render),
 }
 

tigrbl/runtime/atoms/response/headers_from_payload.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from ... import events as _ev
+from typing import Mapping
+
+ANCHOR = _ev.OUT_BUILD  # run after payload is prepared, before render
+
+
+def run(_, ctx) -> None:
+    """Mirror fields configured with ``io.header_out`` into HTTP response headers.
+
+    - Does NOT remove fields from the response body (no header-only behavior).
+    - Honors op-specific exposure via ``io.out_verbs``.
+    Complexity: O(#fields in opview).
+    """
+    from tigrbl.response import ResponseHints
+
+    resp = getattr(ctx, "response", None)
+    if resp is None:
+        return
+
+    hints = getattr(resp, "hints", None)
+    if hints is None:
+        hints = ResponseHints()
+        resp.hints = hints
+
+    payload = getattr(resp, "result", None)
+    if payload is None:
+        temp = getattr(ctx, "temp", None)
+        if isinstance(temp, Mapping):
+            payload = temp.get("response_payload")
+    if not isinstance(payload, dict):
+        return
+
+    specs = getattr(ctx, "specs", None)
+    if not isinstance(specs, Mapping):
+        model = getattr(ctx, "model", None)
+        specs = getattr(model, "__tigrbl_cols__", {}) if model is not None else {}
+
+    op = getattr(ctx, "op", None)
+    for field_name, spec in specs.items():
+        io = getattr(spec, "io", None)
+        if not io:
+            continue
+
+        header_name = getattr(io, "header_out", None)
+        if not header_name:
+            continue
+
+        out_verbs = set(getattr(io, "out_verbs", ()) or ())
+        if op not in out_verbs:
+            continue
+
+        if field_name in payload:
+            value = payload[field_name]
+            if value is not None:
+                hints.headers[header_name] = str(value)

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,8 +9,8 @@ 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 +20,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 +49,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 +69,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/schema/decorators.py

@@ -7,7 +7,6 @@ from typing import Dict, Optional
 
 from ..config.constants import TIGRBL_SCHEMA_DECLS_ATTR
 
-logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
 
 

tigrbl/schema/get_schema.py

@@ -5,7 +5,6 @@ from typing import Literal, Optional, Type
 
 from pydantic import BaseModel
 
-logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
 
 

tigrbl/schema/utils.py

@@ -5,7 +5,6 @@ from typing import Any, Dict, List, Type
 
 from pydantic import BaseModel, ConfigDict, Field, RootModel, create_model
 
-logging.getLogger("uvicorn").setLevel(logging.DEBUG)
 logger = logging.getLogger("uvicorn")
 
 

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.
+        """