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

tigrbl/engine/engine_spec.py

@@ -1,7 +1,7 @@
 # tigrbl/v3/engine/engine_spec.py
 from __future__ import annotations
 
-from dataclasses import dataclass, field, fields
+from dataclasses import dataclass, field
 from typing import Optional, Mapping, Union, Any, Tuple
 from urllib.parse import urlsplit, urlunsplit
 
@@ -14,7 +14,6 @@ from .builders import (
 )
 
 # 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]
 
 
@@ -31,28 +30,21 @@ class EngineSpec:
           "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.
+          {"kind":"sqlite","async":True,"path":"./file.db"}
+          {"kind":"postgres","async":True,"host":"db","db":"app_db",...}
+          {<external kind> ...}  # for plugin engines
     """
 
-    # normalized fields
-    kind: Optional[str] = None  # "sqlite" | "postgres"
+    # normalized
+    kind: Optional[str] = None  # "sqlite" | "postgres" | <external>
     async_: bool = False
 
+    # canonical DSN (optional) and raw mapping (for external engines)
+    dsn: Optional[str] = None
+    mapping: Optional[Mapping[str, object]] = None
+
     # sqlite
-    path: Optional[str] = None  # file path (None when memory=True)
+    path: Optional[str] = None  # file path (None → memory)
     memory: bool = False
 
     # postgres
@@ -64,44 +56,11 @@ class EngineSpec:
     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 ----------
+    # ---------- parsing ----------
 
     @staticmethod
     def from_any(x: EngineCfg | None) -> Optional["EngineSpec"]:
-        """
-        Parse a DSN or mapping (as attached by @engine_ctx) into an EngineSpec.
-        """
+        """Parse DSN/Mapping/Provider/Engine into an :class:`EngineSpec`."""
         if x is None:
             return None
 
@@ -114,39 +73,57 @@ class EngineSpec:
         if isinstance(x, Engine):
             return x.spec
 
-        # String DSN
+        # DSN string
         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:///"):
+            # sqlite async
+            if s.startswith("sqlite+aiosqlite://") or s.startswith("sqlite+aiosqlite:"):
+                path = urlsplit(s).path or ""
+                if s.startswith("sqlite+aiosqlite:////"):
+                    if path.startswith("//"):
+                        path = path[1:]
+                    path = path or None
+                else:
+                    path = path.lstrip("/") or None
+                mem = path in {None, ":memory:", "/:memory:"} or s.endswith(":memory:")
                 return EngineSpec(
-                    kind="sqlite", async_=True, path=s.split(":///")[1], dsn=s
+                    kind="sqlite", async_=True, path=path, memory=mem, dsn=s
                 )
-            # sqlite sync file
-            if s.startswith("sqlite:///"):
+            # sqlite sync
+            if s.startswith("sqlite://") or s.startswith("sqlite:"):
+                # handle sqlite://:memory: and sqlite:///file.db
+                if s.startswith("sqlite://:memory:") or s.endswith(":memory:"):
+                    return EngineSpec(
+                        kind="sqlite", async_=False, path=None, memory=True, dsn=s
+                    )
+                # Take the path part after scheme; urlsplit handles both sqlite:// and sqlite:/// forms
+                p = urlsplit(s).path or ""
+                if s.startswith("sqlite:////"):
+                    if p.startswith("//"):
+                        p = p[1:]
+                    p = p or None
+                else:
+                    p = p.lstrip("/") or None
+                mem = p is None
                 return EngineSpec(
-                    kind="sqlite", async_=False, path=s.split(":///")[1], dsn=s
+                    kind="sqlite", async_=False, path=p, memory=mem, dsn=s
                 )
+
             # postgres async
-            if s.startswith("postgresql+asyncpg://"):
+            if s.startswith("postgresql+asyncpg://") or s.startswith(
+                "postgres+asyncpg://"
+            ):
                 return EngineSpec(kind="postgres", async_=True, dsn=s)
             # postgres sync
-            if s.startswith("postgresql://"):
+            if s.startswith("postgresql://") or s.startswith("postgres://"):
                 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
+        # Helpers
         def _get_bool(key: str, *aliases: str, default: bool = False) -> bool:
             for k in (key, *aliases):
                 if k in m:
@@ -166,14 +143,16 @@ class EngineSpec:
         ) -> Optional[int]:
             for k in (key, *aliases):
                 if k in m and m[k] is not None:
-                    return int(m[k])  # type: ignore[index]
+                    try:
+                        return int(m[k])  # type: ignore[index]
+                    except Exception:
+                        return default
             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")
@@ -182,8 +161,9 @@ class EngineSpec:
             return EngineSpec(
                 kind="sqlite",
                 async_=async_,
-                path=None if memory else path,
+                path=path,
                 memory=memory,
+                dsn=_get_str("dsn", "url"),
                 mapping=m,
             )
 
@@ -199,10 +179,17 @@ class EngineSpec:
                 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,
+                dsn=_get_str("dsn", "url"),
                 mapping=m,
             )
 
-        raise ValueError(f"Unsupported provider kind: {k!r}")
+        # External / unknown kinds – keep mapping and defer to registry at build()
+        return EngineSpec(
+            kind=k or None,
+            async_=_get_bool("async", "async_", default=False),
+            dsn=_get_str("dsn", "url"),
+            mapping=m,
+        )
 
     # ---------- realization ----------
 
@@ -222,40 +209,147 @@ class EngineSpec:
         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,
+                    return async_postgres_engine(dsn=self.dsn)
+                return blocking_postgres_engine(dsn=self.dsn)
+            # keyword build
+            kwargs: dict[str, Any] = {
+                "user": self.user or "app",
+                "host": self.host or "localhost",
+                "port": self.port or 5432,
+                "db": self.name or "app_db",
+                "pool_size": int(self.pool_size or 10),
             }
-            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_:
+                kwargs["max_size"] = int(self.max or 20)
                 return async_postgres_engine(**kwargs)
-            return blocking_postgres_engine(**kwargs)
+            else:
+                kwargs["max_overflow"] = int(self.max or 20)
+                return blocking_postgres_engine(**kwargs)
+
+        # External/registered engines
+        try:
+            from .plugins import load_engine_plugins
+            from .registry import get_engine_registration, known_engine_kinds
+
+            load_engine_plugins()
+            reg = get_engine_registration(self.kind or "")
+        except Exception:
+            reg = None
+        if reg:
+            mapping = self.mapping or {}
+            return reg.build(mapping=mapping, spec=self, dsn=self.dsn)
+
+        # No registration found: helpful error
+        try:
+            from .registry import known_engine_kinds  # re-import defensive
+
+            kinds = ", ".join(known_engine_kinds()) or "(none)"
+        except Exception:
+            kinds = "(unknown)"
+        raise RuntimeError(
+            f"Unknown or unavailable engine kind '{self.kind}'. Installed engine kinds: {kinds}. "
+            f"If this is an optional extension, install its package (e.g., 'pip install tigrbl_engine_{self.kind}')."
+        )
+
+    def supports(self) -> dict[str, Any]:
+        """Return capability dictionary for this engine spec.
+        For external kinds, consult the plugin registry if available.
+        """
+        # Built-ins
+        if self.kind == "sqlite":
+            try:
+                from .capabilities import sqlite_capabilities
+
+                return sqlite_capabilities(async_=self.async_, memory=self.memory)
+            except Exception:
+                pass
+        if self.kind == "postgres":
+            try:
+                from .capabilities import postgres_capabilities
+
+                return postgres_capabilities(async_=self.async_)
+            except Exception:
+                pass
+        # External/registered engines
+        try:
+            from .plugins import load_engine_plugins
+            from .registry import get_engine_registration
 
-        raise ValueError("EngineSpec has no kind")
+            load_engine_plugins()
+            reg = get_engine_registration(self.kind or "")
+        except Exception:
+            reg = None
+        if reg and getattr(reg, "capabilities", None):
+            try:
+                # Try flexible signature: capabilities(spec=..., mapping=...)
+                return reg.capabilities(spec=self, mapping=self.mapping)
+            except TypeError:
+                try:
+                    return reg.capabilities()
+                except Exception:
+                    pass
+            except Exception:
+                pass
+        # Fallback minimal shape
+        return {
+            "transactional": False,
+            "async_native": bool(self.async_),
+            "isolation_levels": set(),
+            "read_only_enforced": False,
+            "engine": self.kind or "unknown",
+        }
 
     def to_provider(self) -> Provider:
         """Materialize a lazy :class:`Provider` for this spec."""
         return Provider(self)
+
+    def __repr__(self) -> str:  # pragma: no cover - deterministic output
+        def _redact_dsn(dsn: Optional[str]) -> Optional[str]:
+            if not dsn:
+                return dsn
+            try:
+                parts = urlsplit(dsn)
+            except Exception:
+                return dsn
+            if not parts.scheme or parts.password is None:
+                return dsn
+            user = parts.username or ""
+            userinfo = f"{user}:***" if user else "***"
+            host = parts.hostname or ""
+            netloc = f"{userinfo}@{host}" if host else userinfo
+            if parts.port is not None:
+                netloc = f"{netloc}:{parts.port}"
+            return urlunsplit(
+                (parts.scheme, netloc, parts.path, parts.query, parts.fragment)
+            )
+
+        def _redact_mapping(
+            mapping: Optional[Mapping[str, object]],
+        ) -> Optional[dict[str, object]]:
+            if mapping is None:
+                return None
+            redacted: dict[str, object] = {}
+            for key, value in mapping.items():
+                if str(key).lower() in {"pwd", "password", "pass", "secret"}:
+                    redacted[key] = "***"
+                else:
+                    redacted[key] = value
+            return redacted
+
+        fields = [
+            ("kind", self.kind),
+            ("async_", self.async_),
+            ("dsn", _redact_dsn(self.dsn)),
+            ("mapping", _redact_mapping(self.mapping)),
+            ("path", self.path),
+            ("memory", self.memory),
+            ("user", self.user),
+            ("host", self.host),
+            ("port", self.port),
+            ("name", self.name),
+            ("pool_size", self.pool_size),
+            ("max", self.max),
+        ]
+        return "EngineSpec(" + ", ".join(f"{k}={v!r}" for k, v in fields) + ")"

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/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/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)