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

tigrbl/schema/decorators.py

@@ -0,0 +1,68 @@
+# tigrbl/v3/schema/decorators.py
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from ..config.constants import TIGRBL_SCHEMA_DECLS_ATTR
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+
+
+@dataclass(frozen=True)
+class _SchemaDecl:
+    alias: str  # name under model.schemas.<alias>
+    kind: str  # "in" | "out"
+
+
+def _register_schema_decl(
+    target_model: type, alias: str, kind: str, schema_cls: type
+) -> None:
+    """Store schema declarations on the model for later binding."""
+    logger.debug(
+        "Registering schema decl for %s alias=%s kind=%s",
+        target_model.__name__,
+        alias,
+        kind,
+    )
+    if kind not in ("in", "out"):
+        logger.debug("Invalid kind '%s' for schema decl", kind)
+        raise ValueError("schema_ctx(kind=...) must be 'in' or 'out'")
+    mapping: Dict[str, Dict[str, type]] = (
+        getattr(target_model, TIGRBL_SCHEMA_DECLS_ATTR, None) or {}
+    )
+    bucket = dict(mapping.get(alias, {}))
+    bucket[kind] = schema_cls
+    mapping[alias] = bucket
+    setattr(target_model, TIGRBL_SCHEMA_DECLS_ATTR, mapping)
+    logger.debug("Registered schema %s for alias '%s'", schema_cls, alias)
+
+
+def schema_ctx(*, alias: str, kind: str = "out", for_: Optional[type] = None):
+    """Register a named schema for a model."""
+
+    def deco(schema_cls: type):
+        if not isinstance(schema_cls, type):
+            logger.debug("schema_ctx applied to non-class %r", schema_cls)
+            raise TypeError("@schema_ctx must decorate a class")
+        if for_ is not None:
+            logger.debug(
+                "Registering schema %s for model %s via decorator",
+                schema_cls,
+                for_.__name__,
+            )
+            _register_schema_decl(for_, alias, kind, schema_cls)
+        setattr(
+            schema_cls, "__tigrbl_schema_decl__", _SchemaDecl(alias=alias, kind=kind)
+        )
+        logger.debug(
+            "Attached schema decl to %s: alias=%s kind=%s", schema_cls, alias, kind
+        )
+        return schema_cls
+
+    return deco
+
+
+__all__ = ["schema_ctx"]

tigrbl/schema/get_schema.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import logging
+from typing import Literal, Optional, Type
+
+from pydantic import BaseModel
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+
+
+def get_schema(
+    orm_cls: type,
+    op: str,
+    *,
+    kind: Literal["in", "out"] = "out",
+) -> Optional[Type[BaseModel]]:
+    """Return the bound schema for ``orm_cls``.
+
+    Parameters
+    ----------
+    orm_cls:
+        ORM model that has been bound via :func:`tigrbl.bindings.build_schemas`.
+    op:
+        Operation alias whose schema should be returned.
+    kind:
+        Either ``"in"`` for request schemas or ``"out"`` for response schemas.
+
+    Returns
+    -------
+    Optional[Type[BaseModel]]
+        The requested schema class if available, otherwise ``None`` when the
+        operation uses raw payloads.
+
+    Raises
+    ------
+    KeyError
+        If the model has not been bound or the operation/kind is unknown.
+    """
+    logger.debug(
+        "Resolving schema for model=%s op=%s kind=%s", orm_cls.__name__, op, kind
+    )
+
+    ns = getattr(orm_cls, "schemas", None)
+    if ns is None:
+        logger.debug("Model %s has no schemas namespace", orm_cls.__name__)
+        raise KeyError(
+            f"{orm_cls.__name__} has no bound schemas; did you include the model?",
+        )
+    logger.debug("Found schemas namespace for model %s", orm_cls.__name__)
+
+    alias_ns = getattr(ns, op, None)
+    if alias_ns is None:
+        logger.debug("Unknown operation '%s' for model %s", op, orm_cls.__name__)
+        raise KeyError(f"Unknown op '{op}' for {orm_cls.__name__}")
+    logger.debug("Found operation '%s' for model %s", op, orm_cls.__name__)
+
+    kind = kind.lower()
+    if kind not in {"in", "out"}:
+        logger.debug("Invalid schema kind '%s' requested", kind)
+        raise ValueError("kind must be 'in' or 'out'")
+    logger.debug("Using schema kind '%s'", kind)
+
+    attr = "in_" if kind == "in" else "out"
+    if not hasattr(alias_ns, attr):
+        logger.debug(
+            "Schema kind '%s' not found for op '%s' on %s", kind, op, orm_cls.__name__
+        )
+        raise KeyError(
+            f"Schema kind '{kind}' not found for op '{op}' on {orm_cls.__name__}",
+        )
+    logger.debug(
+        "Found schema attribute '%s' for op '%s' on %s", attr, op, orm_cls.__name__
+    )
+    schema = getattr(alias_ns, attr)
+    logger.debug(
+        "Resolved schema %s for model %s op=%s kind=%s",
+        schema,
+        orm_cls.__name__,
+        op,
+        kind,
+    )
+    return schema
+
+
+__all__ = ["get_schema"]

tigrbl/schema/schema_spec.py

@@ -0,0 +1,20 @@
+# tigrbl/v3/schema/schema_spec.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .types import SchemaArg, SchemaKind
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaSpec:
+    """Declarative description of a schema for a model."""
+
+    alias: str
+    kind: SchemaKind = "out"
+    for_: Optional[type] = None
+    schema: SchemaArg | None = None
+
+
+__all__ = ["SchemaSpec"]

tigrbl/schema/shortcuts.py

@@ -0,0 +1,42 @@
+# tigrbl/v3/schema/shortcuts.py
+from __future__ import annotations
+
+from typing import Optional, Type
+
+try:  # pragma: no cover
+    from pydantic import BaseModel  # type: ignore
+except Exception:  # pragma: no cover
+
+    class BaseModel:  # minimal stub for typing only
+        pass
+
+
+from ._schema import Schema
+from .schema_spec import SchemaSpec
+from .types import SchemaArg, SchemaKind
+
+
+def schema_spec(
+    alias: str,
+    *,
+    kind: SchemaKind = "out",
+    for_: Optional[type] = None,
+    schema: SchemaArg | None = None,
+) -> SchemaSpec:
+    """Factory for :class:`SchemaSpec`."""
+
+    return SchemaSpec(alias=alias, kind=kind, for_=for_, schema=schema)
+
+
+def schema(
+    model: Type[BaseModel],
+    *,
+    kind: SchemaKind = "out",
+    alias: str | None = None,
+) -> Schema:
+    """Factory for :class:`Schema`."""
+
+    return Schema(model=model, kind=kind, alias=alias)
+
+
+__all__ = ["schema_spec", "schema"]

tigrbl/schema/types.py

@@ -0,0 +1,34 @@
+# tigrbl/v3/schema/types.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Type, Union, Literal
+
+try:  # pragma: no cover
+    from pydantic import BaseModel  # type: ignore
+except Exception:  # pragma: no cover
+
+    class BaseModel:  # minimal stub for typing only
+        pass
+
+
+SchemaKind = Literal["in", "out"]
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaRef:
+    """Lazy reference to ``model.schemas.<alias>.(in_|out)``."""
+
+    alias: str
+    kind: SchemaKind = "in"
+
+
+SchemaArg = Union[
+    Type[BaseModel],  # direct Pydantic model
+    SchemaRef,  # cross-op reference
+    str,  # "alias.in" | "alias.out"
+    Callable[[type], Type[BaseModel]],  # lambda cls: cls.schemas.create.in_
+]
+
+
+__all__ = ["SchemaKind", "SchemaRef", "SchemaArg"]

tigrbl/schema/utils.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import logging
+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")
+
+
+def namely_model(model: Type[BaseModel], *, name: str, doc: str) -> Type[BaseModel]:
+    """Assign a unique name and docstring to a Pydantic model class."""
+    logger.debug("Renaming model %s to %s", model.__name__, name)
+    model.__name__ = name
+    model.__qualname__ = name
+    model.__doc__ = doc
+
+    # Rebuild the model so Pydantic updates internal references (e.g., for OpenAPI titles).
+
+    model.model_rebuild(force=True)
+    logger.debug("Model %s rebuilt", name)
+    return model
+
+
+def _camel(s: str) -> str:
+    rv = "".join(p.capitalize() or "_" for p in s.split("_"))
+    logger.debug("Camel-cased '%s' → '%s'", s, rv)
+    return rv
+
+
+def _extract_example(schema: Type[BaseModel]) -> Dict[str, Any]:
+    """Build a simple example object from field examples if available."""
+    try:
+        js = schema.model_json_schema()
+    except Exception as exc:
+        logger.debug("Failed to build JSON schema for %s: %s", schema, exc)
+        return {}
+    out: Dict[str, Any] = {}
+    for name, prop in (js.get("properties") or {}).items():
+        examples = prop.get("examples")
+        if examples:
+            out[name] = examples[0]
+    logger.debug("Extracted example for %s: %s", schema, out)
+    return out
+
+
+def _make_bulk_rows_model(
+    model: type, verb: str, item_schema: Type[BaseModel]
+) -> Type[BaseModel]:
+    """Build a root model representing ``List[item_schema]``."""
+    name = f"{model.__name__}{_camel(verb)}Request"
+    example = _extract_example(item_schema)
+    examples = [[example]] if example else []
+
+    class _BulkModel(RootModel[List[item_schema]]):  # type: ignore[misc]
+        model_config = ConfigDict(json_schema_extra={"examples": examples})
+
+    logger.debug("Built bulk rows model %s with examples=%s", name, examples)
+    return namely_model(
+        _BulkModel,
+        name=name,
+        doc=f"{verb} request schema for {model.__name__}",
+    )
+
+
+def _make_bulk_rows_response_model(
+    model: type, verb: str, item_schema: Type[BaseModel]
+) -> Type[BaseModel]:
+    """Build a root model representing ``List[item_schema]`` for responses."""
+    name = f"{model.__name__}{_camel(verb)}Response"
+    example = _extract_example(item_schema)
+    examples = [[example]] if example else []
+
+    class _BulkModel(RootModel[List[item_schema]]):  # type: ignore[misc]
+        model_config = ConfigDict(json_schema_extra={"examples": examples})
+
+    logger.debug("Built bulk rows response model %s with examples=%s", name, examples)
+    return namely_model(
+        _BulkModel,
+        name=name,
+        doc=f"{verb} response schema for {model.__name__}",
+    )
+
+
+def _make_bulk_ids_model(
+    model: type, verb: str, pk_type: type | Any
+) -> Type[BaseModel]:
+    """Build a wrapper schema with an ``ids: List[pk_type]`` field."""
+    name = f"{model.__name__}{_camel(verb)}Request"
+    schema = create_model(  # type: ignore[call-arg]
+        name,
+        ids=(List[pk_type], Field(...)),  # type: ignore[name-defined]
+    )
+    logger.debug("Built bulk ids model %s", name)
+    return namely_model(
+        schema,
+        name=name,
+        doc=f"{verb} request schema for {model.__name__}",
+    )
+
+
+def _make_deleted_response_model(model: type, verb: str) -> Type[BaseModel]:
+    """Build a response schema with a ``deleted`` count."""
+    name = f"{model.__name__}{_camel(verb)}Response"
+    schema = create_model(  # type: ignore[call-arg]
+        name,
+        deleted=(int, Field(..., examples=[0])),
+        __config__=ConfigDict(json_schema_extra={"examples": [{"deleted": 0}]}),
+    )
+    logger.debug("Built deleted response model %s", name)
+    return namely_model(
+        schema,
+        name=name,
+        doc=f"{verb} response schema for {model.__name__}",
+    )
+
+
+def _make_pk_model(
+    model: type, verb: str, pk_name: str, pk_type: type | Any
+) -> Type[BaseModel]:
+    """Build a wrapper schema with a single primary-key field."""
+    name = f"{model.__name__}{_camel(verb)}Request"
+    schema = create_model(  # type: ignore[call-arg]
+        name,
+        **{pk_name: (pk_type, Field(...))},  # type: ignore[name-defined]
+    )
+    logger.debug("Built pk model %s for field %s", name, pk_name)
+    return namely_model(
+        schema,
+        name=name,
+        doc=f"{verb} request schema for {model.__name__}",
+    )
+
+
+__all__ = [
+    "namely_model",
+    "_make_bulk_rows_model",
+    "_make_bulk_rows_response_model",
+    "_make_bulk_ids_model",
+    "_make_deleted_response_model",
+    "_make_pk_model",
+]

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