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

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

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/system/__init__.py

@@ -8,5 +8,6 @@ Tigrbl v3 – System/Diagnostics helpers.
 from __future__ import annotations
 
 from .diagnostics import mount_diagnostics
+from .uvicorn import stop_uvicorn_server
 
-__all__ = ["mount_diagnostics"]
+__all__ = ["mount_diagnostics", "stop_uvicorn_server"]

tigrbl/system/uvicorn.py

@@ -0,0 +1,60 @@
+"""Utilities for running uvicorn during tests or tooling."""
+
+from __future__ import annotations
+
+import asyncio
+
+import uvicorn
+
+
+async def _cancel_task(task: asyncio.Task) -> None:
+    if task.done():
+        return
+    task.cancel()
+    try:
+        await task
+    except asyncio.CancelledError:
+        return
+
+
+async def _close_servers(server: uvicorn.Server) -> None:
+    servers = []
+    primary = getattr(server, "server", None)
+    if primary is not None:
+        servers.append(primary)
+    extra = getattr(server, "servers", None)
+    if extra:
+        servers.extend(extra)
+    for srv in servers:
+        close = getattr(srv, "close", None)
+        if callable(close):
+            close()
+        wait_closed = getattr(srv, "wait_closed", None)
+        if callable(wait_closed):
+            await wait_closed()
+
+
+async def stop_uvicorn_server(
+    server: uvicorn.Server,
+    task: asyncio.Task,
+    *,
+    timeout: float = 5.0,
+) -> None:
+    """Request uvicorn shutdown and ensure the task exits."""
+    if task.done():
+        return
+
+    server.should_exit = True
+    try:
+        await asyncio.wait_for(task, timeout=timeout)
+        return
+    except asyncio.TimeoutError:
+        server.force_exit = True
+        shutdown = getattr(server, "shutdown", None)
+        if callable(shutdown):
+            try:
+                await asyncio.wait_for(shutdown(), timeout=timeout)
+            except asyncio.TimeoutError:
+                pass
+        await _close_servers(server)
+        await _cancel_task(task)

tigrbl/table/_base.py

@@ -99,6 +99,10 @@ def _materialize_colspecs_to_sqla(cls) -> None:
         from tigrbl.column.column_spec import ColumnSpec
     except Exception:
         return
+    try:
+        from sqlalchemy.orm import InstrumentedAttribute
+    except Exception:  # pragma: no cover - defensive for minimal SQLA envs
+        InstrumentedAttribute = None
 
     # Prefer explicit registry if present; otherwise collect specs from the
     # entire MRO so mixins contribute their ColumnSpec definitions.
@@ -123,6 +127,13 @@ def _materialize_colspecs_to_sqla(cls) -> None:
         if not storage:
             # Virtual (wire-only) column – no DB column
             continue
+        existing_attr = getattr(cls, name, None)
+        if InstrumentedAttribute is not None and isinstance(
+            existing_attr, InstrumentedAttribute
+        ):
+            # Column already mapped on a base class; avoid duplicating columns
+            # that trigger SQLAlchemy implicit combination warnings.
+            continue
 
         dtype = getattr(storage, "type_", None)
         if not dtype:
@@ -174,18 +185,41 @@ class Base(DeclarativeBase):
     __allow_unmapped__ = True
 
     def __init_subclass__(cls, **kw):
-        # 0) Remove any previously registered class with the same name.
+        # 0) Remove any previously registered class with the same module path.
         try:
             reg = Base.registry._class_registry
-            keys = [cls.__name__, f"{cls.__module__}.{cls.__name__}"]
-            existing = next((reg.get(k) for k in keys if reg.get(k) is not None), None)
+            key = f"{cls.__module__}.{cls.__name__}"
+            existing = reg.get(key)
             if existing is not None:
                 try:
                     Base.registry._dispose_cls(existing)
                 except Exception:
                     pass
-                for k in keys:
-                    reg.pop(k, None)
+                reg.pop(key, None)
+                if reg.get(cls.__name__) is existing:
+                    reg.pop(cls.__name__, None)
+        except Exception:
+            pass
+
+        # 0.5) If a table with the same name already exists, allow this class
+        # to extend it instead of raising duplicate-table errors.
+        try:
+            table_name = getattr(cls, "__tablename__", None)
+            if table_name and table_name in Base.metadata.tables:
+                table_args = getattr(cls, "__table_args__", None)
+                if table_args is None:
+                    cls.__table_args__ = {"extend_existing": True}
+                elif isinstance(table_args, dict):
+                    table_args = dict(table_args)
+                    table_args["extend_existing"] = True
+                    cls.__table_args__ = table_args
+                elif isinstance(table_args, tuple):
+                    if table_args and isinstance(table_args[-1], dict):
+                        table_dict = dict(table_args[-1])
+                        table_dict["extend_existing"] = True
+                        cls.__table_args__ = (*table_args[:-1], table_dict)
+                    else:
+                        cls.__table_args__ = (*table_args, {"extend_existing": True})
         except Exception:
             pass
 

tigrbl/types/__init__.py

@@ -25,7 +25,6 @@ from ..deps.sqlalchemy import (
     ARRAY,
     PgEnum,
     JSONB,
-    _PgUUID,
     TSVECTOR,
     # ORM
     Mapped,
@@ -67,6 +66,7 @@ from ..deps.fastapi import (
 
 # ── Local Package ─────────────────────────────────────────────────────────
 from .op import _Op, _SchemaVerb
+from .uuid import PgUUID, SqliteUUID
 from .authn_abc import AuthNProvider
 from .table_config_provider import TableConfigProvider
 from .nested_path_provider import NestedPathProvider
@@ -88,12 +88,6 @@ DateTime = _DateTime(timezone=False)
 TZDateTime = _DateTime(timezone=True)
 
 
-class PgUUID(_PgUUID):
-    @property
-    def hex(self):
-        return self.as_uuid.hex
-
-
 # ── Public Re-exports (Backwards Compatibility) ──────────────────────────
 __all__: list[str] = [
     # local
@@ -110,6 +104,8 @@ __all__: list[str] = [
     "list_request_extras_providers",
     "list_response_extras_providers",
     "OpConfigProvider",
+    # add ons
+    "SqliteUUID",
     # builtin types
     "MethodType",
     "SimpleNamespace",