tigrbl-orm 0.1.0.dev1__py3-none-any.whl

tigrbl_orm/orm/__init__.py

@@ -0,0 +1 @@
+"""ORM utilities containing SQLAlchemy tables and mixins."""

tigrbl_orm/orm/mixins/_RowBound.py

@@ -0,0 +1,83 @@
+# tigrbl/v3/mixins/_RowBound.py
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from ...runtime.status import HTTP_ERROR_MESSAGES, create_standardized_error
+
+
+class _RowBound:
+    """
+    Base mix-in for row-level visibility.
+
+    Concrete subclasses **must** override:
+
+        @staticmethod
+        def is_visible(obj, ctx) -> bool
+
+    Hooks are wired only if the subclass actually provides an implementation.
+    """
+
+    # ────────────────────────────────────────────────────────────────────
+    # Tigrbl bootstrap
+    # -------------------------------------------------------------------
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        cls._install_rowbound_hooks()
+
+    @classmethod
+    def _install_rowbound_hooks(cls) -> None:
+        # Skip abstract helpers or unmapped mix-ins
+        if cls.is_visible is _RowBound.is_visible:
+            return
+        if not hasattr(cls, "__table__"):
+            return
+
+        hook = cls._make_row_visibility_hook()
+        hooks_attr = getattr(cls, "__tigrbl_hooks__", {})
+        hooks = {**hooks_attr} if isinstance(hooks_attr, dict) else {}
+
+        def _append(alias: str, phase: str, fn) -> None:
+            phase_map = hooks.get(alias) or {}
+            lst = list(phase_map.get(phase) or [])
+            if fn not in lst:
+                lst.append(fn)
+            phase_map[phase] = tuple(lst)
+            hooks[alias] = phase_map
+
+        for op in ("read", "list"):
+            _append(op, "POST_HANDLER", hook)
+
+        setattr(cls, "__tigrbl_hooks__", hooks)
+
+    # ────────────────────────────────────────────────────────────────────
+    # Per-request hook
+    # -------------------------------------------------------------------
+    @classmethod
+    def _make_row_visibility_hook(cls):
+        def _row_visibility_hook(ctx: Mapping[str, Any]) -> None:
+            if "result" not in ctx:  # nothing to filter
+                return
+
+            res = ctx["result"]
+
+            # LIST → keep only visible rows
+            if isinstance(res, Sequence):
+                ctx["result"] = [row for row in res if cls.is_visible(row, ctx)]
+                return
+
+            # READ → invisible row → pretend 404
+            if not cls.is_visible(res, ctx):
+                http_exc, _, _ = create_standardized_error(
+                    404, message=HTTP_ERROR_MESSAGES[404]
+                )
+                raise http_exc
+
+        return _row_visibility_hook
+
+    # -------------------------------------------------------------------
+    # Must be overridden
+    # -------------------------------------------------------------------
+    @staticmethod
+    def is_visible(obj, ctx) -> bool:  # pragma: no cover
+        raise NotImplementedError

tigrbl_orm/orm/mixins/__init__.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from .bootstrappable import Bootstrappable
+from .upsertable import Upsertable
+from .ownable import Ownable, OwnerPolicy
+from .tenant_bound import TenantBound, TenantPolicy
+from .key_digest import KeyDigest
+
+from .utils import (
+    tzutcnow,
+    tzutcnow_plus_day,
+    _infer_schema,
+    uuid_example,
+    CRUD_IN,
+    CRUD_OUT,
+    CRUD_IO,
+    RO_IO,
+)
+from .principals import GUIDPk, TenantColumn, UserColumn, OrgColumn, Principal
+from .bound import OwnerBound, UserBound
+from .lifecycle import (
+    Created,
+    LastUsed,
+    Timestamped,
+    ActiveToggle,
+    SoftDelete,
+    Versioned,
+)
+from .hierarchy import Contained, TreeNode
+from .edges import RelationEdge, MaskableEdge, TaggableEdge
+from .markers import AsyncCapable, Audited
+from .locks import RowLock, SoftLock
+from .operations import BulkCapable, Replaceable, Mergeable, Streamable
+from .fields import (
+    Slugged,
+    StatusColumn,
+    ValidityWindow,
+    Monetary,
+    ExtRef,
+    MetaJSON,
+    BlobRef,
+    SearchVector,
+)
+
+__all__ = [
+    "Bootstrappable",
+    "Upsertable",
+    "Ownable",
+    "OwnerPolicy",
+    "TenantBound",
+    "TenantPolicy",
+    "KeyDigest",
+    "tzutcnow",
+    "tzutcnow_plus_day",
+    "_infer_schema",
+    "uuid_example",
+    "CRUD_IN",
+    "CRUD_OUT",
+    "CRUD_IO",
+    "RO_IO",
+    "GUIDPk",
+    "TenantColumn",
+    "UserColumn",
+    "OrgColumn",
+    "Principal",
+    "OwnerBound",
+    "UserBound",
+    "Created",
+    "LastUsed",
+    "Timestamped",
+    "ActiveToggle",
+    "SoftDelete",
+    "Versioned",
+    "Contained",
+    "TreeNode",
+    "RelationEdge",
+    "MaskableEdge",
+    "TaggableEdge",
+    "AsyncCapable",
+    "Audited",
+    "RowLock",
+    "SoftLock",
+    "BulkCapable",
+    "Replaceable",
+    "Mergeable",
+    "Streamable",
+    "Slugged",
+    "StatusColumn",
+    "ValidityWindow",
+    "Monetary",
+    "ExtRef",
+    "MetaJSON",
+    "BlobRef",
+    "SearchVector",
+]

tigrbl_orm/orm/mixins/bootstrappable.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import Any, ClassVar, Iterable
+import logging
+import sqlalchemy as sa
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy.exc import IntegrityError
+
+from ...types import Session, event
+
+log = logging.getLogger(__name__)
+
+
+class Bootstrappable:
+    """
+    Seed DEFAULT_ROWS for *this mapped class only* with zero magic.
+
+    Rules:
+      - Insert ONLY keys present on this class's mapped columns.
+      - No auto defaults, no timestamp injection, no unique probing.
+      - Idempotency only if ALL primary key columns are present in the row.
+      - Listener is attached to cls.__table__ (no cross-class/global effects).
+    """
+
+    DEFAULT_ROWS: ClassVar[list[dict[str, Any]]] = []
+
+    def __init_subclass__(cls, **kw):
+        super().__init_subclass__(**kw)
+        event.listen(
+            cls.__table__, "after_create", cls._after_create_insert_default_rows
+        )
+
+    @classmethod
+    def _after_create_insert_default_rows(cls, target, connection, **_):
+        if not getattr(cls, "DEFAULT_ROWS", None):
+            return
+        from sqlalchemy.orm import sessionmaker
+
+        SessionLocal = sessionmaker(bind=connection, future=True)
+        db: Session = SessionLocal()
+        try:
+            cls._insert_rows(db, cls.DEFAULT_ROWS)
+            db.commit()
+        except Exception as e:
+            db.rollback()
+            log.warning(
+                "Bootstrappable seed failed for %s: %s",
+                cls.__name__,
+                repr(e),
+                exc_info=True,
+            )
+        finally:
+            db.close()
+
+    @classmethod
+    def ensure_bootstrapped(
+        cls, db: Session, rows: Iterable[dict[str, Any]] | None = None
+    ) -> None:
+        rows = cls.DEFAULT_ROWS if rows is None else list(rows)
+        if rows:
+            cls._insert_rows(db, rows)
+
+    @classmethod
+    def _insert_rows(cls, db: Session, rows: Iterable[dict[str, Any]]) -> None:
+        mapper = sa_inspect(cls)
+
+        # --- pick an insertable target (avoid boolean eval + avoid JOINs) ---
+        local = mapper.local_table
+        table = local if local is not None else mapper.persist_selectable
+        if not hasattr(table, "insert"):  # e.g., persist_selectable is a JOIN
+            table = mapper.local_table
+
+        col_keys = {c.key for c in mapper.columns}
+        pk_cols = list(table.primary_key.columns) if table.primary_key else []
+        pk_keys = {c.key for c in pk_cols}
+
+        def clean(r: dict[str, Any]) -> dict[str, Any]:
+            # keep only columns mapped on THIS class
+            return {k: r[k] for k in r.keys() & col_keys}
+
+        payloads = [clean(r) for r in rows if r]
+        if not payloads:
+            return
+
+        # Idempotent path if all PK columns are provided (per row)
+        can_upsert = bool(pk_cols) and all(pk_keys <= set(p.keys()) for p in payloads)
+
+        dialect = db.get_bind().dialect.name
+
+        if can_upsert and dialect == "postgresql":
+            from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+            stmt = (
+                pg_insert(table)
+                .values(payloads)
+                .on_conflict_do_nothing(index_elements=[c.name for c in pk_cols])
+            )
+            db.execute(stmt)
+            return
+
+        if can_upsert and dialect == "sqlite":
+            # Best-effort idempotency for SQLite
+            from sqlalchemy.dialects.sqlite import insert as sqlite_insert
+
+            db.execute(sqlite_insert(table).values(payloads).prefix_with("OR IGNORE"))
+            return
+
+        # Fallback: plain inserts; swallow duplicate races
+        for p in payloads:
+            try:
+                db.execute(sa.insert(table).values(**p))
+            except IntegrityError:
+                db.rollback()  # treat as already present

tigrbl_orm/orm/mixins/bound.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from ...config.constants import CTX_AUTH_KEY, CTX_USER_ID_KEY
+from ...specs import ColumnSpec, F, S, acol
+from ..._spec.storage_spec import ForeignKeySpec
+from ...types import PgUUID, UUID, Mapped
+
+from .utils import uuid_example, CRUD_IO
+
+
+class OwnerBound:
+    owner_id: Mapped[UUID] = acol(
+        spec=ColumnSpec(
+            storage=S(
+                type_=PgUUID(as_uuid=True),
+                fk=ForeignKeySpec(target="users.id"),
+            ),
+            field=F(py_type=UUID, constraints={"examples": [uuid_example]}),
+            io=CRUD_IO,
+        )
+    )
+
+    @classmethod
+    def filter_for_ctx(cls, q, ctx):
+        auto_fields = ctx.get(CTX_AUTH_KEY, {})
+        return q.filter(cls.owner_id == auto_fields.get(CTX_USER_ID_KEY))
+
+
+class UserBound:
+    user_id: Mapped[UUID] = acol(
+        spec=ColumnSpec(
+            storage=S(
+                type_=PgUUID(as_uuid=True),
+                fk=ForeignKeySpec(target="users.id"),
+            ),
+            field=F(py_type=UUID, constraints={"examples": [uuid_example]}),
+            io=CRUD_IO,
+        )
+    )
+
+    @classmethod
+    def filter_for_ctx(cls, q, ctx):
+        auto_fields = ctx.get(CTX_AUTH_KEY, {})
+        return q.filter(cls.user_id == auto_fields.get(CTX_USER_ID_KEY))
+
+
+__all__ = ["OwnerBound", "UserBound"]

tigrbl_orm/orm/mixins/edges.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from ...specs import ColumnSpec, F, S, acol
+from ...types import Integer, String, declarative_mixin, Mapped
+
+from .utils import CRUD_IO
+
+
+@declarative_mixin
+class RelationEdge:
+    """Marker: row itself is an association—no extra columns required."""
+
+    pass
+
+
+@declarative_mixin
+class MaskableEdge:
+    """Edge row with bitmap of verbs/roles."""
+
+    mask: Mapped[int] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=Integer, nullable=False),
+            field=F(py_type=int),
+            io=CRUD_IO,
+        )
+    )
+
+
+@declarative_mixin
+class TaggableEdge:
+    tag: Mapped[str] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=String, nullable=False),
+            field=F(py_type=str),
+            io=CRUD_IO,
+        )
+    )
+
+
+__all__ = ["RelationEdge", "MaskableEdge", "TaggableEdge"]

tigrbl_orm/orm/mixins/fields.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import datetime as dt
+from decimal import Decimal
+
+from ...specs import ColumnSpec, F, IO, S, acol
+from ...types import (
+    TZDateTime,
+    PgUUID,
+    String,
+    SAEnum,
+    Numeric,
+    JSONB,
+    TSVECTOR,
+    UUID,
+    Index,
+    declarative_mixin,
+    declared_attr,
+    Mapped,
+)
+
+from .utils import tzutcnow, tzutcnow_plus_day, CRUD_IO
+
+
+@declarative_mixin
+class Slugged:
+    slug: Mapped[str] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=String, unique=True, nullable=False),
+            field=F(py_type=str, constraints={"max_length": 120}),
+            io=CRUD_IO,
+        )
+    )
+
+
+@declarative_mixin
+class StatusColumn:
+    status: Mapped[str] = acol(
+        spec=ColumnSpec(
+            storage=S(
+                type_=SAEnum(
+                    "queued",
+                    "waiting",
+                    "input_required",
+                    "auth_required",
+                    "approved",
+                    "rejected",
+                    "dispatched",
+                    "running",
+                    "paused",
+                    "success",
+                    "failed",
+                    "cancelled",
+                    name="status_enum",
+                ),
+                default="waiting",
+                nullable=False,
+            ),
+            field=F(py_type=str),
+            io=CRUD_IO,
+        )
+    )
+
+
+@declarative_mixin
+class ValidityWindow:
+    valid_from: Mapped[dt.datetime] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=TZDateTime, default=tzutcnow, nullable=False),
+            field=F(py_type=dt.datetime),
+            io=CRUD_IO,
+        )
+    )
+    valid_to: Mapped[dt.datetime | None] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=TZDateTime, default=tzutcnow_plus_day),
+            field=F(py_type=dt.datetime),
+            io=CRUD_IO,
+        )
+    )
+
+
+@declarative_mixin
+class Monetary:
+    amount: Mapped[Decimal] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=Numeric(18, 2), nullable=False),
+            field=F(py_type=Decimal),
+            io=CRUD_IO,
+        )
+    )
+    currency: Mapped[str] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=String, default="USD", nullable=False),
+            field=F(py_type=str, constraints={"max_length": 3}),
+            io=CRUD_IO,
+        )
+    )
+
+
+@declarative_mixin
+class ExtRef:
+    external_id: Mapped[str] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=String),
+            field=F(py_type=str),
+            io=CRUD_IO,
+        )
+    )
+    provider: Mapped[str] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=String),
+            field=F(py_type=str),
+            io=CRUD_IO,
+        )
+    )
+
+
+@declarative_mixin
+class MetaJSON:
+    meta: Mapped[dict] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=JSONB, default=dict),
+            field=F(py_type=dict),
+            io=CRUD_IO,
+        )
+    )
+
+
+@declarative_mixin
+class BlobRef:
+    blob_id: Mapped[UUID | None] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=PgUUID(as_uuid=True)),
+            field=F(py_type=UUID),
+            io=CRUD_IO,
+        )
+    )
+
+
+@declarative_mixin
+class SearchVector:
+    tsv: Mapped[str] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=TSVECTOR),
+            field=F(py_type=str),
+            io=IO(),
+        )
+    )
+
+    @declared_attr
+    def __table_args__(cls):
+        return (Index(f"ix_{cls.__tablename__}_tsv", "tsv"),)
+
+
+__all__ = [
+    "Slugged",
+    "StatusColumn",
+    "ValidityWindow",
+    "Monetary",
+    "ExtRef",
+    "MetaJSON",
+    "BlobRef",
+    "SearchVector",
+]

tigrbl_orm/orm/mixins/hierarchy.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from ...specs import ColumnSpec, F, S, acol
+from ..._spec.storage_spec import ForeignKeySpec
+from ...types import PgUUID, UUID, String, declarative_mixin, declared_attr, Mapped
+
+from .utils import CRUD_IO
+
+
+@declarative_mixin
+class Contained:
+    @declared_attr
+    def parent_id(cls) -> Mapped[UUID]:
+        if not hasattr(cls, "parent_table"):
+            raise AttributeError("subclass must set parent_table")
+        spec = ColumnSpec(
+            storage=S(
+                type_=PgUUID(as_uuid=True),
+                fk=ForeignKeySpec(target=f"{cls.parent_table}.id"),
+                nullable=False,
+            ),
+            field=F(py_type=UUID),
+            io=CRUD_IO,
+        )
+        return acol(spec=spec)
+
+
+@declarative_mixin
+class TreeNode:
+    """Self-nesting hierarchy."""
+
+    @declared_attr
+    def parent_id(cls) -> Mapped[UUID | None]:
+        spec = ColumnSpec(
+            storage=S(
+                type_=PgUUID(as_uuid=True),
+                fk=ForeignKeySpec(target=f"{cls.__tablename__}.id"),
+                nullable=True,
+            ),
+            field=F(py_type=UUID),
+            io=CRUD_IO,
+        )
+        return acol(spec=spec)
+
+    path: Mapped[str] = acol(
+        spec=ColumnSpec(
+            storage=S(type_=String),
+            field=F(py_type=str),
+            io=CRUD_IO,
+        )
+    )
+
+
+__all__ = ["Contained", "TreeNode"]

tigrbl_orm/orm/mixins/key_digest.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from hashlib import sha256
+from secrets import token_urlsafe
+
+from ..._spec.io_spec import Pair
+from ...specs import F, IO, S, acol
+from ...types import Mapped, String, declarative_mixin
+
+
+@declarative_mixin
+class KeyDigest:
+    """Provides hashed API key storage with helpers."""
+
+    @staticmethod
+    def _generate_pair(_ctx: dict | None = None) -> Pair:
+        """Generate a raw/stored pair for API keys."""
+        raw = token_urlsafe(32)
+        return Pair(raw=raw, stored=sha256(raw.encode()).hexdigest())
+
+    digest: Mapped[str] = acol(
+        storage=S(String, nullable=False, unique=True, index=True),
+        field=F(constraints={"max_length": 64}),
+        io=IO(out_verbs=("read", "list", "create")).paired(
+            make=_generate_pair,
+            alias="api_key",
+            verbs=("create",),
+            emit="post_refresh",
+            alias_field=F(py_type=str),  # include alias in the response schema
+            mask_last=None,  # set an int if you want masking
+        ),
+    )
+
+    @staticmethod
+    def digest_of(value: str) -> str:
+        return sha256(value.encode()).hexdigest()
+
+    @property
+    def raw_key(self) -> str:  # pragma: no cover - write-only
+        raise AttributeError("raw_key is write-only")
+
+    @raw_key.setter
+    def raw_key(self, value: str) -> None:
+        self.digest = self.digest_of(value)