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

tigrbl/bindings/rest/collection.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import inspect
+import logging
+from types import SimpleNamespace
+from typing import (
+    Annotated,
+    Any,
+    Awaitable,
+    Callable,
+    Dict,
+    Mapping,
+    Sequence,
+    List as _List,
+    Union as _Union,
+)
+
+from .common import (
+    TIGRBL_AUTH_CONTEXT_ATTR,
+    BaseModel,
+    Body,
+    Depends,
+    Response,
+    OpSpec,
+    Path,
+    Request,
+    _coerce_parent_kw,
+    _get_phase_chains,
+    _make_list_query_dep,
+    _request_model_for,
+    _serialize_output,
+    _validate_body,
+    _validate_query,
+    _executor,
+    _status_for,
+)
+
+from .io_headers import _make_header_dep
+
+from ...runtime.executor.types import _Ctx
+
+
+logging.getLogger("uvicorn").debug("Loaded module v3/bindings/rest/collection")
+
+
+def _ctx(model, alias, target, request, db, payload, parent_kw, api):
+    ctx: Dict[str, Any] = {
+        "request": request,
+        "db": db,
+        "payload": payload,
+        "path_params": parent_kw,
+        # expose both API router and FastAPI app; runtime opview resolution
+        # relies on the app object, which must be hashable.
+        "api": api if api is not None else getattr(request, "app", None),
+        "app": getattr(request, "app", None),
+        "model": model,
+        "op": alias,
+        "method": alias,
+        "target": target,
+        "env": SimpleNamespace(
+            method=alias, params=payload, target=target, model=model
+        ),
+    }
+    ac = getattr(request.state, TIGRBL_AUTH_CONTEXT_ATTR, None)
+    if ac is not None:
+        ctx["auth_context"] = ac
+    return _Ctx(ctx)
+
+
+def _sig(nested_vars, extra):
+    params = [
+        inspect.Parameter(
+            nv,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            annotation=Annotated[str, Path(...)],
+        )
+        for nv in nested_vars
+    ]
+    params.extend(extra)
+    return inspect.Signature(params)
+
+
+def _list_ann(tp):
+    try:
+        return list[tp]  # type: ignore[valid-type]
+    except Exception:  # pragma: no cover - best effort
+        return _List[tp]  # type: ignore[name-defined]
+
+
+def _union(a, b):
+    try:
+        return a | b  # type: ignore[operator]
+    except Exception:  # pragma: no cover - best effort
+        return _Union[a, b]
+
+
+def _make_collection_endpoint(
+    model: type,
+    sp: OpSpec,
+    *,
+    resource: str,
+    db_dep: Callable[..., Any],
+    nested_vars: Sequence[str] | None = None,
+    api: Any | None = None,
+) -> Callable[..., Awaitable[Any]]:
+    alias, target, nested_vars = sp.alias, sp.target, list(nested_vars or [])
+    status_code = _status_for(sp)
+    hdr_dep = _make_header_dep(model, alias)
+
+    if target in {"list", "clear"}:
+        list_dep = _make_list_query_dep(model, alias) if target == "list" else None
+
+        async def _endpoint(
+            request: Request,
+            db: Any = Depends(db_dep),
+            h: Mapping[str, Any] = Depends(hdr_dep),
+            q: Mapping[str, Any] | None = None,
+            **kw: Any,
+        ):
+            parent_kw = {k: kw[k] for k in nested_vars if k in kw}
+            _coerce_parent_kw(model, parent_kw)
+            if q is not None:
+                query = {**dict(q), **parent_kw}
+                payload = _validate_query(model, alias, target, query)
+            else:
+                payload = dict(parent_kw)
+            if isinstance(h, Mapping):
+                payload = {**payload, **dict(h)}
+            ctx = _ctx(model, alias, target, request, db, payload, parent_kw, api)
+            ctx["response_serializer"] = lambda r: _serialize_output(
+                model, alias, target, sp, r
+            )
+            phases = _get_phase_chains(model, alias)
+            result = await _executor._invoke(
+                request=request, db=db, phases=phases, ctx=ctx
+            )
+            if isinstance(result, Response):
+                if sp.status_code is not None or result.status_code == 200:
+                    result.status_code = status_code
+                return result
+            return result
+
+        params = [
+            inspect.Parameter(
+                nv,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                annotation=Annotated[str, Path(...)],
+            )
+            for nv in nested_vars
+        ]
+        params.extend(
+            [
+                inspect.Parameter(
+                    "request",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Request,
+                ),
+                inspect.Parameter(
+                    "db",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[Any, Depends(db_dep)],
+                ),
+                inspect.Parameter(
+                    "h",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[Mapping[str, Any], Depends(hdr_dep)],
+                ),
+            ]
+        )
+        if target == "list":
+            params.append(
+                inspect.Parameter(
+                    "q",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[Mapping[str, Any], Depends(list_dep)],
+                )
+            )
+        _endpoint.__signature__ = inspect.Signature(params)
+    else:
+        body_model = _request_model_for(sp, model)
+        base = body_model or Mapping[str, Any]
+        if target.startswith("bulk_"):
+            alias_ns = getattr(
+                getattr(model, "schemas", None) or SimpleNamespace(), alias, None
+            )
+            item_model = getattr(alias_ns, "in_item", None) if alias_ns else None
+            body_annotation = (
+                _list_ann(item_model)
+                if isinstance(item_model, type) and issubclass(item_model, BaseModel)
+                else _list_ann(Mapping[str, Any])
+                if body_model is None
+                else base
+            )
+        elif target in {"create", "update", "replace", "merge"}:
+            body_annotation = _union(
+                base if body_model else Mapping[str, Any],
+                _list_ann(Mapping[str, Any]),
+            )
+        else:
+            body_annotation = base
+
+        async def _endpoint(
+            request: Request,
+            db: Any = Depends(db_dep),
+            h: Mapping[str, Any] = Depends(hdr_dep),
+            body=Body(...),
+            **kw: Any,
+        ):
+            parent_kw = {k: kw[k] for k in nested_vars if k in kw}
+            _coerce_parent_kw(model, parent_kw)
+            payload = _validate_body(model, alias, target, body)
+            if isinstance(h, Mapping):
+                if isinstance(payload, Mapping):
+                    payload = {**payload, **dict(h)}
+                else:
+                    payload = [{**dict(item), **dict(h)} for item in payload]
+            is_seq = (
+                target in {"create", "update", "replace", "merge"}
+                and isinstance(payload, Sequence)
+                and not isinstance(payload, Mapping)
+            )
+            exec_alias = f"bulk_{target}" if is_seq else alias
+            exec_target = f"bulk_{target}" if is_seq else target
+            if parent_kw:
+                if isinstance(payload, Mapping):
+                    payload = {**payload, **parent_kw}
+                else:
+                    payload = [{**dict(item), **parent_kw} for item in payload]
+            ctx = _ctx(
+                model, exec_alias, exec_target, request, db, payload, parent_kw, api
+            )
+
+            def _serializer(r, _ctx=ctx):
+                out = _serialize_output(model, exec_alias, exec_target, sp, r)
+                temp = getattr(_ctx, "temp", {}) if isinstance(_ctx, Mapping) else {}
+                extras = (
+                    temp.get("response_extras", {}) if isinstance(temp, Mapping) else {}
+                )
+                if isinstance(out, dict) and isinstance(extras, dict):
+                    out.update(extras)
+                return out
+
+            ctx["response_serializer"] = _serializer
+            phases = _get_phase_chains(model, exec_alias)
+            result = await _executor._invoke(
+                request=request, db=db, phases=phases, ctx=ctx
+            )
+            if isinstance(result, Response):
+                if sp.status_code is not None or result.status_code == 200:
+                    result.status_code = status_code
+                return result
+            return result
+
+        _endpoint.__signature__ = _sig(
+            nested_vars,
+            [
+                inspect.Parameter(
+                    "request",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Request,
+                ),
+                inspect.Parameter(
+                    "db",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[Any, Depends(db_dep)],
+                ),
+                inspect.Parameter(
+                    "h",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[Mapping[str, Any], Depends(hdr_dep)],
+                ),
+                inspect.Parameter(
+                    "body",
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=Annotated[body_annotation, Body(...)],
+                ),
+            ],
+        )
+        _endpoint.__annotations__["body"] = body_annotation
+
+    _endpoint.__name__ = f"rest_{model.__name__}_{alias}_collection"
+    _endpoint.__qualname__ = _endpoint.__name__
+    _endpoint.__doc__ = (
+        f"REST collection endpoint for {model.__name__}.{alias} ({target})"
+    )
+    return _endpoint

tigrbl/bindings/rest/common.py

@@ -0,0 +1,120 @@
+"""Shared interfaces for tigrbl.bindings.rest.
+
+This module re-exports helper utilities split across smaller modules to keep the
+import surface stable while easing maintenance.
+"""
+
+from __future__ import annotations
+import logging
+
+from pydantic import BaseModel
+
+from .fastapi import (
+    Body,
+    Depends,
+    HTTPException,
+    Path,
+    Query,
+    Request,
+    Response,
+    Router,
+    Security,
+    _status,
+)
+from .helpers import (
+    _Key,
+    _coerce_parent_kw,
+    _ensure_jsonable,
+    _get_phase_chains,
+    _pk_name,
+    _pk_names,
+    _req_state_db,
+    _resource_name,
+)
+from .io import (
+    _make_list_query_dep,
+    _optionalize_list_in_model,
+    _serialize_output,
+    _strip_optional,
+    _validate_body,
+    _validate_query,
+)
+from .routing import (
+    _DEFAULT_METHODS,
+    _RESPONSES_META,
+    _default_path_suffix,
+    _normalize_deps,
+    _normalize_secdeps,
+    _require_auth_header,
+    _requires_auth_header,
+    _path_for_spec,
+    _request_model_for,
+    _response_model_for,
+    _status_for,
+)
+from ...config.constants import (
+    TIGRBL_ALLOW_ANON_ATTR,
+    TIGRBL_AUTH_CONTEXT_ATTR,
+    TIGRBL_AUTH_DEP_ATTR,
+    TIGRBL_GET_DB_ATTR,
+    TIGRBL_REST_DEPENDENCIES_ATTR,
+)
+from ...op import OpSpec
+from ...op.types import CANON, PHASES
+from ...rest import _nested_prefix
+from ...runtime import executor as _executor
+from ...schema.builder import _strip_parent_fields
+
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/rest/common")
+
+__all__ = [
+    "Body",
+    "Depends",
+    "HTTPException",
+    "Path",
+    "Query",
+    "Request",
+    "Response",
+    "Router",
+    "Security",
+    "_status",
+    "BaseModel",
+    "OpSpec",
+    "CANON",
+    "PHASES",
+    "_executor",
+    "TIGRBL_GET_DB_ATTR",
+    "TIGRBL_AUTH_DEP_ATTR",
+    "TIGRBL_REST_DEPENDENCIES_ATTR",
+    "TIGRBL_ALLOW_ANON_ATTR",
+    "TIGRBL_AUTH_CONTEXT_ATTR",
+    "_nested_prefix",
+    "_strip_parent_fields",
+    "logger",
+    "_Key",
+    "_ensure_jsonable",
+    "_req_state_db",
+    "_resource_name",
+    "_pk_name",
+    "_pk_names",
+    "_get_phase_chains",
+    "_coerce_parent_kw",
+    "_serialize_output",
+    "_validate_body",
+    "_validate_query",
+    "_strip_optional",
+    "_make_list_query_dep",
+    "_optionalize_list_in_model",
+    "_normalize_deps",
+    "_normalize_secdeps",
+    "_require_auth_header",
+    "_requires_auth_header",
+    "_status_for",
+    "_RESPONSES_META",
+    "_DEFAULT_METHODS",
+    "_default_path_suffix",
+    "_path_for_spec",
+    "_response_model_for",
+    "_request_model_for",
+]

tigrbl/bindings/rest/fastapi.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+import logging
+
+from types import SimpleNamespace
+from typing import Callable, Sequence
+
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/rest/fastapi")
+
+try:
+    from ...types import (
+        Router,
+        Request,
+        Body,
+        Depends,
+        HTTPException,
+        Response,
+        Path,
+        Security,
+    )
+    from fastapi import Query
+    from fastapi import status as _status
+except Exception:  # pragma: no cover
+
+    class Router:  # type: ignore
+        def __init__(self, *a, **kw):
+            self.routes = []
+
+        def add_api_route(
+            self, path: str, endpoint: Callable, methods: Sequence[str], **opts
+        ):
+            self.routes.append((path, methods, endpoint, opts))
+
+    class Request:  # type: ignore
+        def __init__(self, scope=None):
+            self.scope = scope or {}
+            self.query_params = {}
+            self.state = SimpleNamespace()
+
+    def Body(default=None, **kw):  # type: ignore
+        return default
+
+    def Depends(fn):  # type: ignore
+        return fn
+
+    def Security(fn):  # type: ignore
+        return fn
+
+    def Query(default=None, **kw):  # type: ignore
+        return default
+
+    def Path(default=None, **kw):  # type: ignore
+        return default
+
+    class HTTPException(Exception):  # type: ignore
+        def __init__(self, status_code: int, detail: str | None = None):
+            super().__init__(detail)
+            self.status_code = status_code
+            self.detail = detail
+
+    class Response:  # type: ignore
+        def __init__(self, *a, **kw):
+            pass
+
+    class _status:  # type: ignore
+        HTTP_200_OK = 200
+        HTTP_201_CREATED = 201
+        HTTP_204_NO_CONTENT = 204
+        HTTP_400_BAD_REQUEST = 400
+        HTTP_401_UNAUTHORIZED = 401
+        HTTP_403_FORBIDDEN = 403
+        HTTP_404_NOT_FOUND = 404
+        HTTP_409_CONFLICT = 409
+        HTTP_422_UNPROCESSABLE_ENTITY = 422
+        HTTP_429_TOO_MANY_REQUESTS = 429
+        HTTP_500_INTERNAL_SERVER_ERROR = 500

tigrbl/bindings/rest/helpers.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+from typing import Any, Awaitable, Callable, Dict, Mapping, Sequence, Tuple
+
+from .fastapi import Request
+from ...op.types import PHASES
+
+try:
+    from ...runtime.kernel import build_phase_chains as _kernel_build_phase_chains  # type: ignore
+except Exception:  # pragma: no cover
+    _kernel_build_phase_chains = None  # type: ignore
+
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/rest/helpers")
+
+_Key = Tuple[str, str]  # (alias, target)
+
+
+def _ensure_jsonable(obj: Any) -> Any:
+    """Best-effort conversion of DB rows, row-mappings, or ORM objects to dicts."""
+    if isinstance(obj, (list, tuple)):
+        return [_ensure_jsonable(x) for x in obj]
+
+    if isinstance(obj, Mapping):
+        try:
+            return {k: _ensure_jsonable(v) for k, v in dict(obj).items()}
+        except Exception:  # pragma: no cover - fall back to original object
+            pass
+
+    try:
+        data = vars(obj)
+    except TypeError:
+        return obj
+
+    return {k: _ensure_jsonable(v) for k, v in data.items() if not k.startswith("_")}
+
+
+def _req_state_db(request: Request) -> Any:
+    return getattr(request.state, "db", None)
+
+
+def _resource_name(model: type) -> str:
+    """
+    Resource segment for HTTP paths/tags.
+
+    IMPORTANT: Never use table name here. Only allow an explicit __resource__
+    override or fall back to the model class name in lowercase.
+    """
+    override = getattr(model, "__resource__", None)
+    return override or model.__name__.lower()
+
+
+def _pk_name(model: type) -> str:
+    """
+    Single primary key name (fallback 'id'). For composite keys, still returns 'id'.
+    Used for backward-compat path-param aliasing and handler resolution.
+    """
+    table = getattr(model, "__table__", None)
+    if table is None:
+        return "id"
+    pk = getattr(table, "primary_key", None)
+    if pk is None:
+        return "id"
+    try:
+        cols = list(pk.columns)
+    except Exception:
+        return "id"
+    if len(cols) != 1:
+        return "id"
+    return getattr(cols[0], "name", "id")
+
+
+def _pk_names(model: type) -> set[str]:
+    """All PK column names (fallback {'id'})."""
+    table = getattr(model, "__table__", None)
+    try:
+        cols = getattr(getattr(table, "primary_key", None), "columns", None)
+        if cols is None:
+            return {"id"}
+        out = {getattr(c, "name", None) for c in cols}
+        out.discard(None)
+        return out or {"id"}
+    except Exception:
+        return {"id"}
+
+
+def _get_phase_chains(
+    model: type, alias: str
+) -> Dict[str, Sequence[Callable[..., Awaitable[Any]]]]:
+    """
+    Prefer building via runtime Kernel (atoms + system steps + hooks in one lifecycle).
+    Fallback: read the pre-built model.hooks.<alias> chains directly.
+    """
+    if _kernel_build_phase_chains is not None:
+        try:
+            return _kernel_build_phase_chains(model, alias)
+        except Exception:
+            logger.exception(
+                "Kernel build_phase_chains failed for %s.%s; falling back to hooks",
+                getattr(model, "__name__", model),
+                alias,
+            )
+    hooks_root = getattr(model, "hooks", None) or SimpleNamespace()
+    alias_ns = getattr(hooks_root, alias, None)
+    out: Dict[str, Sequence[Callable[..., Awaitable[Any]]]] = {}
+    for ph in PHASES:
+        out[ph] = list(getattr(alias_ns, ph, []) or [])
+    return out
+
+
+def _coerce_parent_kw(model: type, parent_kw: Dict[str, Any]) -> None:
+    for name, val in list(parent_kw.items()):
+        col = getattr(model, name, None)
+        try:
+            parent_kw[name] = col.type.python_type(val)  # type: ignore[attr-defined]
+        except Exception:
+            pass