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

tigrbl/app/tigrbl_app.py

@@ -0,0 +1,319 @@
+# tigrbl/v3/app/tigrbl_app.py
+from __future__ import annotations
+
+import copy
+from types import SimpleNamespace
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    Mapping,
+    Optional,
+    Sequence,
+    Tuple,
+)
+
+from ._app import App as _App
+from ..engine.engine_spec import EngineCfg
+from ..engine import resolver as _resolver
+from ..ddl import initialize as _ddl_initialize
+from ..bindings.api import (
+    include_model as _include_model,
+    include_models as _include_models,
+    rpc_call as _rpc_call,
+    _seed_security_and_deps,
+    _mount_router,
+    _default_prefix,
+    AttrDict,
+)
+from ..bindings.model import rebind as _rebind, bind as _bind
+from ..bindings.rest import build_router_and_attach as _build_router_and_attach
+from ..transport import mount_jsonrpc as _mount_jsonrpc
+from ..system import mount_diagnostics as _mount_diagnostics
+from ..op import get_registry, OpSpec
+from ._model_registry import initialize_model_registry
+
+
+# optional compat: legacy transactional decorator
+try:
+    from .compat.transactional import transactional as _txn_decorator
+except Exception:  # pragma: no cover
+    _txn_decorator = None
+
+
+class TigrblApp(_App):
+    """
+    Monolithic facade that owns:
+      • containers (models, schemas, handlers, hooks, rpc, rest, routers, columns, table_config, core proxies)
+      • model inclusion (REST + RPC wiring)
+      • JSON-RPC / diagnostics mounting
+      • (optional) legacy-friendly helpers (transactional decorator, auth flags)
+
+    It composes v3 primitives; you can still use the functions directly if you prefer.
+    """
+
+    TITLE = "TigrblApp"
+    VERSION = "0.1.0"
+    LIFESPAN = None
+    MIDDLEWARES: Sequence[Any] = ()
+    APIS: Sequence[Any] = ()
+    MODELS: Sequence[Any] = ()
+
+    # --- optional auth knobs recognized by some middlewares/dispatchers (kept for back-compat) ---
+    _authn: Any = None
+    _allow_anon: bool = True
+    _authorize: Any = None
+    _optional_authn_dep: Any = None
+    _allow_anon_ops: set[str] = set()
+
+    def __init__(
+        self,
+        *,
+        engine: EngineCfg | None = None,
+        jsonrpc_prefix: str = "/rpc",
+        system_prefix: str = "/system",
+        api_hooks: Mapping[str, Iterable[Callable]]
+        | Mapping[str, Mapping[str, Iterable[Callable]]]
+        | None = None,
+        **fastapi_kwargs: Any,
+    ) -> None:
+        title = fastapi_kwargs.pop("title", None)
+        if title is not None:
+            self.TITLE = title
+        version = fastapi_kwargs.pop("version", None)
+        if version is not None:
+            self.VERSION = version
+        lifespan = fastapi_kwargs.pop("lifespan", None)
+        if lifespan is not None:
+            self.LIFESPAN = lifespan
+        super().__init__(engine=engine, **fastapi_kwargs)
+        # capture initial routes so refreshes retain FastAPI defaults
+        self._base_routes = list(self.router.routes)
+        self.jsonrpc_prefix = jsonrpc_prefix
+        self.system_prefix = system_prefix
+
+        # public containers (mirrors used by bindings.api)
+        self.models = initialize_model_registry(getattr(self, "MODELS", ()))
+        self.schemas = SimpleNamespace()
+        self.handlers = SimpleNamespace()
+        self.hooks = SimpleNamespace()
+        self.rpc = SimpleNamespace()
+        self.rest = SimpleNamespace()
+        self.routers: Dict[str, Any] = {}
+        self.tables = AttrDict()
+        self.columns: Dict[str, Tuple[str, ...]] = {}
+        self.table_config: Dict[str, Dict[str, Any]] = {}
+        self.core = SimpleNamespace()
+        self.core_raw = SimpleNamespace()
+
+        # API-level hooks map (merged into each model at include-time; precedence handled in bindings.hooks)
+        self._api_hooks_map = copy.deepcopy(api_hooks) if api_hooks else None
+
+    # ------------------------- internal helpers -------------------------
+
+    @staticmethod
+    def _merge_api_hooks_into_model(model: type, hooks_map: Any) -> None:
+        """
+        Install API-level hooks on the model so the binder can see them.
+        Accepted shapes:
+            {phase: [fn, ...]}                           # global, all aliases
+            {alias: {phase: [fn, ...]}, "*": {...}}      # per-alias + wildcard
+        If the model already has __tigrbl_api_hooks__, we shallow-merge keys.
+        """
+        if not hooks_map:
+            return
+        existing = getattr(model, "__tigrbl_api_hooks__", None)
+        if existing is None:
+            setattr(model, "__tigrbl_api_hooks__", copy.deepcopy(hooks_map))
+            return
+
+        # shallow merge (alias or phase keys); values are lists we extend
+        merged = copy.deepcopy(existing)
+        for k, v in (hooks_map or {}).items():
+            if k not in merged:
+                merged[k] = copy.deepcopy(v)
+            else:
+                # when both are dicts, merge phase lists
+                if isinstance(v, Mapping) and isinstance(merged[k], Mapping):
+                    for ph, fns in v.items():
+                        merged[k].setdefault(ph, [])
+                        merged[k][ph] = list(merged[k][ph]) + list(fns or [])
+                else:
+                    # fallback: prefer model-local value, then append api-level
+                    if isinstance(merged[k], list):
+                        merged[k] = list(merged[k]) + list(v or [])
+                    else:
+                        merged[k] = v
+        setattr(model, "__tigrbl_api_hooks__", merged)
+
+    # ------------------------- primary operations -------------------------
+
+    def include_model(
+        self, model: type, *, prefix: str | None = None, mount_router: bool = True
+    ) -> Tuple[type, Any]:
+        """
+        Bind a model, mount its REST router, and attach all namespaces to this facade.
+        """
+        # inject API-level hooks so the binder merges them
+        self._merge_api_hooks_into_model(model, self._api_hooks_map)
+        return _include_model(self, model, prefix=prefix, mount_router=mount_router)
+
+    def include_models(
+        self,
+        models: Sequence[type],
+        *,
+        base_prefix: str | None = None,
+        mount_router: bool = True,
+    ) -> Dict[str, Any]:
+        for m in models:
+            self._merge_api_hooks_into_model(m, self._api_hooks_map)
+        return _include_models(
+            self,
+            models,
+            base_prefix=base_prefix,
+            mount_router=mount_router,
+        )
+
+    async def rpc_call(
+        self,
+        model_or_name: type | str,
+        method: str,
+        payload: Any = None,
+        *,
+        db: Any,
+        request: Any = None,
+        ctx: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        return await _rpc_call(
+            self, model_or_name, method, payload, db=db, request=request, ctx=ctx
+        )
+
+    # ------------------------- extras / mounting -------------------------
+
+    def mount_jsonrpc(self, *, prefix: str | None = None) -> Any:
+        """Mount JSON-RPC router onto this app."""
+        px = prefix if prefix is not None else self.jsonrpc_prefix
+        prov = _resolver.resolve_provider(api=self)
+        get_db = prov.get_db if prov else None
+        router = _mount_jsonrpc(
+            self,
+            self,
+            prefix=px,
+            get_db=get_db,
+        )
+        self._base_routes = list(self.router.routes)
+        return router
+
+    def attach_diagnostics(
+        self, *, prefix: str | None = None, app: Any | None = None
+    ) -> Any:
+        """Mount diagnostics router onto this app or the provided ``app``."""
+        px = prefix if prefix is not None else self.system_prefix
+        prov = _resolver.resolve_provider(api=self)
+        get_db = prov.get_db if prov else None
+        router = _mount_diagnostics(self, get_db=get_db)
+        include_self = getattr(self, "include_router", None)
+        if callable(include_self):
+            include_self(router, prefix=px)
+        if app is not None and app is not self:
+            include_other = getattr(app, "include_router", None)
+            if callable(include_other):
+                include_other(router, prefix=px)
+        if app is None:
+            self._base_routes = list(self.router.routes)
+        return router
+
+    # ------------------------- registry passthroughs -------------------------
+
+    def registry(self, model: type):
+        """Return the per-model OpspecRegistry."""
+        return get_registry(model)
+
+    def bind(self, model: type) -> Tuple[OpSpec, ...]:
+        """Bind/rebuild a model in place (without mounting)."""
+        self._merge_api_hooks_into_model(model, self._api_hooks_map)
+        return _bind(model)
+
+    def rebind(
+        self, model: type, *, changed_keys: Optional[set[tuple[str, str]]] = None
+    ) -> Tuple[OpSpec, ...]:
+        """Targeted rebuild of a bound model."""
+        return _rebind(model, changed_keys=changed_keys)
+
+    # ------------------------- legacy helpers -------------------------
+
+    def transactional(self, *dargs, **dkw):
+        """
+        Legacy-friendly decorator: @api.transactional(...)
+        Wraps a function as a v3 custom op with START_TX/END_TX.
+        """
+        if _txn_decorator is None:
+            raise RuntimeError("transactional decorator not available")
+        return _txn_decorator(self, *dargs, **dkw)
+
+    # Optional: let callers set auth knobs used by some middlewares/dispatchers
+    def set_auth(
+        self,
+        *,
+        authn: Any = None,
+        allow_anon: Optional[bool] = None,
+        authorize: Any = None,
+        optional_authn_dep: Any = None,
+    ) -> None:
+        if authn is not None:
+            self._authn = authn
+            if allow_anon is None:
+                allow_anon = False
+        if allow_anon is not None:
+            self._allow_anon = bool(allow_anon)
+        if authorize is not None:
+            self._authorize = authorize
+        if optional_authn_dep is not None:
+            self._optional_authn_dep = optional_authn_dep
+
+        # Refresh already-included models so routers pick up new auth settings
+        if self.models:
+            self._refresh_security()
+
+    def _refresh_security(self) -> None:
+        """Re-seed auth deps on models and rebuild routers."""
+        # Reset router to baseline and allow_anon ops cache
+        self.router.routes = list(self._base_routes)
+        self._allow_anon_ops = set()
+        for model in self.models.values():
+            _seed_security_and_deps(self, model)
+            specs = getattr(getattr(model, "opspecs", SimpleNamespace()), "all", ())
+            if specs:
+                _build_router_and_attach(model, list(specs))
+            router = getattr(getattr(model, "rest", SimpleNamespace()), "router", None)
+            if router is None:
+                continue
+            # update api-level references
+            mname = model.__name__
+            rest_ns = getattr(self.rest, mname, SimpleNamespace())
+            rest_ns.router = router
+            setattr(self.rest, mname, rest_ns)
+            self.routers[mname] = router
+            prefix = _default_prefix(model)
+            _mount_router(self, router, prefix=prefix)
+
+    def _collect_tables(self):
+        # dedupe; handle multiple DeclarativeBases (multiple metadatas)
+        seen = set()
+        tables = []
+        for m in self.models.values():
+            t = getattr(m, "__table__", None)
+            if t is not None and not t.columns:
+                continue
+            if t is not None and t not in seen:
+                seen.add(t)
+                tables.append(t)
+        return tables
+
+    initialize = _ddl_initialize
+
+    # ------------------------- repr -------------------------
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<TigrblApp models={list(self.models)} rpc={list(getattr(self.rpc, '__dict__', {}).keys())}>"

tigrbl/bindings/__init__.py

@@ -0,0 +1,73 @@
+# tigrbl/v3/bindings/__init__.py
+"""
+Tigrbl v3 – Bindings package.
+
+This package wires OpSpec-derived artifacts onto models and an API facade.
+Concerns are kept strictly separated:
+  • Security deps & extra deps → transport/router only (REST/RPC)
+  • System steps → injected by runtime lifecycle (Kernel), not by bindings
+  • Atoms → discovered/injected by runtime, not by bindings
+  • Hooks → bindable at API / model / op levels (no imperative hooks)
+
+Public surface (re-exports)
+
+Model binding:
+  - bind(model, *, only_keys=None)           → builds/refreshes model namespaces
+  - rebind(model, *, changed_keys=None)      → targeted refresh
+
+Per-concern builders:
+  - build_schemas(model, specs, *, only_keys=None)
+      • Seeds schemas declared via @schema_ctx before computing defaults.
+      • Supports overrides via SchemaRef("alias","in|out"), "alias.in"/"alias.out", or "raw".
+  - build_hooks(model, specs, *, only_keys=None)
+      • Merges API → MODEL → OP for pre-like phases; OP → MODEL → API for post/error.
+      • No imperative hook source.
+  - build_handlers(model, specs, *, only_keys=None)
+      • Inserts the core/raw step into the HANDLER phase (other phases handled by runtime).
+  - register_rpc(model, specs, *, only_keys=None)
+  - build_rest(model, specs, *, only_keys=None)
+      • Router-level only; serializes responses iff a response schema exists.
+
+API integration:
+  - include_model(api, model, *, app=None, prefix=None, mount_router=True)
+  - include_models(api, models, *, app=None, base_prefix=None, mount_router=True)
+  - rpc_call(api, model_or_name, method, payload=None, *, db, request=None, ctx=None)
+"""
+
+from __future__ import annotations
+import logging
+
+# Core model orchestrator
+from .model import bind, rebind
+
+# Per-concern builders (aliased for a clean public API)
+from .schemas import build_and_attach as build_schemas
+from .hooks import normalize_and_attach as build_hooks
+from .handlers import build_and_attach as build_handlers
+from .rpc import register_and_attach as register_rpc
+from .rest import build_router_and_attach as build_rest
+from ..response.bind import bind as bind_response
+
+# API facade integration
+from .api import include_model, include_models, rpc_call
+
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/__init__")
+
+
+__all__ = [
+    # model orchestrator
+    "bind",
+    "rebind",
+    # per-concern builders
+    "build_schemas",
+    "build_hooks",
+    "build_handlers",
+    "register_rpc",
+    "build_rest",
+    "bind_response",
+    # api integration
+    "include_model",
+    "include_models",
+    "rpc_call",
+]

tigrbl/bindings/api/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+import logging
+
+from .common import AttrDict, _default_prefix, _mount_router  # noqa: F401
+from .include import include_model, include_models, _seed_security_and_deps  # noqa: F401
+from .rpc import rpc_call
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/api/__init__")
+
+__all__ = ["include_model", "include_models", "rpc_call"]

tigrbl/bindings/api/common.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+from typing import Any
+
+logging.getLogger("uvicorn").setLevel(logging.DEBUG)
+logger = logging.getLogger("uvicorn")
+logger.debug("Loaded module v3/bindings/api/common")
+
+
+class AttrDict(dict):
+    """Dictionary providing attribute-style access."""
+
+    def __getattr__(self, item: str) -> Any:  # pragma: no cover - trivial
+        try:
+            return self[item]
+        except KeyError as e:  # pragma: no cover - debug aid
+            raise AttributeError(item) from e
+
+    def __setattr__(self, key: str, value: Any) -> None:  # pragma: no cover - trivial
+        self[key] = value
+
+
+# Public type for the API facade object users pass to include_model(...)
+ApiLike = Any
+
+
+def _resource_name(model: type) -> str:
+    """
+    Compute the API resource segment.
+
+    Policy:
+      - Prefer explicit `__resource__` when present (caller-controlled).
+      - Otherwise, use the model *class name* in lowercase.
+      - DO NOT use `__tablename__` here (strictly DB-only per project policy).
+    """
+    if hasattr(model, "__resource__"):
+        resource = model.__resource__
+        logger.debug("Using explicit resource '%s' for %s", resource, model.__name__)
+    else:
+        resource = model.__name__.lower()
+        logger.debug("Derived resource '%s' for %s", resource, model.__name__)
+    return resource
+
+
+def _default_prefix(model: type) -> str:
+    """Default mount prefix for a model router.
+
+    Historically routers were mounted under ``/{resource}``, resulting in
+    duplicated path segments such as ``/item/item``.  To expose REST endpoints
+    under ``/item`` we now mount routers at the application root by default.
+    """
+    logger.debug("Default prefix for %s is root '/'", model.__name__)
+    return ""
+
+
+def _has_include_router(obj: Any) -> bool:
+    has_router = hasattr(obj, "include_router") and callable(
+        getattr(obj, "include_router")
+    )
+    logger.debug("Object %s has include_router: %s", obj, has_router)
+    return has_router
+
+
+def _mount_router(app_or_router: Any, router: Any, *, prefix: str) -> None:
+    """
+    Best-effort mount onto a FastAPI app or Router.
+    If not available, we still attach router under api.routers for later use.
+    """
+    if app_or_router is None:
+        logger.debug("No app/router; skipping mount for prefix %s", prefix)
+        return
+    try:
+        if _has_include_router(app_or_router):
+            logger.debug("Mounting router %s at prefix %s", router, prefix)
+            app_or_router.include_router(router, prefix=prefix)  # FastAPI / Router
+        else:
+            logger.debug(
+                "Provided object %s lacks include_router; not mounting router",
+                app_or_router,
+            )
+    except Exception:
+        logger.exception("Failed to mount router at %s", prefix)
+
+
+def _ensure_api_ns(api: ApiLike) -> None:
+    """
+    Ensure containers exist on the api facade object.
+    """
+    for attr, default in (
+        ("models", {}),
+        ("tables", AttrDict()),
+        ("schemas", SimpleNamespace()),
+        ("handlers", SimpleNamespace()),
+        ("hooks", SimpleNamespace()),
+        ("rpc", SimpleNamespace()),
+        ("rest", SimpleNamespace()),
+        ("routers", {}),
+        ("columns", {}),
+        ("table_config", {}),
+        ("core", SimpleNamespace()),  # helper method proxies
+        ("core_raw", SimpleNamespace()),
+    ):
+        if not hasattr(api, attr):
+            setattr(api, attr, default)
+            logger.debug("Initialized api.%s", attr)
+        else:
+            logger.debug("api already has attribute %s", attr)