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

tigrbl/api/tigrbl_api.py

@@ -0,0 +1,291 @@
+# tigrbl/v3/api/tigrbl_api.py
+from __future__ import annotations
+
+import copy
+from types import SimpleNamespace
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    Mapping,
+    Optional,
+    Sequence,
+    Tuple,
+)
+
+from ._api import Api as _Api
+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 ..app._model_registry import initialize_model_registry
+
+
+class TigrblApi(_Api):
+    """
+    Canonical router-focused 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) auth knobs recognized by some middlewares/dispatchers
+
+    It composes v3 primitives; you can still use the functions directly if you prefer.
+    """
+
+    PREFIX = ""
+    TAGS: 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,
+        **router_kwargs: Any,
+    ) -> None:
+        _Api.__init__(self, engine=engine, **router_kwargs)
+        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, app=None, 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,
+            app=None,
+            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 a JSON-RPC router onto this TigrblApi instance."""
+        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,
+        )
+        return router
+
+    def attach_diagnostics(
+        self, *, prefix: str | None = None, app: Any | None = None
+    ) -> Any:
+        """Mount a diagnostics router onto this TigrblApi instance or ``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)
+        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)
+
+    # 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 routes and allow_anon ops cache
+        self.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
+        models = list(getattr(self, "models", {}))
+        rpc_ns = getattr(self, "rpc", None)
+        rpc_keys = list(getattr(rpc_ns, "__dict__", {}).keys()) if rpc_ns else []
+        return f"<TigrblApi models={models} rpc={rpc_keys}>"

tigrbl/app/_app.py

@@ -0,0 +1,86 @@
+# tigrbl/tigrbl/v3/app/_app.py
+from __future__ import annotations
+from typing import Any
+
+from ..deps.fastapi import FastAPI
+from ..engine.engine_spec import EngineCfg
+from ..engine import resolver as _resolver
+from ..engine import install_from_objects
+from ..ddl import initialize as _ddl_initialize
+from ._model_registry import initialize_model_registry
+from .app_spec import AppSpec
+
+
+class App(AppSpec, FastAPI):
+    def __init__(
+        self, *, engine: EngineCfg | None = None, **fastapi_kwargs: Any
+    ) -> None:
+        # Manually mirror ``AppSpec`` fields so the dataclass-generated ``repr``
+        # and friends have expected attributes while runtime structures remain
+        # mutable dictionaries or lists as needed.
+        self.title = self.TITLE
+        self.version = self.VERSION
+        self.engine = engine if engine is not None else getattr(self, "ENGINE", None)
+        self.apis = tuple(getattr(self, "APIS", ()))
+        self.ops = tuple(getattr(self, "OPS", ()))
+        # Runtime registries use mutable containers (dict/namespace), but the
+        # dataclass fields expect sequences. Storing a dict here satisfies both.
+        self.models = initialize_model_registry(getattr(self, "MODELS", ()))
+        self.schemas = tuple(getattr(self, "SCHEMAS", ()))
+        self.hooks = tuple(getattr(self, "HOOKS", ()))
+        self.security_deps = tuple(getattr(self, "SECURITY_DEPS", ()))
+        self.deps = tuple(getattr(self, "DEPS", ()))
+        self.response = getattr(self, "RESPONSE", None)
+        self.jsonrpc_prefix = getattr(self, "JSONRPC_PREFIX", "/rpc")
+        self.system_prefix = getattr(self, "SYSTEM_PREFIX", "/system")
+        self.middlewares = tuple(getattr(self, "MIDDLEWARES", ()))
+        self.lifespan = self.LIFESPAN
+
+        FastAPI.__init__(
+            self,
+            title=self.title,
+            version=self.version,
+            lifespan=self.lifespan,
+            **fastapi_kwargs,
+        )
+        _engine_ctx = self.engine
+        if _engine_ctx is not None:
+            _resolver.set_default(_engine_ctx)
+            _resolver.resolve_provider()
+        for mw in getattr(self, "MIDDLEWARES", []):
+            self.add_middleware(mw.__class__, **getattr(mw, "kwargs", {}))
+
+    def install_engines(
+        self, *, api: Any = None, models: tuple[Any, ...] | None = None
+    ) -> None:
+        # If class declared APIS/MODELS, use them unless explicit args are passed.
+        apis = (api,) if api is not None else self.APIS
+        models = models if models is not None else self.MODELS
+        if apis:
+            for a in apis:
+                install_from_objects(app=self, api=a, models=models)
+        else:
+            install_from_objects(app=self, api=None, models=models)
+
+    def _collect_tables(self) -> list[Any]:
+        seen = set()
+        tables = []
+        for model in self.models.values():
+            if not hasattr(model, "__table__"):
+                try:  # pragma: no cover - defensive remap
+                    from ..table import Base
+                    from ..table._base import _materialize_colspecs_to_sqla
+
+                    _materialize_colspecs_to_sqla(model)
+                    Base.registry.map_declaratively(model)
+                except Exception:
+                    pass
+            table = getattr(model, "__table__", None)
+            if table is not None and not table.columns:
+                continue
+            if table is not None and table not in seen:
+                seen.add(table)
+                tables.append(table)
+        return tables
+
+    initialize = _ddl_initialize

tigrbl/app/_model_registry.py

@@ -0,0 +1,41 @@
+"""Utilities for initializing model registries on App and API facades."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+
+def initialize_model_registry(models: Iterable[Any]) -> dict[str, Any]:
+    """Build the default ``models`` mapping for an App or Api instance.
+
+    ``defineAppSpec``/``defineApiSpec`` allow authors to declare default models
+    using bare model classes or ``("alias", Model)`` tuples.  Runtime facades,
+    however, expect ``self.models`` to be a dictionary keyed by model name so
+    that lookups like ``app.models["Widget"]`` Just Work.
+
+    This helper normalizes the declared sequence into that dictionary shape and
+    preserves declaration order.  When an alias is provided we register both the
+    alias and the model's ``__name__`` so either lookup style succeeds.
+    """
+
+    registry: dict[str, Any] = {}
+
+    for entry in models or ():
+        # Support ``("Alias", Model)`` declarations in addition to bare models.
+        if isinstance(entry, tuple) and len(entry) == 2 and isinstance(entry[0], str):
+            alias, model = entry
+            registry[alias] = model
+            model_name = getattr(model, "__name__", alias)
+            registry.setdefault(model_name, model)
+            continue
+
+        model = entry
+        model_name = getattr(model, "__name__", None)
+        if model_name is None:
+            model_name = str(model)
+        registry[model_name] = model
+
+    return registry
+
+
+__all__ = ["initialize_model_registry"]

tigrbl/app/app_spec.py

@@ -0,0 +1,42 @@
+# tigrbl/tigrbl/v3/app/app_spec.py
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Sequence
+
+from ..engine.engine_spec import EngineCfg
+from ..response.types import ResponseSpec
+
+
+@dataclass(eq=False)
+class AppSpec:
+    """
+    Used to *produce an App subclass* via App.from_spec().
+    """
+
+    title: str = "Tigrbl"
+    version: str = "0.1.0"
+    engine: Optional[EngineCfg] = None
+
+    # NEW: multi-API composition (store API classes or instances)
+    apis: Sequence[Any] = field(default_factory=tuple)
+
+    # NEW: orchestration/topology knobs
+    ops: Sequence[Any] = field(default_factory=tuple)  # op descriptors or specs
+    models: Sequence[Any] = field(default_factory=tuple)  # ORM classes
+    schemas: Sequence[Any] = field(default_factory=tuple)  # schema classes/defs
+    hooks: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+
+    # security/dep stacks (FastAPI dependencies or callables)
+    security_deps: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+    deps: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+
+    # response defaults
+    response: Optional[ResponseSpec] = None
+
+    # system routing prefixes (REST/JSON-RPC namespaces)
+    jsonrpc_prefix: str = "/rpc"
+    system_prefix: str = "/system"
+
+    # optional framework bits
+    middlewares: Sequence[Any] = field(default_factory=tuple)
+    lifespan: Optional[Callable[..., Any]] = None

tigrbl/app/mro_collect.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Any, Tuple
+
+from .app_spec import AppSpec
+
+logger = logging.getLogger("uvicorn")
+
+
+def _merge_seq_attr(app: type, attr: str) -> Tuple[Any, ...]:
+    values: list[Any] = []
+    for base in reversed(app.__mro__):
+        seq = getattr(base, attr, ()) or ()
+        try:
+            values.extend(seq)
+        except TypeError:  # non-iterable
+            values.append(seq)
+    return tuple(values)
+
+
+@lru_cache(maxsize=None)
+def mro_collect_app_spec(app: type) -> AppSpec:
+    """Collect AppSpec-like declarations across the app's MRO."""
+    logger.info("Collecting app spec for %s", app.__name__)
+
+    title = "Tigrbl"
+    version = "0.1.0"
+    engine: Any | None = None
+    response = None
+    jsonrpc_prefix = "/rpc"
+    system_prefix = "/system"
+    lifespan = None
+
+    for base in reversed(app.__mro__):
+        title = getattr(base, "TITLE", title)
+        version = getattr(base, "VERSION", version)
+        eng = getattr(base, "ENGINE", None)
+        if eng is not None:
+            engine = eng
+        response = getattr(base, "RESPONSE", response)
+        jsonrpc_prefix = getattr(base, "JSONRPC_PREFIX", jsonrpc_prefix)
+        system_prefix = getattr(base, "SYSTEM_PREFIX", system_prefix)
+        lifespan = getattr(base, "LIFESPAN", lifespan)
+
+    spec = AppSpec(
+        title=title,
+        version=version,
+        engine=engine,
+        apis=_merge_seq_attr(app, "APIS"),
+        ops=_merge_seq_attr(app, "OPS"),
+        models=_merge_seq_attr(app, "MODELS"),
+        schemas=_merge_seq_attr(app, "SCHEMAS"),
+        hooks=_merge_seq_attr(app, "HOOKS"),
+        security_deps=_merge_seq_attr(app, "SECURITY_DEPS"),
+        deps=_merge_seq_attr(app, "DEPS"),
+        response=response,
+        jsonrpc_prefix=jsonrpc_prefix,
+        system_prefix=system_prefix,
+        middlewares=_merge_seq_attr(app, "MIDDLEWARES"),
+        lifespan=lifespan,
+    )
+    return spec
+
+
+__all__ = ["mro_collect_app_spec"]

tigrbl/app/shortcuts.py

@@ -0,0 +1,65 @@
+# tigrbl/tigrbl/v3/app/shortcuts.py
+from __future__ import annotations
+
+from typing import Any, Sequence, Type
+
+from .app_spec import AppSpec
+from ._app import App
+
+
+def defineAppSpec(
+    *,
+    title: str = "Tigrbl",
+    version: str = "0.1.0",
+    engine: Any = None,
+    # composition
+    apis: Sequence[Any] = (),
+    ops: Sequence[Any] = (),
+    models: Sequence[Any] = (),
+    schemas: Sequence[Any] = (),
+    hooks: Sequence[Any] = (),
+    # deps & security
+    security_deps: Sequence[Any] = (),
+    deps: Sequence[Any] = (),
+    # prefixes
+    jsonrpc_prefix: str = "/rpc",
+    system_prefix: str = "/system",
+    # framework bits
+    middlewares: Sequence[Any] = (),
+    lifespan: Any = None,
+) -> Type[AppSpec]:
+    """
+    Build an App-spec class with class attributes only (no instances).
+    Use it directly in your class MRO:
+
+        class MyApp(defineAppSpec(title="Svc", engine=...)):
+            pass
+
+    or pass it to `deriveApp(...)` to get a concrete App subclass.
+    """
+    attrs = dict(
+        TITLE=title,
+        VERSION=version,
+        ENGINE=engine,
+        APIS=tuple(apis or ()),
+        OPS=tuple(ops or ()),
+        MODELS=tuple(models or ()),
+        SCHEMAS=tuple(schemas or ()),
+        HOOKS=tuple(hooks or ()),
+        SECURITY_DEPS=tuple(security_deps or ()),
+        DEPS=tuple(deps or ()),
+        JSONRPC_PREFIX=jsonrpc_prefix,
+        SYSTEM_PREFIX=system_prefix,
+        MIDDLEWARES=tuple(middlewares or ()),
+        LIFESPAN=lifespan,
+    )
+    return type("AppSpec", (AppSpec,), attrs)
+
+
+def deriveApp(**kw: Any) -> Type[App]:
+    """Produce a concrete :class:`App` subclass that inherits the spec."""
+    Spec = defineAppSpec(**kw)
+    return type("AppWithSpec", (Spec, App), {})
+
+
+__all__ = ["defineAppSpec", "deriveApp"]