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

tigrbl/bindings/api/include.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+from typing import Any, Dict, Sequence, Tuple
+
+from .common import (
+    ApiLike,
+    _default_prefix,
+    _ensure_api_ns,
+    _has_include_router,
+    _mount_router,
+    _resource_name,
+)
+from .resource_proxy import _ResourceProxy
+from .. import model as _binder
+from ...config.constants import (
+    TIGRBL_AUTH_DEP_ATTR,
+    TIGRBL_AUTHORIZE_ATTR,
+    TIGRBL_GET_DB_ATTR,
+    TIGRBL_REST_DEPENDENCIES_ATTR,
+    TIGRBL_RPC_DEPENDENCIES_ATTR,
+    TIGRBL_ALLOW_ANON_ATTR,
+)
+from ...engine import resolver as _resolver
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/api/include")
+
+
+# --- keep as helper, no behavior change to transports/kernel ---
+def _seed_security_and_deps(api: Any, model: type) -> None:
+    """
+    Copy API-level dependency hooks onto the model so downstream binders can use them.
+    - __tigrbl_get_db__             : DB dep (FastAPI Depends-compatible)
+    - __tigrbl_auth_dep__           : auth dependency (returns user or raises 401)
+    - __tigrbl_authorize__          : callable(request, model, alias, payload, user)→None/raise 403
+    - __tigrbl_rest_dependencies__  : list of extra dependencies for REST (e.g., rate-limits)
+    - __tigrbl_rpc_dependencies__   : list of extra dependencies for JSON-RPC router
+    """
+    # DB deps
+    prov = _resolver.resolve_provider(api=api)
+    if prov is not None:
+        logger.debug("Resolved provider for %s", model.__name__)
+        setattr(model, TIGRBL_GET_DB_ATTR, prov.get_db)
+    else:
+        logger.debug("No provider resolved for %s", model.__name__)
+
+    # Authn (prefer optional dep when available)
+    auth_dep = None
+    if getattr(api, "_optional_authn_dep", None):
+        auth_dep = api._optional_authn_dep
+        logger.debug("Using optional auth dependency for %s", model.__name__)
+    elif getattr(api, "_allow_anon", True) is False and getattr(api, "_authn", None):
+        auth_dep = api._authn
+        logger.debug("Using required auth dependency for %s", model.__name__)
+    elif getattr(api, "_authn", None):
+        auth_dep = api._authn
+        logger.debug("Using default auth dependency for %s", model.__name__)
+    if auth_dep is not None:
+        setattr(model, TIGRBL_AUTH_DEP_ATTR, auth_dep)
+    else:
+        logger.debug("No auth dependency configured for %s", model.__name__)
+
+    # Allow anonymous verbs
+    allow_attr = getattr(model, TIGRBL_ALLOW_ANON_ATTR, None)
+    if allow_attr:
+        verbs = allow_attr() if callable(allow_attr) else allow_attr
+        logger.debug("Allowing anonymous verbs %s for %s", verbs, model.__name__)
+        for v in verbs:
+            api._allow_anon_ops.add(f"{model.__name__}.{v}")
+    else:
+        logger.debug("No anonymous verbs for %s", model.__name__)
+
+    # Authz
+    if getattr(api, "_authorize", None):
+        setattr(model, TIGRBL_AUTHORIZE_ATTR, api._authorize)
+        logger.debug("Authorization hook attached for %s", model.__name__)
+    else:
+        logger.debug("No authorization hook for %s", model.__name__)
+
+    # Extra deps (router-level only; never part of kernel plan)
+    if getattr(api, "rest_dependencies", None):
+        setattr(model, TIGRBL_REST_DEPENDENCIES_ATTR, list(api.rest_dependencies))
+        logger.debug("REST dependencies seeded for %s", model.__name__)
+    else:
+        logger.debug("No REST dependencies for %s", model.__name__)
+    if getattr(api, "rpc_dependencies", None):
+        setattr(model, TIGRBL_RPC_DEPENDENCIES_ATTR, list(api.rpc_dependencies))
+        logger.debug("RPC dependencies seeded for %s", model.__name__)
+    else:
+        logger.debug("No RPC dependencies for %s", model.__name__)
+
+
+def _attach_to_api(api: ApiLike, model: type) -> None:
+    """
+    Attach the model’s bound namespaces to the api facade.
+    """
+    _ensure_api_ns(api)
+
+    mname = model.__name__
+    rname = _resource_name(model)
+    rtitle = rname[:1].upper() + rname[1:]
+    logger.debug("Attaching model %s as resource '%s'", mname, rname)
+
+    # Index model object
+    api.models[mname] = model
+    api.tables[mname] = getattr(model, "__table__", None)
+
+    # Direct references to model namespaces
+    setattr(api.schemas, mname, getattr(model, "schemas", SimpleNamespace()))
+    setattr(api.handlers, mname, getattr(model, "handlers", SimpleNamespace()))
+    setattr(api.hooks, mname, getattr(model, "hooks", SimpleNamespace()))
+    rpc_ns = getattr(model, "rpc", SimpleNamespace())
+    setattr(api.rpc, mname, rpc_ns)
+    if rtitle != mname:
+        setattr(api.rpc, rtitle, rpc_ns)
+        logger.debug("Registered RPC namespace alias '%s'", rtitle)
+    # rest (router lives on model.rest.router)
+    rest_ns = getattr(api, "rest")
+    setattr(
+        rest_ns,
+        mname,
+        SimpleNamespace(
+            router=getattr(getattr(model, "rest", SimpleNamespace()), "router", None)
+        ),
+    )
+    # also keep a flat routers dict for quick access
+    api.routers[mname] = getattr(
+        getattr(model, "rest", SimpleNamespace()), "router", None
+    )
+
+    # Table metadata (introspection only)
+    api.columns[mname] = tuple(getattr(model, "columns", ()))
+    api.table_config[mname] = dict(getattr(model, "table_config", {}) or {})
+
+    # Core helper proxies (now aware of API for DB resolution precedence)
+    core_proxy = _ResourceProxy(model, api=api)
+    setattr(api.core, mname, core_proxy)
+    if rtitle != mname:
+        setattr(api.core, rtitle, core_proxy)
+    core_raw_proxy = _ResourceProxy(model, serialize=False, api=api)
+    setattr(api.core_raw, mname, core_raw_proxy)
+    if rtitle != mname:
+        setattr(api.core_raw, rtitle, core_raw_proxy)
+
+
+def include_model(
+    api: ApiLike,
+    model: type,
+    *,
+    app: Any | None = None,
+    prefix: str | None = None,
+    mount_router: bool = True,
+) -> Tuple[type, Any]:
+    """
+    Bind a model (if not already bound), mount its REST router, and attach all namespaces to `api`.
+
+    Args:
+        api: An arbitrary facade object; we’ll attach containers onto it if missing.
+        model: The SQLAlchemy model (table class).
+        app: Optional FastAPI app or Router (anything with `include_router`).
+             Routers are always mounted on `api.router`; if provided, we also
+             mount onto this `app` (or `api.app` when not given).
+        prefix: Optional mount prefix. When None, defaults to `/{ModelClassName}` or
+                `/{__resource__}` if set on the model.
+        mount_router: If False, we skip mounting onto the host app but still bind
+            the router under `api.router`/`api.rest`/`api.routers`.
+
+    Returns:
+        (model, router) – the model class and its Router (or None if not present).
+    """
+    logger.debug("Including model %s", model.__name__)
+
+    # If another test or call disposed the SQLAlchemy registry, previously
+    # imported models lose their table mapping.  Re-map on demand so tests that
+    # run after a registry dispose still have working models.
+    if not hasattr(model, "__table__"):
+        try:  # pragma: no cover - defensive path exercised in tests
+            from ...table import Base
+            from ...table._base import _materialize_colspecs_to_sqla
+
+            # Recreate mapped_column attributes from ColumnSpecs then map
+            _materialize_colspecs_to_sqla(model)
+            Base.registry.map_declaratively(model)
+        except Exception:  # pragma: no cover
+            logger.debug("Failed to remap model %s", model.__name__, exc_info=True)
+
+    # 0) seed deps/security so binders can see them (transport-level only)
+    _seed_security_and_deps(api, model)
+
+    # 1) Build/bind model namespaces (idempotent)
+    _binder.bind(model, api=api)
+
+    # 2) Pick a router & mount prefix
+    router = getattr(getattr(model, "rest", SimpleNamespace()), "router", None)
+    if prefix is None:
+        prefix = _default_prefix(model)
+        logger.debug("Computed default prefix '%s' for %s", prefix, model.__name__)
+    else:
+        logger.debug("Using provided prefix '%s' for %s", prefix, model.__name__)
+
+    # 3) Always bind model router to the API object when possible
+    root_router = api if _has_include_router(api) else getattr(api, "router", None)
+    if router is not None:
+        logger.debug("Mounting model router for %s on api", model.__name__)
+        _mount_router(root_router, router, prefix=prefix)
+    else:
+        logger.debug("Model %s has no router to mount", model.__name__)
+
+    # Optionally mount onto a host app
+    target_app = app or getattr(api, "app", None)
+    if mount_router and router is not None:
+        logger.debug("Mounting router for %s on host app", model.__name__)
+        _mount_router(target_app, router, prefix=prefix)
+    else:
+        logger.debug(
+            "Skipping host app mount for %s (mount_router=%s, router=%s)",
+            model.__name__,
+            mount_router,
+            router is not None,
+        )
+
+    # 4) Attach all namespaces onto api
+    _attach_to_api(api, model)
+
+    logger.debug("bindings.api: included %s at prefix %s", model.__name__, prefix)
+    return model, router
+
+
+def include_models(
+    api: ApiLike,
+    models: Sequence[type],
+    *,
+    app: Any | None = None,
+    base_prefix: str | None = None,
+    mount_router: bool = True,
+) -> Dict[str, Any]:
+    """
+    Convenience helper to include multiple models.
+
+    If ``base_prefix`` is provided, each model's router is mounted under that
+    prefix. The model router itself already has its own `/{resource}` prefix.
+    """
+    logger.debug("Including %d models", len(models))
+    results: Dict[str, Any] = {}
+    for mdl in models:
+        px = base_prefix.rstrip("/") if base_prefix else None
+        logger.debug("Including model %s with base prefix %s", mdl.__name__, px)
+        _, router = include_model(
+            api, mdl, app=app, prefix=px, mount_router=mount_router
+        )
+        results[mdl.__name__] = router
+    logger.debug("Finished including models")
+    return results

tigrbl/bindings/api/resource_proxy.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+from typing import Any, Awaitable, Callable, Dict, Mapping, Optional
+
+from ..rpc import _coerce_payload, _get_phase_chains, _validate_input, _serialize_output
+from ...runtime import executor as _executor
+from ...engine import resolver as _resolver
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/api/resource_proxy")
+
+
+class _ResourceProxy:
+    """Dynamic proxy that executes core operations."""
+
+    __slots__ = ("_model", "_serialize", "_api")
+
+    def __init__(
+        self, model: type, *, serialize: bool = True, api: Any = None
+    ) -> None:  # pragma: no cover - trivial
+        self._model = model
+        self._serialize = serialize
+        self._api = api
+
+    def __repr__(self) -> str:  # pragma: no cover - debug helper
+        return f"<ResourceProxy {self._model.__name__}>"
+
+    def __getattr__(self, alias: str) -> Callable[..., Awaitable[Any]]:
+        logger.debug("Resolving core handler '%s' for %s", alias, self._model.__name__)
+        handlers_root = getattr(self._model, "handlers", None)
+        h_alias = getattr(handlers_root, alias, None) if handlers_root else None
+        if h_alias is None or not hasattr(h_alias, "core"):
+            logger.debug(
+                "No core handler '%s' found for %s", alias, self._model.__name__
+            )
+            raise AttributeError(f"{self._model.__name__} has no core method '{alias}'")
+
+        async def _call(
+            payload: Any = None,
+            *,
+            db: Any | None = None,
+            request: Any = None,
+            ctx: Optional[Dict[str, Any]] = None,
+        ) -> Any:
+            raw_payload = _coerce_payload(payload)
+            logger.debug(
+                "Calling %s.%s with payload %s",
+                self._model.__name__,
+                alias,
+                raw_payload,
+            )
+            if alias == "bulk_delete" and not isinstance(raw_payload, Mapping):
+                raw_payload = {"ids": raw_payload}
+                logger.debug("Coerced bulk_delete payload to mapping: %s", raw_payload)
+            norm_payload = _validate_input(self._model, alias, alias, raw_payload)
+            logger.debug(
+                "Validated payload for %s.%s: %s",
+                self._model.__name__,
+                alias,
+                norm_payload,
+            )
+
+            base_ctx: Dict[str, Any] = dict(ctx or {})
+            base_ctx.setdefault("payload", norm_payload)
+            if request is not None:
+                logger.debug("Request provided for %s.%s", self._model.__name__, alias)
+                base_ctx.setdefault("request", request)
+            # surface contextual metadata for runtime atoms
+            app_ref = getattr(request, "app", None) or base_ctx.get("app") or self._api
+            base_ctx.setdefault("app", app_ref)
+            base_ctx.setdefault("api", base_ctx.get("api") or self._api or app_ref)
+            base_ctx.setdefault("model", self._model)
+            base_ctx.setdefault("op", alias)
+            base_ctx.setdefault("method", alias)
+            base_ctx.setdefault("target", alias)
+            base_ctx.setdefault(
+                "env",
+                SimpleNamespace(
+                    method=alias, params=norm_payload, target=alias, model=self._model
+                ),
+            )
+            if self._serialize:
+                logger.debug(
+                    "Serialization enabled for %s.%s", self._model.__name__, alias
+                )
+                base_ctx.setdefault(
+                    "response_serializer",
+                    lambda r: _serialize_output(self._model, alias, alias, r),
+                )
+            else:
+                logger.debug(
+                    "Serialization disabled for %s.%s", self._model.__name__, alias
+                )
+                base_ctx.setdefault("response_serializer", lambda r: r)
+
+            # Acquire DB if one was not explicitly provided (op > model > api > app)
+            _release_db = None
+            if db is None:
+                try:
+                    logger.debug(
+                        "Acquiring DB for %s.%s via resolver",
+                        self._model.__name__,
+                        alias,
+                    )
+                    db, _release_db = _resolver.acquire(
+                        api=self._api, model=self._model, op_alias=alias
+                    )
+                except Exception:
+                    logger.exception(
+                        "DB acquire failed for %s.%s; no default configured?",
+                        self._model.__name__,
+                        alias,
+                    )
+                    raise
+            else:
+                logger.debug("Using provided DB for %s.%s", self._model.__name__, alias)
+
+            base_ctx.setdefault("db", db)
+            phases = _get_phase_chains(self._model, alias)
+            logger.debug(
+                "Executing phases %s for %s.%s", phases, self._model.__name__, alias
+            )
+            try:
+                return await _executor._invoke(
+                    request=request,
+                    db=db,
+                    phases=phases,
+                    ctx=base_ctx,
+                )
+            finally:
+                if _release_db is not None:
+                    try:
+                        _release_db()
+                        logger.debug(
+                            "Released DB for %s.%s", self._model.__name__, alias
+                        )
+                    except Exception:
+                        logger.debug(
+                            "Non-fatal: error releasing acquired DB session",
+                            exc_info=True,
+                        )
+
+        _call.__name__ = f"{self._model.__name__}.{alias}"
+        _call.__qualname__ = _call.__name__
+        _call.__doc__ = f"Helper for core call {self._model.__name__}.{alias}"
+        return _call

tigrbl/bindings/api/rpc.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+from typing import Any, Dict, Mapping, Optional, Union
+
+from .common import ApiLike, _ensure_api_ns
+from ...engine import resolver as _resolver
+from ...core.crud.helpers.model import _single_pk_name
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/api/rpc")
+
+
+async def rpc_call(
+    api: ApiLike,
+    model_or_name: Union[type, str],
+    method: str,
+    payload: Any = None,
+    *,
+    db: Any | None = None,
+    request: Any = None,
+    ctx: Optional[Dict[str, Any]] = None,
+) -> Any:
+    """
+    Call a registered RPC method by (model, method) pair.
+    `model_or_name` may be a model class or its name.
+    """
+    logger.debug("rpc_call invoked for model=%s method=%s", model_or_name, method)
+    _ensure_api_ns(api)
+
+    if isinstance(model_or_name, str):
+        mdl = api.models.get(model_or_name)
+        if mdl is None:
+            logger.debug("Unknown model name '%s'", model_or_name)
+            raise KeyError(f"Unknown model '{model_or_name}'")
+        logger.debug("Resolved model name '%s' to %s", model_or_name, mdl)
+    else:
+        mdl = model_or_name
+        logger.debug("Using model class %s", getattr(mdl, "__name__", mdl))
+
+    fn = getattr(getattr(mdl, "rpc", SimpleNamespace()), method, None)
+    if fn is None:
+        logger.debug(
+            "RPC method '%s' not found on %s", method, getattr(mdl, "__name__", mdl)
+        )
+        raise AttributeError(
+            f"{getattr(mdl, '__name__', mdl)} has no RPC method '{method}'"
+        )
+
+    # Acquire DB if not explicitly provided (op > model > api > app)
+    _release_db = None
+    if db is None:
+        try:
+            logger.debug(
+                "Acquiring DB for rpc_call %s.%s", getattr(mdl, "__name__", mdl), method
+            )
+            db, _release_db = _resolver.acquire(api=api, model=mdl, op_alias=method)
+        except Exception:
+            logger.exception(
+                "DB acquire failed for rpc_call %s.%s; no default configured?",
+                getattr(mdl, "__name__", mdl),
+                method,
+            )
+            raise
+    else:
+        logger.debug(
+            "Using provided DB for rpc_call %s.%s",
+            getattr(mdl, "__name__", mdl),
+            method,
+        )
+
+    # Ensure execution context contains basic runtime metadata. In tests or
+    # other direct calls there may be no ``request`` object to supply an app
+    # reference, which the runtime uses to resolve the opview. When absent, the
+    # kernel falls back to cached specs for the given model and alias.
+    ctx_dict: Dict[str, Any] = dict(ctx or {})
+    # Opportunistically derive path params from the payload when the caller
+    # supplies the primary key in the body. Many RPC handlers expect the
+    # identifier via ``ctx['path_params']`` (mirroring REST semantics), but
+    # test code invokes ``rpc_call`` directly with the id embedded in the
+    # payload.  Normalizing here preserves backwards compatibility and keeps
+    # default CRUD handlers happy.
+    if isinstance(payload, Mapping):
+        try:
+            pk_name = _single_pk_name(mdl)
+        except Exception:  # model may not be bound to a table
+            pk_name = None
+        if pk_name and pk_name in payload:
+            pp = dict(ctx_dict.get("path_params", {}))
+            pp.setdefault(pk_name, payload[pk_name])
+            ctx_dict["path_params"] = pp
+
+    try:
+        logger.debug("Executing rpc_call %s.%s", getattr(mdl, "__name__", mdl), method)
+        return await fn(payload, db=db, request=request, ctx=ctx_dict)
+    finally:
+        if _release_db is not None:
+            try:
+                _release_db()
+                logger.debug(
+                    "Released DB for rpc_call %s.%s",
+                    getattr(mdl, "__name__", mdl),
+                    method,
+                )
+            except Exception:
+                logger.debug(
+                    "Non-fatal: error releasing acquired DB session (rpc_call)",
+                    exc_info=True,
+                )

tigrbl/bindings/columns.py

@@ -0,0 +1,49 @@
+import logging
+
+# tigrbl/v3/bindings/columns.py
+from sqlalchemy import Column
+from ..specs import ColumnSpec, is_virtual
+
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/columns")
+
+
+def build_and_attach(model: type, specs=None, only_keys=None):
+    cols = {}
+    for name, attr in list(model.__dict__.items()):
+        if not isinstance(attr, ColumnSpec):
+            continue
+        if is_virtual(attr):
+            cols[name] = attr
+            continue
+
+        st = attr.storage
+        # Ensure type instantiation
+        col_type = st.type_
+        if isinstance(col_type, type):
+            # Special case UUID/Enum
+            if col_type.__name__ == "UUID":
+                col_type = col_type(as_uuid=True)
+            elif col_type.__name__ == "Enum":
+                raise RuntimeError("Use SAEnum(enum_cls) not bare Enum class")
+            else:
+                col_type = col_type()
+
+        col = Column(
+            col_type,
+            primary_key=st.primary_key,
+            nullable=st.nullable,
+            unique=st.unique,
+            index=st.index,
+            autoincrement=st.autoincrement,
+            default=st.default,
+            onupdate=st.onupdate,
+            server_default=st.server_default,
+            comment=st.comment,
+        )
+        setattr(model, name, col)
+        cols[name] = attr
+
+    # register map for later (your Key already has one, but ensure default)
+    if not hasattr(model, "__tigrbl_cols__"):
+        model.__tigrbl_cols__ = cols

tigrbl/bindings/handlers/__init__.py

@@ -0,0 +1,11 @@
+# tigrbl/v3/bindings/handlers/__init__.py
+from __future__ import annotations
+import logging
+
+from .builder import build_and_attach
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/handlers/__init__")
+
+__all__ = ["build_and_attach"]