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

tigrbl/hook/__init__.py

@@ -0,0 +1,21 @@
+from ..config.constants import HOOK_DECLS_ATTR
+from .decorators import hook_ctx
+from .types import PHASE, HookPhase, PHASES, Ctx, StepFn, HookPredicate
+from .shortcuts import hook, hook_spec
+from ._hook import Hook
+from .hook_spec import HookSpec
+
+__all__ = [
+    "hook_ctx",
+    "HOOK_DECLS_ATTR",
+    "Hook",
+    "PHASE",
+    "HookPhase",
+    "PHASES",
+    "Ctx",
+    "StepFn",
+    "HookPredicate",
+    "hook",
+    "hook_spec",
+    "HookSpec",
+]

tigrbl/hook/_hook.py

@@ -0,0 +1,22 @@
+"""Runtime hook wrapper for Tigrbl v3."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Optional, Union
+
+from .types import HookPhase, StepFn
+
+
+@dataclass(frozen=True, slots=True)
+class Hook:
+    """Concrete hook bound to a phase and one or more ops."""
+
+    phase: HookPhase
+    fn: StepFn
+    ops: Union[str, Iterable[str]]
+    name: Optional[str] = None
+    description: Optional[str] = None
+
+
+__all__ = ["Hook"]

tigrbl/hook/decorators.py

@@ -0,0 +1,28 @@
+"""Hook-related decorators for Tigrbl v3."""
+
+from __future__ import annotations
+
+from typing import Iterable, Union
+
+from ..config.constants import HOOK_DECLS_ATTR
+from ._hook import Hook
+
+
+def hook_ctx(ops: Union[str, Iterable[str]], *, phase: str):
+    """Declare a ctx-only hook for one/many ops at a given phase."""
+
+    def deco(fn):
+        from ..op.decorators import _ensure_cm, _unwrap
+
+        cm = _ensure_cm(fn)
+        f = _unwrap(cm)
+        f.__tigrbl_ctx_only__ = True
+        lst = getattr(f, HOOK_DECLS_ATTR, [])
+        lst.append(Hook(phase=phase, fn=f, ops=ops))
+        setattr(f, HOOK_DECLS_ATTR, lst)
+        return cm
+
+    return deco
+
+
+__all__ = ["hook_ctx", "HOOK_DECLS_ATTR"]

tigrbl/hook/hook_spec.py

@@ -0,0 +1,24 @@
+"""Hook specification for Tigrbl v3."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .types import HookPhase, StepFn, HookPredicate
+
+
+@dataclass(frozen=True, slots=True)
+class HookSpec:
+    phase: HookPhase
+    fn: StepFn
+    order: int = 0
+    when: Optional[HookPredicate] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+
+
+# Backwards compatibility alias
+OpHook = HookSpec
+
+__all__ = ["HookSpec", "OpHook"]

tigrbl/hook/mro_collect.py

@@ -0,0 +1,98 @@
+"""Helpers for collecting ctx-only hooks."""
+
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Any, Callable, Dict, Iterable, Union
+
+from ..runtime.executor import _Ctx
+from ..op.collect import apply_alias
+from ..op.mro_collect import mro_alias_map_for
+from ..op.decorators import _maybe_await, _unwrap
+from .decorators import HOOK_DECLS_ATTR, Hook
+
+logger = logging.getLogger("uvicorn")
+
+
+def _phase_io_key(phase: str) -> str | None:
+    p = str(phase)
+    if p.startswith("PRE_"):
+        return "payload"
+    if p.startswith("POST_"):
+        return "result"
+    if p.startswith("ON_"):
+        return "error"
+    return None
+
+
+def _wrap_ctx_hook(
+    table: type, func: Callable[..., Any], phase: str
+) -> Callable[..., Any]:
+    io_key = _phase_io_key(phase)
+
+    async def hook(
+        value=None, *, db=None, request=None, ctx: Dict[str, Any] | None = None
+    ):
+        ctx = _Ctx.ensure(request=request, db=db, seed=ctx)
+        if io_key is not None and value is not None:
+            ctx[io_key] = value
+        bound = func.__get__(table, table)
+        _ = await _maybe_await(bound(ctx))
+        if io_key is None:
+            return None
+        return ctx.get(io_key, value)
+
+    hook.__name__ = getattr(func, "__name__", "hook")
+    hook.__qualname__ = getattr(func, "__qualname__", hook.__name__)
+    return hook
+
+
+@lru_cache(maxsize=None)
+def _mro_collect_decorated_hooks_cached(
+    table: type, visible_aliases_fs: frozenset[str]
+) -> Dict[str, Dict[str, list[Callable[..., Any]]]]:
+    """Cached helper for :func:`mro_collect_decorated_hooks`."""
+
+    visible_aliases = set(visible_aliases_fs)
+    logger.info("Collecting hooks for %s", table.__name__)
+    mapping: Dict[str, Dict[str, list[Callable[..., Any]]]] = {}
+    aliases = mro_alias_map_for(table)
+
+    def _resolve_ops(spec: Union[str, Iterable[str]]) -> Iterable[str]:
+        if spec == "*":
+            return visible_aliases
+        if isinstance(spec, str):
+            return [spec if spec in visible_aliases else apply_alias(spec, aliases)]
+        out: list[str] = []
+        for x in spec:
+            out.append(x if x in visible_aliases else apply_alias(x, aliases))
+        return out
+
+    for base in reversed(table.__mro__):
+        for name, attr in base.__dict__.items():
+            func = _unwrap(attr)
+            decls: list[Hook] | None = getattr(func, HOOK_DECLS_ATTR, None)
+            if not decls:
+                continue
+            for d in decls:
+                for op in _resolve_ops(d.ops):
+                    if op not in visible_aliases:
+                        continue
+                    ph = d.phase
+                    mapping.setdefault(op, {}).setdefault(ph, []).append(
+                        _wrap_ctx_hook(table, d.fn, ph)
+                    )
+    logger.debug("Collected hooks for aliases: %s", list(mapping.keys()))
+    return mapping
+
+
+def mro_collect_decorated_hooks(
+    table: type, *, visible_aliases: set[str]
+) -> Dict[str, Dict[str, list[Callable[..., Any]]]]:
+    """Collect alias→phase→[hook] declarations across a table's MRO."""
+
+    return _mro_collect_decorated_hooks_cached(table, frozenset(visible_aliases))
+
+
+__all__ = ["mro_collect_decorated_hooks"]

tigrbl/hook/shortcuts.py

@@ -0,0 +1,44 @@
+"""Shortcut helpers for building Hook specs."""
+
+from __future__ import annotations
+
+from typing import Iterable, Union
+
+from .types import HookPhase, HookPredicate, StepFn
+from ._hook import Hook
+from .hook_spec import HookSpec
+
+
+def hook(
+    phase: HookPhase,
+    ops: Union[str, Iterable[str]],
+    fn: StepFn,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Hook:
+    """Build a :class:`Hook` instance."""
+    return Hook(phase=phase, fn=fn, ops=ops, name=name, description=description)
+
+
+def hook_spec(
+    phase: HookPhase,
+    fn: StepFn,
+    *,
+    order: int = 0,
+    when: HookPredicate | None = None,
+    name: str | None = None,
+    description: str | None = None,
+) -> HookSpec:
+    """Build a :class:`HookSpec` instance."""
+    return HookSpec(
+        phase=phase,
+        fn=fn,
+        order=order,
+        when=when,
+        name=name,
+        description=description,
+    )
+
+
+__all__ = ["hook", "hook_spec"]

tigrbl/hook/types.py

@@ -0,0 +1,76 @@
+"""Hook type definitions for Tigrbl v3."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Awaitable, Callable, Literal, Tuple
+
+# ---------------------------------------------------------------------------
+# Runtime phases (align with runtime/executor.py)
+# ---------------------------------------------------------------------------
+
+
+class PHASE(str, Enum):
+    PRE_TX_BEGIN = "PRE_TX_BEGIN"
+    START_TX = "START_TX"
+    PRE_HANDLER = "PRE_HANDLER"
+    HANDLER = "HANDLER"
+    POST_HANDLER = "POST_HANDLER"
+    PRE_COMMIT = "PRE_COMMIT"
+    END_TX = "END_TX"
+    POST_COMMIT = "POST_COMMIT"
+    POST_RESPONSE = "POST_RESPONSE"
+    ON_ERROR = "ON_ERROR"
+    ON_PRE_TX_BEGIN_ERROR = "ON_PRE_TX_BEGIN_ERROR"
+    ON_START_TX_ERROR = "ON_START_TX_ERROR"
+    ON_PRE_HANDLER_ERROR = "ON_PRE_HANDLER_ERROR"
+    ON_HANDLER_ERROR = "ON_HANDLER_ERROR"
+    ON_POST_HANDLER_ERROR = "ON_POST_HANDLER_ERROR"
+    ON_PRE_COMMIT_ERROR = "ON_PRE_COMMIT_ERROR"
+    ON_END_TX_ERROR = "ON_END_TX_ERROR"
+    ON_POST_COMMIT_ERROR = "ON_POST_COMMIT_ERROR"
+    ON_POST_RESPONSE_ERROR = "ON_POST_RESPONSE_ERROR"
+    ON_ROLLBACK = "ON_ROLLBACK"
+
+
+HookPhase = Literal[
+    "PRE_TX_BEGIN",
+    "START_TX",
+    "PRE_HANDLER",
+    "HANDLER",
+    "POST_HANDLER",
+    "PRE_COMMIT",
+    "END_TX",
+    "POST_COMMIT",
+    "POST_RESPONSE",
+    "ON_ERROR",
+    "ON_PRE_TX_BEGIN_ERROR",
+    "ON_START_TX_ERROR",
+    "ON_PRE_HANDLER_ERROR",
+    "ON_HANDLER_ERROR",
+    "ON_POST_HANDLER_ERROR",
+    "ON_PRE_COMMIT_ERROR",
+    "ON_END_TX_ERROR",
+    "ON_POST_COMMIT_ERROR",
+    "ON_POST_RESPONSE_ERROR",
+    "ON_ROLLBACK",
+]
+
+PHASES: Tuple[HookPhase, ...] = tuple(p.value for p in PHASE)
+
+# ---------------------------------------------------------------------------
+# Hook function types
+# ---------------------------------------------------------------------------
+
+Ctx = Any
+StepFn = Callable[[Ctx], Awaitable[Any] | Any]
+HookPredicate = Callable[[Any], bool]
+
+__all__ = [
+    "PHASE",
+    "HookPhase",
+    "PHASES",
+    "Ctx",
+    "StepFn",
+    "HookPredicate",
+]

tigrbl/op/__init__.py

@@ -0,0 +1,50 @@
+"""Tigrbl v3 op package."""
+
+from __future__ import annotations
+
+from ._op import Op
+from .types import (
+    OpSpec,
+    OpHook,
+    TargetOp,
+    Arity,
+    PersistPolicy,
+    PHASE,
+    HookPhase,
+    PHASES,
+    VerbAliasPolicy,
+)
+from .resolver import resolve
+from .collect import apply_alias
+from .model_registry import (
+    OpspecRegistry,
+    get_registry,
+    register_ops,
+    get_registered_ops,
+    clear_registry,
+)
+from .decorators import alias, alias_ctx, op_alias, op_ctx
+
+__all__ = [
+    "Op",
+    "OpSpec",
+    "OpHook",
+    "TargetOp",
+    "Arity",
+    "PersistPolicy",
+    "PHASE",
+    "HookPhase",
+    "PHASES",
+    "VerbAliasPolicy",
+    "resolve",
+    "apply_alias",
+    "OpspecRegistry",
+    "get_registry",
+    "register_ops",
+    "get_registered_ops",
+    "clear_registry",
+    "alias",
+    "alias_ctx",
+    "op_alias",
+    "op_ctx",
+]

tigrbl/op/_op.py

@@ -0,0 +1,31 @@
+# tigrbl/tigrbl/v3/op/_op.py
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any
+
+from .types import OpSpec
+
+
+class Op(OpSpec):
+    """Declarative operation descriptor with optional engine binding."""
+
+    __slots__ = ()
+
+    def __set_name__(self, owner: type, name: str) -> None:  # noqa: D401
+        spec = self
+        alias = self.alias or name
+        if self.table is not owner or self.alias != alias:
+            spec = replace(self, table=owner, alias=alias)
+        ops = list(getattr(owner, "__tigrbl_ops__", ()) or [])
+        ops.append(spec)
+        owner.__tigrbl_ops__ = tuple(ops)
+
+    def install_engines(
+        self, *, api: Any | None = None, model: type | None = None
+    ) -> None:
+        from ..engine import install_from_objects
+
+        m = model if model is not None else self.table
+        if m is not None:
+            install_from_objects(api=api, models=[m])

tigrbl/op/canonical.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Type
+
+from ..config.constants import (
+    TIGRBL_DEFAULTS_EXCLUDE_ATTR,
+    TIGRBL_DEFAULTS_INCLUDE_ATTR,
+    TIGRBL_DEFAULTS_MODE_ATTR,
+)
+
+DEFAULT_CANON_VERBS = {
+    "create",
+    "read",
+    "update",
+    "replace",
+    "delete",
+    "list",
+    "clear",
+}
+
+
+def should_wire_canonical(table: Type, op: str) -> bool:
+    mode = getattr(table, TIGRBL_DEFAULTS_MODE_ATTR, "all")
+    inc = set(getattr(table, TIGRBL_DEFAULTS_INCLUDE_ATTR, set()))
+    exc = set(getattr(table, TIGRBL_DEFAULTS_EXCLUDE_ATTR, set()))
+    if mode == "none":
+        return False
+    if mode == "some":
+        return op in inc
+    allowed = (DEFAULT_CANON_VERBS | inc) - exc
+    return op in allowed  # mode == "all"

tigrbl/op/collect.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Dict
+
+
+def apply_alias(verb: str, alias_map: Dict[str, str]) -> str:
+    """Resolve canonical verb → alias (falls back to verb)."""
+    return alias_map.get(verb, verb)
+
+
+__all__ = ["apply_alias"]

tigrbl/op/decorators.py

@@ -0,0 +1,238 @@
+"""Operation-related decorators for Tigrbl v3."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, Optional, Sequence, Union
+
+from .types import OpSpec, Arity, TargetOp, PersistPolicy
+from ..schema.types import SchemaArg
+
+
+# ---------------------------------------------------------------------------
+# Utilities
+# ---------------------------------------------------------------------------
+
+
+def _unwrap(obj: Any) -> Callable[..., Any]:
+    """Get underlying function for (class|static)method; else return obj."""
+    if isinstance(obj, (classmethod, staticmethod)):
+        return obj.__func__  # type: ignore[attr-defined]
+    return obj
+
+
+def _ensure_cm(func: Any) -> Any:
+    """Ensure method is a classmethod so it receives (cls, ctx)."""
+    if isinstance(func, (classmethod, staticmethod)):
+        return func
+    return classmethod(func)
+
+
+def _maybe_await(v):
+    if inspect.isawaitable(v):
+        return v
+
+    async def _done():
+        return v
+
+    return _done()
+
+
+# ---------------------------------------------------------------------------
+# alias_ctx with optional rich overrides
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class AliasDecl:
+    alias: str
+    # Optional overrides (lazy-capable schema args are fine; resolved later)
+    request_schema: Optional[SchemaArg] = None
+    response_schema: Optional[SchemaArg] = None
+    persist: Optional[PersistPolicy] = None
+    arity: Optional[Arity] = None
+    rest: Optional[bool] = None
+
+
+def alias(name: str, **kw) -> AliasDecl:
+    """Convenience helper: alias('get', response_schema=..., rest=False)."""
+    return AliasDecl(alias=name, **kw)
+
+
+def alias_ctx(**verb_to_alias_or_decl: Union[str, AliasDecl]):
+    """Class decorator mapping canonical verbs → aliases with optional overrides."""
+
+    def deco(cls: type):
+        amap = dict(getattr(cls, "__tigrbl_aliases__", {}) or {})
+        overrides = dict(getattr(cls, "__tigrbl_alias_overrides__", {}) or {})
+
+        for canon, value in verb_to_alias_or_decl.items():
+            if isinstance(value, AliasDecl):
+                amap[canon] = value.alias
+                overrides[canon] = {
+                    "request_schema": value.request_schema,
+                    "response_schema": value.response_schema,
+                    "persist": value.persist,
+                    "arity": value.arity,
+                    "rest": value.rest,
+                }
+            elif isinstance(value, str):
+                amap[canon] = value
+            else:
+                raise TypeError(
+                    f"alias_ctx[{canon}] must be str or AliasDecl, got {type(value)}"
+                )
+
+        setattr(cls, "__tigrbl_aliases__", amap)
+        setattr(cls, "__tigrbl_alias_overrides__", overrides)
+        try:  # clear cached alias maps so late-applied decorators take effect
+            from .mro_collect import mro_alias_map_for
+
+            mro_alias_map_for.cache_clear()
+        except Exception:  # pragma: no cover - best effort
+            pass
+        return cls
+
+    return deco
+
+
+# ---------------------------------------------------------------------------
+# op_alias (class decorator): attach an OpSpec alias to the model
+# ---------------------------------------------------------------------------
+
+
+def op_alias(
+    *,
+    alias: str,
+    target: TargetOp,
+    arity: Arity | None = None,
+    persist: PersistPolicy = "default",
+    request_model: SchemaArg | None = None,
+    response_model: SchemaArg | None = None,
+    http_methods: Sequence[str] | None = None,
+    tags: Sequence[str] | None = None,
+    rbac_guard_op: TargetOp | None = None,
+):
+    """Class decorator to declare an alias for an operation."""
+
+    def deco(table_cls: type):
+        ops = list(getattr(table_cls, "__tigrbl_ops__", ()))
+        spec = OpSpec(
+            alias=alias,
+            target=target,
+            table=table_cls,
+            arity=arity or _infer_arity(target),
+            persist=_normalize_persist(persist),
+            request_model=request_model,
+            response_model=response_model,
+            http_methods=tuple(http_methods) if http_methods else None,
+            tags=tuple(tags or ()),
+            rbac_guard_op=rbac_guard_op,
+        )
+        ops.append(spec)
+        table_cls.__tigrbl_ops__ = tuple(ops)
+        return table_cls
+
+    return deco
+
+
+# ---------------------------------------------------------------------------
+# op_ctx (single path: target + arity) with schema overrides
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _OpDecl:
+    alias: Optional[str]
+    target: Optional[TargetOp]
+    arity: Optional[Arity]
+    rest: Optional[bool]
+    request_schema: Optional[SchemaArg]
+    response_schema: Optional[SchemaArg]
+    persist: Optional[PersistPolicy]
+    status_code: Optional[int]
+
+
+def op_ctx(
+    *,
+    bind: Any | Iterable[Any] | None = None,
+    alias: Optional[str] = None,
+    target: Optional[TargetOp] = None,
+    arity: Optional[Arity] = None,
+    rest: Optional[bool] = None,
+    request_schema: Optional[SchemaArg] = None,
+    response_schema: Optional[SchemaArg] = None,
+    persist: Optional[PersistPolicy] = None,
+    status_code: Optional[int] = None,
+):
+    """Declare a ctx-only operation whose body is `(cls, ctx)`."""
+
+    def deco(fn):
+        cm = _ensure_cm(fn)
+        f = _unwrap(cm)
+        f.__tigrbl_ctx_only__ = True
+        f.__tigrbl_op_decl__ = _OpDecl(
+            alias=alias,
+            target=target,
+            arity=arity,
+            rest=rest,
+            request_schema=request_schema,
+            response_schema=response_schema,
+            persist=persist,
+            status_code=status_code,
+        )
+
+        if bind is not None:
+            targets = (
+                bind
+                if isinstance(bind, Iterable) and not isinstance(bind, (str, bytes))
+                else [bind]
+            )
+            for obj in targets:
+                setattr(obj, f.__name__, cm)
+
+        return cm
+
+    return deco
+
+
+# ---------------------------------------------------------------------------
+# Collection helpers
+# ---------------------------------------------------------------------------
+
+_COLLECTION_VERBS = {
+    "create",
+    "list",
+    "bulk_create",
+    "bulk_update",
+    "bulk_replace",
+    "bulk_merge",
+    "bulk_delete",
+    "clear",
+    "merge",
+}
+
+
+def _infer_arity(target: str) -> str:
+    return "collection" if target in _COLLECTION_VERBS else "member"
+
+
+def _normalize_persist(p) -> str:
+    if p is None:
+        return "default"
+    p = str(p).lower()
+    if p in {"none", "skip", "read"}:
+        return "skip"
+    if p in {"append"}:
+        return "append"
+    if p in {"override"}:
+        return "override"
+    if p in {"prepend"}:
+        return "prepend"
+    if p in {"write", "default", "persist"}:
+        return "default"
+    return "default"
+
+
+__all__ = ["alias", "alias_ctx", "op_alias", "op_ctx"]