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

tigrbl/bindings/handlers/steps.py

@@ -0,0 +1,276 @@
+# tigrbl/v3/bindings/handlers/steps.py
+from __future__ import annotations
+import logging
+
+import inspect
+from functools import lru_cache
+from typing import Any, Callable, Mapping, Optional
+
+from ... import core as _core
+from ...op import OpSpec
+from ...op.types import StepFn
+from ...runtime.executor import _Ctx
+from .ctx import _ctx_db, _ctx_payload, _ctx_request
+from .identifiers import _resolve_ident
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/handlers/steps")
+
+
+async def _call_list_core(
+    fn: Callable[..., Any],
+    model: type,
+    payload: Mapping[str, Any],
+    ctx: Mapping[str, Any],
+):
+    filters = dict(payload) if isinstance(payload, Mapping) else {}
+    skip = filters.pop("skip", None)
+    limit = filters.pop("limit", None)
+    filters_arg = filters if filters else None
+
+    db = _ctx_db(ctx)
+    req = _ctx_request(ctx)
+
+    candidates: list[tuple[tuple, dict]] = []
+
+    def add_candidate(
+        use_pos_filters: bool, use_pos_db: bool, with_req: bool, with_pag: bool
+    ):
+        args: tuple = ()
+        kwargs: dict = {}
+        if use_pos_filters:
+            args += (filters_arg,)
+        else:
+            kwargs["filters"] = filters_arg
+        if use_pos_db:
+            args += (db,)
+        else:
+            kwargs["db"] = db
+        if with_req and req is not None:
+            kwargs["request"] = req
+        if with_pag:
+            if skip is not None:
+                kwargs["skip"] = skip
+            if limit is not None:
+                kwargs["limit"] = limit
+        candidates.append((args, kwargs))
+
+    add_candidate(False, False, True, True)
+    add_candidate(True, False, True, True)
+    add_candidate(True, True, True, True)
+
+    add_candidate(False, False, False, True)
+    add_candidate(True, False, False, True)
+    add_candidate(True, True, False, True)
+
+    add_candidate(False, False, True, False)
+    add_candidate(True, False, True, False)
+    add_candidate(True, True, True, False)
+
+    add_candidate(False, False, False, False)
+    add_candidate(True, False, False, False)
+    add_candidate(True, True, False, False)
+
+    last_err: Optional[BaseException] = None
+    for args, kwargs in candidates:
+        try:
+            logger.debug("Trying list core call with args=%s kwargs=%s", args, kwargs)
+            rv = fn(model, *args, **kwargs)
+            if inspect.isawaitable(rv):
+                logger.debug("Awaiting async result for list core")
+                return await rv
+            return rv
+        except TypeError as e:
+            logger.debug("Candidate failed with TypeError: %s", e)
+            last_err = e
+            continue
+    if last_err:
+        logger.debug("Reraising last TypeError from list core resolution")
+        raise last_err
+    raise RuntimeError("list() call resolution failed unexpectedly")
+
+
+def _accepted_kw(handler: Callable[..., Any]) -> set[str]:
+    try:
+        sig = inspect.signature(handler)
+    except Exception as exc:
+        logger.debug("Failed to inspect handler %r: %s", handler, exc)
+        return {"ctx"}
+
+    names: set[str] = set()
+    for p in sig.parameters.values():
+        if p.kind in (p.VAR_KEYWORD, p.VAR_POSITIONAL):
+            logger.debug("Handler %r accepts arbitrary params", handler)
+            return {"ctx", "db", "payload", "request", "model", "op", "spec", "alias"}
+        names.add(p.name)
+    logger.debug("Handler %r accepts keywords %s", handler, names)
+    return names
+
+
+def _wrap_custom(model: type, sp: OpSpec, user_handler: Callable[..., Any]) -> StepFn:
+    async def step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        payload = _ctx_payload(ctx)
+        request = _ctx_request(ctx)
+        isolated = _Ctx.ensure(request=request, db=db, seed=ctx)
+        bound = getattr(model, getattr(user_handler, "__name__", ""), user_handler)
+        wanted = _accepted_kw(bound)
+
+        kw = {}
+        if "ctx" in wanted:
+            kw["ctx"] = isolated
+        if "db" in wanted:
+            kw["db"] = db
+        if "payload" in wanted:
+            kw["payload"] = payload
+        if "request" in wanted:
+            kw["request"] = request
+        if "model" in wanted:
+            kw["model"] = model
+        if "op" in wanted:
+            kw["op"] = sp
+        if "spec" in wanted:
+            kw["spec"] = sp
+        if "alias" in wanted:
+            kw["alias"] = sp.alias
+        logger.debug("Calling custom handler %r with kw=%s", bound, kw)
+        rv = bound(**kw)  # type: ignore[misc]
+        if inspect.isawaitable(rv):
+            logger.debug("Awaiting async custom handler")
+            return await rv
+        return rv
+
+    step.__name__ = getattr(user_handler, "__name__", step.__name__)
+    step.__qualname__ = getattr(user_handler, "__qualname__", step.__name__)
+    step.__module__ = getattr(user_handler, "__module__", step.__module__)
+    return step
+
+
+@lru_cache(maxsize=None)
+def _wrap_core(model: type, target: str) -> StepFn:
+    logger.debug("Creating core wrapper for %s.%s", model.__name__, target)
+
+    async def create_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        payload = _ctx_payload(ctx)
+        logger.debug("Dispatching to core.create")
+        return await _core.create(model, payload, db=db)
+
+    async def read_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        ident = _resolve_ident(model, ctx)
+        logger.debug("Dispatching to core.read with ident=%r", ident)
+        return await _core.read(model, ident, db=db)
+
+    async def update_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        ident = _resolve_ident(model, ctx)
+        payload = _ctx_payload(ctx)
+        logger.debug("Dispatching to core.update with ident=%r", ident)
+        return await _core.update(model, ident, payload, db=db)
+
+    async def replace_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        ident = _resolve_ident(model, ctx)
+        payload = _ctx_payload(ctx)
+        logger.debug("Dispatching to core.replace with ident=%r", ident)
+        return await _core.replace(model, ident, payload, db=db)
+
+    async def merge_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        ident = _resolve_ident(model, ctx)
+        payload = _ctx_payload(ctx)
+        logger.debug("Dispatching to core.merge with ident=%r", ident)
+        return await _core.merge(model, ident, payload, db=db)
+
+    async def delete_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        ident = _resolve_ident(model, ctx)
+        logger.debug("Dispatching to core.delete with ident=%r", ident)
+        return await _core.delete(model, ident, db=db)
+
+    async def list_step(ctx: Any) -> Any:
+        payload = _ctx_payload(ctx)
+        logger.debug("Dispatching to core.list")
+        return await _call_list_core(_core.list, model, payload, ctx)
+
+    async def clear_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        logger.debug("Dispatching to core.clear")
+        return await _core.clear(model, {}, db=db)
+
+    async def bulk_create_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        payload = _ctx_payload(ctx)
+        logger.debug("Dispatching to core.bulk_create")
+        if not isinstance(payload, list):
+            raise TypeError("bulk_create expects a list payload")
+        return await _core.bulk_create(model, payload, db=db)
+
+    async def bulk_update_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        payload = _ctx_payload(ctx)
+        logger.debug("Dispatching to core.bulk_update")
+        if not isinstance(payload, list):
+            raise TypeError("bulk_update expects a list payload")
+        return await _core.bulk_update(model, payload, db=db)
+
+    async def bulk_replace_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        payload = _ctx_payload(ctx)
+        logger.debug("Dispatching to core.bulk_replace")
+        if not isinstance(payload, list):
+            raise TypeError("bulk_replace expects a list payload")
+        return await _core.bulk_replace(model, payload, db=db)
+
+    async def bulk_merge_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        payload = _ctx_payload(ctx)
+        logger.debug("Dispatching to core.bulk_merge")
+        if not isinstance(payload, list):
+            raise TypeError("bulk_merge expects a list payload")
+        return await _core.bulk_merge(model, payload, db=db)
+
+    async def bulk_delete_step(ctx: Any) -> Any:
+        db = _ctx_db(ctx)
+        payload = _ctx_payload(ctx)
+        logger.debug("Dispatching to core.bulk_delete")
+        ids = payload.get("ids") if isinstance(payload, Mapping) else []
+        return await _core.bulk_delete(model, ids, db=db)
+
+    async def default_step(ctx: Any) -> Any:
+        logger.debug("No core operation matched; returning payload")
+        return _ctx_payload(ctx)
+
+    steps: dict[str, StepFn] = {
+        "create": create_step,
+        "read": read_step,
+        "update": update_step,
+        "replace": replace_step,
+        "merge": merge_step,
+        "delete": delete_step,
+        "list": list_step,
+        "clear": clear_step,
+        "bulk_create": bulk_create_step,
+        "bulk_update": bulk_update_step,
+        "bulk_replace": bulk_replace_step,
+        "bulk_merge": bulk_merge_step,
+        "bulk_delete": bulk_delete_step,
+    }
+
+    step = steps.get(target, default_step)
+
+    fn = getattr(_core, target, None)
+    step.__name__ = getattr(fn, "__name__", step.__name__)
+    step.__qualname__ = getattr(fn, "__qualname__", step.__name__)
+    step.__module__ = getattr(fn, "__module__", step.__module__)
+    return step
+
+
+__all__ = [
+    "_call_list_core",
+    "_accepted_kw",
+    "_wrap_custom",
+    "_wrap_core",
+]

tigrbl/bindings/hooks.py

@@ -0,0 +1,311 @@
+# tigrbl/v3/bindings/hooks.py
+from __future__ import annotations
+
+import inspect
+import logging
+from types import SimpleNamespace
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    Tuple,
+)
+
+from ..op import OpSpec
+from ..hook import HookSpec
+from ..hook.types import PHASES, StepFn
+from ..config.constants import (
+    TIGRBL_API_HOOKS_ATTR,
+    TIGRBL_HOOKS_ATTR,
+    CTX_SKIP_PERSIST_FLAG,
+)
+
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/hooks")
+
+_Key = Tuple[str, str]  # (alias, target)
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Phase groupings (v2-compatible precedence)
+#   pre-like:    API → MODEL → OP
+#   post/error:  OP  → MODEL → API
+# ───────────────────────────────────────────────────────────────────────────────
+
+_PRE_LIKE = frozenset({"PRE_TX_BEGIN", "START_TX", "PRE_HANDLER", "PRE_COMMIT"})
+_POST_LIKE = frozenset({"POST_HANDLER", "POST_COMMIT", "POST_RESPONSE", "FINAL"})
+_ERROR_LIKE = frozenset(
+    {
+        "ON_ROLLBACK",
+        "ON_PRE_HANDLER_ERROR",
+        "ON_HANDLER_ERROR",
+        "ON_POST_HANDLER_ERROR",
+        "ON_PRE_COMMIT_ERROR",
+        # v3 uses END_TX; map v2's ON_COMMIT_ERROR → ON_END_TX_ERROR
+        "ON_END_TX_ERROR",
+        "ON_POST_COMMIT_ERROR",
+        "ON_POST_RESPONSE_ERROR",
+        "ON_ERROR",
+    }
+)
+
+
+def _is_pre_like(p: str) -> bool:
+    return p in _PRE_LIKE
+
+
+def _is_post_or_error(p: str) -> bool:
+    return p in _POST_LIKE or p in _ERROR_LIKE
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# ctx helpers
+# ───────────────────────────────────────────────────────────────────────────────
+
+
+def _ctx_get(ctx: Mapping[str, Any], key: str, default: Any = None) -> Any:
+    try:
+        return ctx[key]
+    except Exception:
+        return getattr(ctx, key, default)
+
+
+def _ctx_db(ctx: Mapping[str, Any]) -> Any:
+    return _ctx_get(ctx, "db")
+
+
+def _ctx_payload(ctx: Mapping[str, Any]) -> Mapping[str, Any]:
+    v = _ctx_get(ctx, "payload", None)
+    return v if v is not None else {}
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# System step helpers
+# ───────────────────────────────────────────────────────────────────────────────
+
+
+def _mark_skip_persist() -> StepFn:
+    async def _step(ctx: Any) -> None:
+        try:
+            ctx[CTX_SKIP_PERSIST_FLAG] = True
+        except Exception:
+            setattr(ctx, CTX_SKIP_PERSIST_FLAG, True)
+
+    _step.__name__ = "mark_skip_persist"
+    _step.__qualname__ = "mark_skip_persist"
+    return _step
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Step wrappers
+# ───────────────────────────────────────────────────────────────────────────────
+
+
+def _wrap_hook(h: HookSpec) -> StepFn:
+    fn = h.fn
+    pred = h.when
+
+    async def _step(ctx: Any) -> Any:
+        if pred is not None:
+            payload = _ctx_payload(ctx)
+
+            # Evaluate predicate without ever boolean-testing SQLAlchemy clauses.
+            def _as_bool(val: object) -> bool:
+                if isinstance(val, bool):
+                    return val
+                try:
+                    return bool(val)
+                except TypeError:
+                    # e.g., SQLAlchemy ClauseElement: no boolean value → treat as pass
+                    return True
+
+            try:
+                res = pred(payload)
+            except TypeError:
+                # Signature mismatch? Try with ctx.
+                try:
+                    res = pred(ctx)  # type: ignore[misc]
+                except Exception:
+                    res = True
+            except Exception:
+                res = True
+            if not _as_bool(res):
+                return None
+        # Pass the context explicitly as a keyword so wrapped hooks expecting a
+        # ``ctx`` parameter receive the correct seed.  Positional invocation
+        # treated the context as the first positional argument (often the
+        # ``value`` parameter), resulting in a new empty context being created
+        # inside the wrapper and missing executor-provided keys like
+        # ``response``.
+        rv = fn(ctx=ctx)
+        if inspect.isawaitable(rv):
+            return await rv
+        return rv
+
+    _step.__name__ = getattr(fn, "__name__", _step.__name__)
+    _step.__qualname__ = getattr(fn, "__qualname__", _step.__name__)
+    return _step
+
+
+def _wrap_step_fn(fn: Callable[..., Any]) -> StepFn:
+    async def _step(ctx: Any) -> Any:
+        # Similar to :func:`_wrap_hook`, pass the context as a keyword argument to
+        # support wrappers produced by ``@hook_ctx`` which expect ``ctx`` as a
+        # kw-only parameter.
+        rv = fn(ctx=ctx)
+        if inspect.isawaitable(rv):
+            return await rv
+        return rv
+
+    _step.__name__ = getattr(fn, "__name__", _step.__name__)
+    _step.__qualname__ = getattr(fn, "__qualname__", _step.__name__)
+    return _step
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Source collection (API / MODEL / OP) for a single alias
+# Accepted shapes for API/MODEL sources:
+#   • { phase: Iterable[callable] }                    (applies to all aliases)
+#   • { alias: { phase: Iterable[callable] } }         (per-alias)
+# ───────────────────────────────────────────────────────────────────────────────
+
+
+def _to_phase_map_for_alias(source: Any, alias: str) -> Dict[str, List[StepFn]]:
+    """
+    Normalize a user-provided hooks source to { phase: [StepFn, ...], ... } for the given alias.
+    """
+    out: Dict[str, List[StepFn]] = {}
+    if not source:
+        return out
+
+    maybe = None
+    if isinstance(source, Mapping):
+        if alias in source:
+            maybe = source.get(alias)
+        elif "*" in source:
+            maybe = source.get("*")
+        else:
+            maybe = source  # flat {phase: iterable}
+
+    if isinstance(maybe, Mapping):
+        for ph, items in (maybe or {}).items():
+            steps = out.setdefault(str(ph), [])
+            if isinstance(items, Iterable):
+                for fn in items:
+                    if callable(fn):
+                        steps.append(_wrap_step_fn(fn))
+    return out
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Precedence merge (API/MODEL/OP only; no imperative source)
+# ───────────────────────────────────────────────────────────────────────────────
+
+
+def _merge_for_phase(
+    phase: str,
+    *,
+    api_map: Mapping[str, List[StepFn]] | None,
+    model_map: Mapping[str, List[StepFn]] | None,
+    op_map: Mapping[str, List[StepFn]] | None,
+) -> List[StepFn]:
+    """
+    Merge lists from sources for one phase:
+      • pre-like  → API + MODEL + OP
+      • post/error→ OP + MODEL + API
+    """
+
+    def _get(m: Mapping[str, List[StepFn]] | None) -> List[StepFn]:
+        if not m:
+            return []
+        return list(m.get(phase, []) or [])
+
+    if _is_pre_like(phase):
+        return _get(api_map) + _get(model_map) + _get(op_map)
+    return _get(op_map) + _get(model_map) + _get(api_map)
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Alias namespace helper
+# ───────────────────────────────────────────────────────────────────────────────
+
+
+def _ensure_alias_hooks_ns(model: type, alias: str) -> SimpleNamespace:
+    root = getattr(model, "hooks", None)
+    if root is None:
+        root = SimpleNamespace()
+        setattr(model, "hooks", root)
+    ns = getattr(root, alias, None)
+    if ns is None:
+        ns = SimpleNamespace()
+        setattr(root, alias, ns)
+    # Ensure all known phases exist as lists
+    for ph in PHASES:
+        if not hasattr(ns, ph):
+            setattr(ns, ph, [])
+    return ns
+
+
+# ───────────────────────────────────────────────────────────────────────────────
+# Build / attach (with precedence)
+# ───────────────────────────────────────────────────────────────────────────────
+
+
+def _attach_one(model: type, sp: OpSpec) -> None:
+    alias = sp.alias
+    ns = _ensure_alias_hooks_ns(model, alias)
+
+    # Reset existing chains for a clean rebuild
+    for ph in PHASES:
+        setattr(ns, ph, [])
+
+    # Resolve source maps for this alias
+    api_src = getattr(model, TIGRBL_API_HOOKS_ATTR, None)
+    model_src = getattr(model, TIGRBL_HOOKS_ATTR, None)
+
+    api_map = _to_phase_map_for_alias(api_src, alias)
+    model_map = _to_phase_map_for_alias(model_src, alias)
+
+    # Op-level (from OpSpec.hooks)
+    op_map: Dict[str, List[StepFn]] = {}
+    for h in sp.hooks or ():
+        phase = str(h.phase)
+        op_map.setdefault(phase, []).append(_wrap_hook(h))
+
+    # Build per-phase chains via precedence merge
+    for ph in PHASES:
+        merged = _merge_for_phase(
+            ph, api_map=api_map, model_map=model_map, op_map=op_map
+        )
+
+        # Ephemeral operations: mark skip in PRE_TX_BEGIN
+        if sp.persist == "skip" and ph == "PRE_TX_BEGIN":
+            merged = [_mark_skip_persist()] + merged
+
+        setattr(ns, ph, merged)
+
+    logger.debug("hooks: %s.%s merged (persist=%s)", model.__name__, alias, sp.persist)
+
+
+def normalize_and_attach(
+    model: type, specs: Sequence[OpSpec], *, only_keys: Optional[Sequence[_Key]] = None
+) -> None:
+    """
+    Build sequential phase chains for each OpSpec and attach them to model.hooks.<alias>.
+    Sources merged per phase (in precedence order):
+      • PRE-like:   API → MODEL → OP
+      • POST/ERROR: OP  → MODEL → API
+    """
+    wanted = set(only_keys or ())
+    for sp in specs:
+        key = (sp.alias, sp.target)
+        if wanted and key not in wanted:
+            continue
+        _attach_one(model, sp)
+
+
+__all__ = ["normalize_and_attach"]