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

tigrbl/op/types.py

@@ -0,0 +1,136 @@
+# tigrbl/v3/ops/types.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from typing import Any, Literal, Mapping, Optional, Tuple, cast
+
+from ..config.constants import CANON as CANONICAL_VERB_TUPLE
+from ..hook.types import PHASE, HookPhase, PHASES, Ctx, StepFn, HookPredicate
+from ..hook import HookSpec as OpHook
+from ..response.types import ResponseSpec
+from ..engine.engine_spec import EngineCfg
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..schema.types import SchemaArg
+# ───────────────────────────────────────────────────────────────────────────────
+# Core aliases & enums
+# ───────────────────────────────────────────────────────────────────────────────
+
+PersistPolicy = Literal[
+    "default",
+    "prepend",
+    "append",
+    "override",
+    "skip",
+]  # TX policy
+Arity = Literal["collection", "member"]  # HTTP path shape
+
+TargetOp = Literal[
+    "create",
+    "read",
+    "update",
+    "replace",
+    "merge",
+    "delete",
+    "list",
+    "clear",
+    "bulk_create",
+    "bulk_update",
+    "bulk_replace",
+    "bulk_merge",
+    "bulk_delete",
+    "custom",
+]
+
+VerbAliasPolicy = Literal["both", "alias_only", "canonical_only"]  # legacy export
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Lazy-capable schema argument types
+# ───────────────────────────────────────────────────────────────────────────────
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Engine binding (optional, used by resolver precedence: op > table > api > app)
+# ───────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class OpSpec:
+    """
+    Single source of truth for an operation.
+
+    • `target` = canonical verb ("create"…,"custom")
+    • `arity`  = REST shape ("member"|"collection")
+
+    Serialization mode is inferred **only** from schema presence:
+      - if model.schemas.<alias>.out exists → serialize
+      - otherwise → raw pass-through
+
+    Optional engine binding:
+      - `engine` allows per-op routing (DSN string or structured mapping).
+        When present, it participates in resolver precedence (op > table > api > app).
+    """
+
+    # Identity & exposure
+    alias: str
+    target: TargetOp
+    table: Optional[type] = None
+    expose_routes: bool = True
+    expose_rpc: bool = True
+    expose_method: bool = True
+
+    # Optional per-op engine binding (DSN string or mapping spec)
+    engine: Optional[EngineCfg] = None
+
+    # HTTP behavior
+    arity: Arity = "collection"
+    http_methods: Optional[Tuple[str, ...]] = None
+    path_suffix: Optional[str] = None
+    tags: Tuple[str, ...] = field(default_factory=tuple)
+    status_code: Optional[int] = None
+    response: Optional[ResponseSpec] = None
+
+    # Persistence
+    persist: PersistPolicy = "default"
+
+    # Schema overrides (resolved later by binder)
+    request_model: Optional[SchemaArg] = None
+    response_model: Optional[SchemaArg] = None
+
+    # Return shaping: "raw" passthrough vs "model" serialization
+    returns: Literal["raw", "model"] = "raw"
+
+    # Handler & hooks
+    handler: Optional[StepFn] = None
+    hooks: Tuple[OpHook, ...] = field(default_factory=tuple)
+
+    # RBAC / diagnostics
+    rbac_guard_op: Optional[str] = None
+    core: Optional[StepFn] = None
+    core_raw: Optional[StepFn] = None
+    extra: Mapping[str, Any] = field(default_factory=dict)
+    deps: Tuple[StepFn | str, ...] = field(default_factory=tuple)
+    secdeps: Tuple[StepFn | str, ...] = field(default_factory=tuple)
+
+
+# Canonical verb set
+CANON: Tuple[TargetOp, ...] = cast(Tuple[TargetOp, ...], CANONICAL_VERB_TUPLE)
+
+__all__ = [
+    "PersistPolicy",
+    "Arity",
+    "TargetOp",
+    "VerbAliasPolicy",
+    "PHASE",
+    "HookPhase",
+    "PHASES",
+    "Ctx",
+    "StepFn",
+    "HookPredicate",
+    "EngineCfg",
+    "OpHook",
+    "OpSpec",
+    "CANON",
+]

tigrbl/orm/__init__.py

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

tigrbl/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.errors 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/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/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/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 ...specs.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/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/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",
+]