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

tigrbl/op/model_registry.py

@@ -0,0 +1,301 @@
+# tigrbl/v3/ops/model_registry.py
+from __future__ import annotations
+
+from dataclasses import replace
+from threading import RLock
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    Iterator,
+    List,
+    Mapping,
+    Optional,
+    Tuple,
+)
+import weakref
+
+from .types import OpSpec, TargetOp
+
+# Listener signature: (registry, changed_keys) -> None
+# where changed_keys is a set of (alias, target) tuples indicating what changed.
+Listener = Callable[["OpspecRegistry", set[Tuple[str, TargetOp]]], None]
+
+
+def _spec_key(sp: OpSpec) -> Tuple[str, TargetOp]:
+    return (sp.alias, sp.target)
+
+
+def _ensure_table(sp: OpSpec, table: type) -> OpSpec:
+    return sp if sp.table is table else replace(sp, table=table)
+
+
+def _coerce_to_specs(value: Any, table: type) -> List[OpSpec]:
+    """
+    Accept flexible inputs (for back-compat with v2):
+      • OpSpec
+      • Iterable[OpSpec]
+      • Mapping[str, dict]  (alias -> kwargs for OpSpec)
+      • Iterable[Mapping[str, Any]]  (each includes 'alias' & 'target')
+    """
+    specs: List[OpSpec] = []
+    if value is None:
+        return specs
+
+    def _from_kwargs(kwargs: Mapping[str, Any]) -> Optional[OpSpec]:
+        if "alias" not in kwargs or "target" not in kwargs:
+            return None
+        try:
+            return OpSpec(table=table, **dict(kwargs))  # type: ignore[arg-type]
+        except TypeError:
+            return None
+
+    if isinstance(value, OpSpec):
+        specs.append(_ensure_table(value, table))
+    elif isinstance(value, Mapping):
+        for maybe_alias, cfg in value.items():
+            if isinstance(cfg, OpSpec):
+                specs.append(_ensure_table(cfg, table))
+            elif isinstance(cfg, Mapping):
+                kw = dict(cfg)
+                kw.setdefault("alias", maybe_alias)
+                sp = _from_kwargs(kw)
+                if sp:
+                    specs.append(sp)
+    elif isinstance(value, Iterable):
+        for item in value:
+            if isinstance(item, OpSpec):
+                specs.append(_ensure_table(item, table))
+            elif isinstance(item, Mapping):
+                sp = _from_kwargs(item)
+                if sp:
+                    specs.append(sp)
+    return specs
+
+
+class OpspecRegistry:
+    """
+    Per-model OpSpec registry with change notifications.
+
+    - Stores specs keyed by (alias, target).
+    - Adds/sets/removes specs and notifies listeners with the changed keys.
+    - Binder should call `subscribe(...)` to rebuild a model's namespaces when the
+      registry changes (partial rebuild is possible based on changed keys).
+
+    Thread-safe via an instance-level RLock.
+    """
+
+    __slots__ = ("_table", "_items", "_lock", "_listeners", "_version")
+
+    def __init__(self, table: type) -> None:
+        self._table: type = table
+        self._items: Dict[Tuple[str, TargetOp], OpSpec] = {}
+        self._lock = RLock()
+        # store weakrefs to listener callables where possible; fallback to strong refs
+        self._listeners: List[
+            Callable[[OpspecRegistry, set[Tuple[str, TargetOp]]], None]
+        ] = []
+        self._version: int = 0
+
+    # ---------------------------- Introspection ---------------------------- #
+
+    @property
+    def table(self) -> type:
+        return self._table
+
+    @property
+    def version(self) -> int:
+        return self._version
+
+    def keys(self) -> Iterator[Tuple[str, TargetOp]]:
+        with self._lock:
+            return iter(tuple(self._items.keys()))
+
+    def items(self) -> Iterator[Tuple[Tuple[str, TargetOp], OpSpec]]:
+        with self._lock:
+            return iter(tuple(self._items.items()))
+
+    def values(self) -> Iterator[OpSpec]:
+        with self._lock:
+            return iter(tuple(self._items.values()))
+
+    def get_all(self) -> Tuple[OpSpec, ...]:
+        """Stable snapshot of all specs."""
+        with self._lock:
+            return tuple(self._items.values())
+
+    # ------------------------------ Listeners ------------------------------ #
+
+    def subscribe(self, fn: Listener) -> None:
+        """
+        Register a listener to be called on changes.
+        NOTE: The listener should be idempotent. It receives (registry, changed_keys).
+        """
+        with self._lock:
+            # Avoid duplicate subscriptions
+            if fn not in self._listeners:
+                self._listeners.append(fn)
+
+    def unsubscribe(self, fn: Listener) -> None:
+        with self._lock:
+            try:
+                self._listeners.remove(fn)
+            except ValueError:
+                pass
+
+    def _notify(self, changed: set[Tuple[str, TargetOp]]) -> None:
+        # Snapshot listeners to avoid mutation issues during callbacks
+        listeners: Tuple[Listener, ...]
+        with self._lock:
+            listeners = tuple(self._listeners)
+        for fn in listeners:
+            try:
+                fn(self, changed)
+            except Exception:
+                # Never let a listener error break the registry
+                pass
+
+    # ------------------------------- Mutators ------------------------------ #
+
+    def add(self, specs: Iterable[OpSpec] | OpSpec) -> set[Tuple[str, TargetOp]]:
+        """
+        Add or overwrite one or more specs.
+        Returns the set of changed keys.
+        """
+        if isinstance(specs, OpSpec):
+            specs = (specs,)
+
+        changed: set[Tuple[str, TargetOp]] = set()
+        with self._lock:
+            for sp in specs:
+                sp = _ensure_table(sp, self._table)
+                k = _spec_key(sp)
+                if self._items.get(k) is sp:
+                    continue  # exact object already present
+                self._items[k] = sp
+                changed.add(k)
+            if changed:
+                self._version += 1
+        if changed:
+            self._notify(changed)
+        return changed
+
+    def set(self, specs: Iterable[OpSpec]) -> set[Tuple[str, TargetOp]]:
+        """
+        Replace all specs with the provided iterable.
+        Returns the set of changed keys (union of removed + added/updated).
+        """
+        new_map: Dict[Tuple[str, TargetOp], OpSpec] = {}
+        for sp in specs:
+            sp = _ensure_table(sp, self._table)
+            new_map[_spec_key(sp)] = sp
+
+        with self._lock:
+            old_keys = set(self._items.keys())
+            new_keys = set(new_map.keys())
+
+            removed = old_keys - new_keys
+            added_or_updated = {
+                k for k in new_keys if self._items.get(k) is not new_map[k]
+            }
+
+            changed = removed | added_or_updated
+            self._items = new_map
+            if changed:
+                self._version += 1
+
+        if changed:
+            self._notify(changed)
+        return changed
+
+    def remove(
+        self, alias: str, target: TargetOp | None = None
+    ) -> set[Tuple[str, TargetOp]]:
+        """
+        Remove specs by alias (optionally constrain to a specific target).
+        Returns the set of removed keys.
+        """
+        removed: set[Tuple[str, TargetOp]] = set()
+        with self._lock:
+            if target is None:
+                # remove all targets under this alias
+                for k in list(self._items.keys()):
+                    if k[0] == alias:
+                        self._items.pop(k, None)
+                        removed.add(k)
+            else:
+                k = (alias, target)
+                if k in self._items:
+                    self._items.pop(k, None)
+                    removed.add(k)
+
+            if removed:
+                self._version += 1
+
+        if removed:
+            self._notify(removed)
+        return removed
+
+    def clear(self) -> None:
+        with self._lock:
+            if not self._items:
+                return
+            self._items.clear()
+            self._version += 1
+        self._notify(set())
+
+
+# ------------------------------------------------------------------------------
+# Per-model registry storage (weak keys so classes can be GC'd)
+# ------------------------------------------------------------------------------
+
+_REGISTRIES: "weakref.WeakKeyDictionary[type, OpspecRegistry]" = (
+    weakref.WeakKeyDictionary()
+)
+_REG_LOCK = RLock()
+
+
+def get_registry(table: type) -> OpspecRegistry:
+    with _REG_LOCK:
+        reg = _REGISTRIES.get(table)
+        if reg is None:
+            reg = OpspecRegistry(table)
+            _REGISTRIES[table] = reg
+        return reg
+
+
+# ------------------------------------------------------------------------------
+# Back-compat helpers (v2-style imperative API)
+# ------------------------------------------------------------------------------
+
+
+def register_ops(table: type, specs: Any) -> set[Tuple[str, TargetOp]]:
+    """
+    Imperative registration (back-compat).
+    Accepts OpSpec, iterable of OpSpec, mapping forms, etc.
+    Triggers listeners (i.e., binder refresh) on change.
+    """
+    reg = get_registry(table)
+    coerced = _coerce_to_specs(specs, table)
+    return reg.add(coerced)
+
+
+def get_registered_ops(table: type) -> Tuple[OpSpec, ...]:
+    """
+    Back-compat reader used by the collector.
+    """
+    return get_registry(table).get_all()
+
+
+def clear_registry(table: type) -> None:
+    get_registry(table).clear()
+
+
+__all__ = [
+    "OpspecRegistry",
+    "get_registry",
+    "register_ops",
+    "get_registered_ops",
+    "clear_registry",
+]

tigrbl/op/mro_collect.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Any, Callable, Dict
+
+from .types import OpSpec
+from .decorators import _maybe_await, _OpDecl, _infer_arity, _normalize_persist, _unwrap
+from ..runtime.executor import _Ctx
+
+logger = logging.getLogger("uvicorn")
+
+
+def _merge_mro_dict(cls: type, attr: str) -> Dict[str, Any]:
+    merged: Dict[str, Any] = {}
+    for base in reversed(cls.__mro__):
+        merged.update(getattr(base, attr, {}) or {})
+    return merged
+
+
+@lru_cache(maxsize=None)
+def mro_alias_map_for(table: type) -> Dict[str, str]:
+    """Collect alias overrides across the table's MRO."""
+    return _merge_mro_dict(table, "__tigrbl_aliases__")
+
+
+def _wrap_ctx_core(table: type, func: Callable[..., Any]) -> Callable[..., Any]:
+    """Adapt `(cls, ctx)` op to `(p, *, db, request, ctx)` handler signature."""
+
+    async def core(p=None, *, db=None, request=None, ctx: Dict[str, Any] | None = None):
+        ctx = _Ctx.ensure(request=request, db=db, seed=ctx)
+        if p is not None:
+            ctx["payload"] = p
+        bound = func.__get__(table, table)
+        res = await _maybe_await(bound(ctx))
+        return res if res is not None else ctx.get("result")
+
+    core.__name__ = getattr(func, "__name__", "core")
+    core.__qualname__ = getattr(func, "__qualname__", core.__name__)
+    return core
+
+
+@lru_cache(maxsize=None)
+def mro_collect_decorated_ops(table: type) -> list[OpSpec]:
+    """Collect ctx-only op declarations across the table's MRO."""
+
+    logger.info("Collecting decorated ops for %s", table.__name__)
+    out: list[OpSpec] = []
+    seen: set[str] = set()
+
+    for base in table.__mro__:
+        for name, attr in vars(base).items():
+            if name in seen:
+                continue
+            func = _unwrap(attr)
+            decl: _OpDecl | None = getattr(func, "__tigrbl_op_decl__", None)
+            if not decl:
+                continue
+
+            target = decl.target or "custom"
+            arity = decl.arity or _infer_arity(target)
+            persist = _normalize_persist(decl.persist)
+            alias = decl.alias or name
+
+            expose_kwargs: dict[str, Any] = {}
+            extra: dict[str, Any] = {}
+            if decl.rest is not None:
+                expose_kwargs["expose_routes"] = bool(decl.rest)
+            elif alias != target and target in {
+                "read",
+                "update",
+                "delete",
+                "list",
+                "clear",
+            }:
+                expose_kwargs["expose_routes"] = False
+
+            spec = OpSpec(
+                table=table,
+                alias=alias,
+                target=target,
+                arity=arity,
+                persist=persist,
+                handler=_wrap_ctx_core(table, func),
+                request_model=decl.request_schema,
+                response_model=decl.response_schema,
+                hooks=(),
+                status_code=decl.status_code,
+                extra=extra,
+                **expose_kwargs,
+            )
+            out.append(spec)
+            seen.add(name)
+
+    logger.debug("Collected %d ops for %s", len(out), table.__name__)
+    return out
+
+
+__all__ = ["mro_alias_map_for", "mro_collect_decorated_ops"]

tigrbl/op/resolver.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from dataclasses import replace
+import logging
+import re
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+from .types import OpSpec, TargetOp
+from ..config.constants import TIGRBL_OPS_ATTR
+from .canonical import should_wire_canonical
+from .mro_collect import mro_alias_map_for
+
+try:
+    # Per-model registry (observable, triggers rebind elsewhere)
+    from .model_registry import get_registered_ops  # type: ignore
+except Exception:  # pragma: no cover
+
+    def get_registered_ops(model: type) -> Sequence[OpSpec]:  # shim
+        return ()
+
+
+logger = logging.getLogger("uvicorn")
+
+_ALIAS_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
+def _ensure_spec_table(spec: OpSpec, table: type) -> OpSpec:
+    if spec.table is table:
+        return spec
+    return replace(spec, table=table)
+
+
+def _as_specs(value: Any, table: type) -> List[OpSpec]:
+    """Normalize various `__tigrbl_ops__` shapes to a list of OpSpec."""
+    specs: List[OpSpec] = []
+    if value is None:
+        return specs
+
+    def _from_kwargs(kwargs: Mapping[str, Any]) -> Optional[OpSpec]:
+        if "alias" not in kwargs or "target" not in kwargs:
+            return None
+        try:
+            spec = OpSpec(table=table, hooks=(), extra={}, **kwargs)
+            return spec
+        except Exception:  # pragma: no cover - defensive
+            return None
+
+    if isinstance(value, OpSpec):
+        specs.append(_ensure_spec_table(value, table))
+    elif isinstance(value, Mapping):
+        for alias, cfg in value.items():
+            if isinstance(cfg, Mapping):
+                spec = _from_kwargs({"alias": alias, **cfg})
+                if spec:
+                    specs.append(spec)
+    elif isinstance(value, Iterable):
+        for item in value:
+            if isinstance(item, OpSpec):
+                specs.append(_ensure_spec_table(item, table))
+            elif isinstance(item, Mapping):
+                spec = _from_kwargs(item)
+                if spec:
+                    specs.append(spec)
+    else:
+        spec = _from_kwargs(
+            {
+                "alias": getattr(value, "alias", None),
+                "target": getattr(value, "target", None),
+            }
+        )
+        if spec:
+            specs.append(spec)
+    return specs
+
+
+def _generate_canonical(table: type) -> List[OpSpec]:
+    """Generate canonical CRUD specs based on model attributes."""
+    specs: List[OpSpec] = []
+    targets: List[Tuple[str, TargetOp]] = [
+        ("create", "create"),
+        ("read", "read"),
+        ("update", "update"),
+        # Include canonical "replace" so RPC callers get full CRUD semantics
+        # without opting into the Replaceable mixin.
+        ("replace", "replace"),
+        ("merge", "merge"),
+        ("delete", "delete"),
+        ("list", "list"),
+        ("clear", "clear"),
+        ("bulk_create", "bulk_create"),
+        ("bulk_update", "bulk_update"),
+        ("bulk_replace", "bulk_replace"),
+        ("bulk_merge", "bulk_merge"),
+        ("bulk_delete", "bulk_delete"),
+    ]
+    collection_targets = {
+        "create",
+        "list",
+        "clear",
+        "bulk_create",
+        "bulk_update",
+        "bulk_replace",
+        "bulk_merge",
+        "bulk_delete",
+    }
+    for alias, target in targets:
+        if not should_wire_canonical(table, target):
+            continue
+        specs.append(
+            OpSpec(
+                table=table,
+                alias=alias,
+                target=target,
+                arity="collection" if target in collection_targets else "member",
+                persist="default",
+                handler=None,
+                request_model=None,
+                response_model=None,
+                hooks=(),
+                status_code=None,
+                extra={},
+            )
+        )
+    return specs
+
+
+def _collect_class_declared(model: type) -> List[OpSpec]:
+    out: List[OpSpec] = []
+    raw = getattr(model, TIGRBL_OPS_ATTR, None)
+    if isinstance(raw, Mapping) or isinstance(raw, Iterable):
+        out.extend(_as_specs(raw, model))
+    return out
+
+
+def _collect_registry(model: type) -> List[OpSpec]:
+    return list(get_registered_ops(model))
+
+
+def _dedupe(
+    existing: Dict[Tuple[str, str], OpSpec], incoming: Iterable[OpSpec]
+) -> None:
+    for sp in incoming:
+        if not isinstance(sp, OpSpec):
+            continue
+        if not sp.alias or not sp.target:
+            continue
+        existing[(sp.alias, sp.target)] = sp
+
+
+def _apply_alias_ctx_to_canon(specs: List[OpSpec], model: type) -> List[OpSpec]:
+    aliases = mro_alias_map_for(model)
+    overrides: Mapping[str, Mapping[str, Any]] = (
+        getattr(model, "__tigrbl_alias_overrides__", {}) or {}
+    )
+
+    if not aliases and not overrides:
+        return specs
+
+    out: List[OpSpec] = []
+    for sp in specs:
+        canon = sp.target
+        new_alias = aliases.get(canon, sp.alias)
+        mutated = sp
+        if new_alias != sp.alias:
+            if not isinstance(new_alias, str) or not _ALIAS_RE.match(new_alias):
+                logger.warning(
+                    "Invalid alias %r for verb %r on %s; keeping %r",
+                    new_alias,
+                    sp.target,
+                    model.__name__,
+                    sp.alias,
+                )
+            else:
+                mutated = replace(mutated, alias=new_alias, path_suffix="")
+
+        ov = overrides.get(canon)
+        if ov:
+            kwargs = {}
+            if "request_schema" in ov:
+                kwargs["request_model"] = ov["request_schema"]
+            if "response_schema" in ov:
+                kwargs["response_model"] = ov["response_schema"]
+            if "persist" in ov:
+                kwargs["persist"] = ov["persist"]
+            if "arity" in ov:
+                kwargs["arity"] = ov["arity"]
+            if "rest" in ov:
+                kwargs["expose_routes"] = bool(ov["rest"])
+            if "engine" in ov:
+                kwargs["engine"] = ov["engine"]
+            if kwargs:
+                mutated = replace(mutated, **kwargs)
+        out.append(mutated)
+    return out
+
+
+def resolve(model: type) -> List[OpSpec]:
+    canon = _generate_canonical(model)
+    canon = _apply_alias_ctx_to_canon(canon, model)
+
+    class_specs = _collect_class_declared(model)
+    reg_specs = _collect_registry(model)
+
+    merged: Dict[Tuple[str, str], OpSpec] = {}
+    _dedupe(merged, canon)
+    _dedupe(merged, class_specs)
+    _dedupe(merged, reg_specs)
+
+    specs = list(merged.values())
+    specs = [_ensure_spec_table(sp, model) for sp in specs]
+
+    logger.debug("ops.resolver.resolve(%s): %d specs", model.__name__, len(specs))
+    return specs
+
+
+__all__ = ["resolve"]