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

tigrbl/runtime/atoms/response/renderer.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, AsyncIterable, Iterable, Mapping, Optional, Union, cast
+import logging
+
+from ....deps.starlette import BackgroundTask, Response
+
+from ....response.shortcuts import (
+    as_file,
+    as_html,
+    as_json,
+    as_stream,
+    as_text,
+)
+
+JSON = Mapping[str, Any]
+
+logger = logging.getLogger("uvicorn")
+
+
+@dataclass
+class ResponseHints:
+    media_type: Optional[str] = None
+    status_code: int = 200
+    headers: dict[str, str] = field(default_factory=dict)
+    filename: Optional[str] = None
+    download: bool = False
+    etag: Optional[str] = None
+    last_modified: Optional[Any] = None
+    background: Optional[BackgroundTask] = None
+
+
+class ResponseKind:
+    JSON = "application/json"
+    HTML = "text/html"
+    TEXT = "text/plain"
+    FILE = "application/file"
+    STREAM = "application/stream"
+    REDIRECT = "application/redirect"
+
+
+ResponseLike = Union[
+    Response,
+    bytes,
+    bytearray,
+    memoryview,
+    str,
+    Path,
+    JSON,
+    Iterable[bytes],
+    AsyncIterable[bytes],
+]
+
+
+def render(
+    request: Any,
+    payload: ResponseLike,
+    *,
+    hints: Optional[ResponseHints] = None,
+    default_media: str = "application/json",
+    envelope_default: bool = False,
+) -> Response:
+    logger.debug("Rendering response with payload type %s", type(payload))
+    if isinstance(payload, Response):
+        return payload
+
+    hints = hints or ResponseHints()
+    chosen = hints.media_type or default_media
+
+    if isinstance(payload, Path):
+        return as_file(
+            payload,
+            filename=hints.filename,
+            download=hints.download,
+            status=hints.status_code,
+            headers=hints.headers,
+        )
+
+    if isinstance(payload, (bytes, bytearray, memoryview)):
+        return as_stream(
+            iter((bytes(payload),)),
+            media_type="application/octet-stream",
+            status=hints.status_code,
+            headers=hints.headers,
+        )
+
+    if hasattr(payload, "__aiter__") or (
+        hasattr(payload, "__iter__") and not isinstance(payload, (str, dict, list))
+    ):
+        return as_stream(
+            cast(Union[Iterable[bytes], AsyncIterable[bytes]], payload),
+            media_type="application/octet-stream",
+            status=hints.status_code,
+            headers=hints.headers,
+        )
+
+    if isinstance(payload, str):
+        if payload.lstrip().startswith("<") or chosen == "text/html":
+            return as_html(payload, status=hints.status_code, headers=hints.headers)
+        return as_text(payload, status=hints.status_code, headers=hints.headers)
+
+    return as_json(
+        payload,
+        status=hints.status_code,
+        headers=hints.headers,
+        envelope=envelope_default,
+    )
+
+
+__all__ = [
+    "ResponseHints",
+    "ResponseKind",
+    "ResponseLike",
+    "render",
+]

tigrbl/runtime/atoms/response/template.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+from typing import Any, Optional
+
+from ... import events as _ev
+from .templates import render_template
+from .renderer import ResponseHints
+
+ANCHOR = _ev.OUT_DUMP  # "out:dump"
+
+
+async def run(obj: Optional[object], ctx: Any) -> None:
+    """response:template@out:dump
+
+    Render a template if configured on ``ctx.response``.
+    """
+    resp_ns = getattr(ctx, "response", None)
+    req = getattr(ctx, "request", None)
+    if resp_ns is None or req is None:
+        return
+    tmpl = getattr(resp_ns, "template", None)
+    if not tmpl:
+        return
+    result = getattr(resp_ns, "result", None)
+    context = result if isinstance(result, dict) else {"data": result}
+    html = await render_template(
+        name=tmpl.name,
+        context=context,
+        search_paths=tmpl.search_paths,
+        package=tmpl.package,
+        auto_reload=bool(tmpl.auto_reload),
+        filters=tmpl.filters,
+        globals_=tmpl.globals,
+        request=req,
+    )
+    resp_ns.result = html
+    hints = getattr(resp_ns, "hints", None)
+    if hints is None:
+        hints = ResponseHints()
+        resp_ns.hints = hints
+    if not hints.media_type:
+        hints.media_type = "text/html"
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/response/templates.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+from functools import lru_cache
+import logging
+from typing import Any, Dict, Iterable, Optional, Tuple
+
+from ....deps.starlette import Request
+from ....deps.jinja import (
+    Environment,
+    FileSystemLoader,
+    PackageLoader,
+    ChoiceLoader,
+    select_autoescape,
+    TemplateNotFound,
+)
+
+logger = logging.getLogger("uvicorn")
+if Environment is None:  # pragma: no cover - jinja2 not installed
+
+    async def render_template(
+        *,
+        name: str,
+        context: Dict[str, Any],
+        search_paths: Iterable[str] = (),
+        package: Optional[str] = None,
+        auto_reload: bool = False,
+        filters: Optional[Dict[str, Any]] = None,
+        globals_: Optional[Dict[str, Any]] = None,
+        request: Optional[Request] = None,
+    ) -> str:
+        logger.debug("Rendering template %s", name)
+        raise RuntimeError("jinja2 is required for template rendering")
+
+else:
+
+    def _mk_loader(search_paths: Iterable[str], package: Optional[str]) -> ChoiceLoader:
+        loaders = []
+        if search_paths:
+            loaders.append(FileSystemLoader(list(search_paths)))
+        if package:
+            loaders.append(PackageLoader(package_name=package))
+        if not loaders:
+            loaders.append(FileSystemLoader(["."]))
+        return ChoiceLoader(loaders)
+
+    @lru_cache(maxsize=64)
+    def _get_env(
+        search_paths_key: Tuple[str, ...],
+        package: Optional[str],
+        auto_reload: bool,
+    ) -> Environment:
+        env = Environment(
+            loader=_mk_loader(search_paths_key, package),
+            autoescape=select_autoescape(["html", "xml"]),
+            auto_reload=auto_reload,
+            enable_async=True,
+        )
+        return env
+
+    async def render_template(
+        *,
+        name: str,
+        context: Dict[str, Any],
+        search_paths: Iterable[str] = (),
+        package: Optional[str] = None,
+        auto_reload: bool = False,
+        filters: Optional[Dict[str, Any]] = None,
+        globals_: Optional[Dict[str, Any]] = None,
+        request: Optional[Request] = None,
+    ) -> str:
+        logger.debug("Rendering template %s", name)
+        env = _get_env(tuple(search_paths), package, auto_reload)
+        if filters:
+            env.filters.update(filters)
+        if globals_:
+            env.globals.update(globals_)
+        if request is not None:
+            env.globals.setdefault("url_for", request.url_for)
+            env.globals.setdefault("request", request)
+
+        try:
+            tmpl = env.get_template(name)
+        except TemplateNotFound as e:  # pragma: no cover - passthrough
+            raise FileNotFoundError(f"Template not found: {name}") from e
+
+        return await tmpl.render_async(**context)
+
+
+__all__ = ["render_template"]

tigrbl/runtime/atoms/schema/__init__.py

@@ -0,0 +1,40 @@
+# tigrbl/v3/runtime/atoms/schema/__init__.py
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple
+import logging
+
+# Atom implementations (model-scoped)
+from . import collect_in as _collect_in
+from . import collect_out as _collect_out
+
+# Runner signature: (obj|None, ctx) -> None
+RunFn = Callable[[Optional[object], Any], None]
+
+#: Domain-scoped registry consumed by the kernel plan (and aggregated at atoms/__init__.py).
+#: Keys are (domain, subject); values are (anchor, runner).
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
+    ("schema", "collect_in"): (_collect_in.ANCHOR, _collect_in.run),
+    ("schema", "collect_out"): (_collect_out.ANCHOR, _collect_out.run),
+}
+
+logger = logging.getLogger("uvicorn")
+
+
+def subjects() -> Tuple[str, ...]:
+    """Return the subject names exported by this domain."""
+    subjects = tuple(s for (_, s) in REGISTRY.keys())
+    logger.debug("Listing 'schema' subjects: %s", subjects)
+    return subjects
+
+
+def get(subject: str) -> Tuple[str, RunFn]:
+    """Return (anchor, runner) for a subject in the 'schema' domain."""
+    key = ("schema", subject)
+    if key not in REGISTRY:
+        raise KeyError(f"Unknown schema atom subject: {subject!r}")
+    logger.debug("Retrieving 'schema' subject %s", subject)
+    return REGISTRY[key]
+
+
+__all__ = ["REGISTRY", "RunFn", "subjects", "get"]

tigrbl/runtime/atoms/schema/collect_in.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_in
+
+# Runs at the very beginning of the lifecycle, before in-model build/validation.
+ANCHOR = _ev.SCHEMA_COLLECT_IN  # "schema:collect_in"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """Load precompiled inbound schema into ctx.temp."""
+    ov = opview_from_ctx(ctx)
+    ensure_schema_in(ctx, ov)
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/schema/collect_out.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+import logging
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_out
+
+# Runs late in POST_HANDLER, before out model build and dumping.
+ANCHOR = _ev.SCHEMA_COLLECT_OUT  # "schema:collect_out"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """Load precompiled outbound schema into ctx.temp."""
+    ov = opview_from_ctx(ctx)
+    ensure_schema_out(ctx, ov)
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/storage/__init__.py

@@ -0,0 +1,38 @@
+# tigrbl/v3/runtime/atoms/storage/__init__.py
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple
+import logging
+
+# Atom implementations (model-scoped)
+from . import to_stored as _to_stored
+
+# Runner signature: (obj|None, ctx) -> None
+RunFn = Callable[[Optional[object], Any], None]
+
+#: Domain-scoped registry consumed by the kernel plan (and aggregated at atoms/__init__.py).
+#: Keys are (domain, subject); values are (anchor, runner).
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
+    ("storage", "to_stored"): (_to_stored.ANCHOR, _to_stored.run),
+}
+
+logger = logging.getLogger("uvicorn")
+
+
+def subjects() -> Tuple[str, ...]:
+    """Return the subject names exported by this domain."""
+    subjects = tuple(s for (_, s) in REGISTRY.keys())
+    logger.debug("Listing 'storage' subjects: %s", subjects)
+    return subjects
+
+
+def get(subject: str) -> Tuple[str, RunFn]:
+    """Return (anchor, runner) for a subject in the 'storage' domain."""
+    key = ("storage", subject)
+    if key not in REGISTRY:
+        raise KeyError(f"Unknown storage atom subject: {subject!r}")
+    logger.debug("Retrieving 'storage' subject %s", subject)
+    return REGISTRY[key]
+
+
+__all__ = ["REGISTRY", "RunFn", "subjects", "get"]

tigrbl/runtime/atoms/storage/to_stored.py

@@ -0,0 +1,167 @@
+# tigrbl/v3/runtime/atoms/storage/to_stored.py
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Mapping, MutableMapping, Optional
+
+from ... import events as _ev
+from ...opview import opview_from_ctx, ensure_schema_in, _ensure_temp
+
+# Runs right before the handler flushes to the DB.
+ANCHOR = _ev.PRE_FLUSH  # "pre:flush"
+
+logger = logging.getLogger("uvicorn")
+
+
+def run(obj: Optional[object], ctx: Any) -> None:
+    """
+    storage:to_stored@pre:flush
+
+    Transform inbound values into their persisted representation.
+
+    - For *paired/secret-once* columns, derive the stored value from the prepared raw
+      and assign it to BOTH ctx.temp["assembled_values"][field] AND the ORM object.
+      Also handles a fallback when 'persist_from_paired' wasn't queued but a paired raw
+      exists (planner tolerance).
+    - Otherwise, apply an optional per-column inbound→stored transform and mirror the
+      transformed value onto the ORM instance.
+
+    On failure to derive for paired, raise ValueError (mapped by higher layers) to
+    avoid leaking DB IntegrityErrors.
+    """
+    logger.debug("Running storage:to_stored")
+    if getattr(ctx, "persist", True) is False:
+        logger.debug("Skipping storage:to_stored; ctx.persist is False")
+        return
+
+    ov = opview_from_ctx(ctx)
+    schema_in = ensure_schema_in(ctx, ov)
+    temp = _ensure_temp(ctx)
+    assembled = _ensure_dict(temp, "assembled_values")
+    paired_values = _ensure_dict(temp, "paired_values")
+    pf_paired = _ensure_dict(temp, "persist_from_paired")
+    slog = _ensure_list(temp, "storage_log")
+    serr = _ensure_list(temp, "storage_errors")
+
+    # Prefer explicit obj (hydrated instance), else ctx.model if adapter provided it
+    target_obj = obj or getattr(ctx, "model", None)
+
+    # Ensure paired fields are considered even when absent from inbound schema.
+    # schema_in["fields"] may omit columns like "digest" that generate their
+    # values server-side via IO(...).paired. To derive their stored values, merge
+    # the explicit schema fields with the paired index keys.
+    all_fields = set(schema_in["fields"]) | set(ov.paired_index.keys())
+
+    for field in sorted(all_fields):
+        if field in ov.paired_index:
+            if field in pf_paired or field in paired_values:
+                raw = None
+                if field in pf_paired:
+                    raw = _resolve_from_pointer(
+                        pf_paired[field].get("source"), paired_values, field
+                    )
+                if raw is None:
+                    raw = paired_values.get(field, {}).get("raw")
+                if raw is None:
+                    serr.append({"field": field, "error": "missing_paired_raw"})
+                    logger.debug("Missing paired raw for field %s", field)
+                    raise RuntimeError(f"paired_raw_missing:{field}")
+                deriver = ov.paired_index[field].get("store")
+                try:
+                    stored = deriver(raw, ctx) if callable(deriver) else raw
+                except Exception as e:
+                    serr.append(
+                        {"field": field, "error": f"deriver_failed:{type(e).__name__}"}
+                    )
+                    logger.debug("Deriver failed for field %s: %s", field, e)
+                    raise
+                assembled[field] = stored
+                _assign_to_model(target_obj, field, stored)
+                slog.append({"field": field, "action": "derived_from_paired"})
+                logger.debug("Derived stored value for paired field %s", field)
+                continue
+
+            nullable = schema_in["by_field"].get(field, {}).get("nullable", True)
+            if (
+                not nullable
+                and field not in assembled
+                and not _has_attr_with_value(target_obj, field)
+            ):
+                serr.append({"field": field, "error": "paired_missing_before_flush"})
+                logger.debug("Paired field %s missing before flush", field)
+                raise RuntimeError(f"paired_missing_before_flush:{field}")
+            continue
+
+        if field in assembled:
+            transform = ov.to_stored_transforms.get(field)
+            if transform is None:
+                logger.debug("No transform for field %s; using assembled value", field)
+                _assign_to_model(target_obj, field, assembled[field])
+                continue
+            try:
+                stored_val = transform(assembled[field], ctx)
+                assembled[field] = stored_val
+                _assign_to_model(target_obj, field, stored_val)
+                slog.append({"field": field, "action": "transformed"})
+                logger.debug("Transformed field %s", field)
+            except Exception as e:
+                serr.append(
+                    {"field": field, "error": f"transform_failed:{type(e).__name__}"}
+                )
+                logger.debug("Transform failed for field %s: %s", field, e)
+                raise
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internals (tolerant to spec shapes)
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _assign_to_model(target: Optional[object], field: str, value: Any) -> None:
+    """Safely assign value onto the hydrated ORM object so SQLAlchemy flushes it."""
+    if target is None:
+        return
+    try:
+        setattr(target, field, value)
+    except Exception:
+        # Non-fatal: some adapters may not expose an assignable object here.
+        pass
+
+
+def _has_attr_with_value(target: Optional[object], field: str) -> bool:
+    if target is None or not hasattr(target, field):
+        return False
+    try:
+        return getattr(target, field) is not None
+    except Exception:
+        return False
+
+
+def _ensure_dict(temp: MutableMapping[str, Any], key: str) -> Dict[str, Any]:
+    d = temp.get(key)
+    if not isinstance(d, dict):
+        d = {}
+        temp[key] = d
+    return d  # type: ignore[return-value]
+
+
+def _ensure_list(temp: MutableMapping[str, Any], key: str) -> list:
+    lst = temp.get(key)
+    if not isinstance(lst, list):
+        lst = []
+        temp[key] = lst
+    return lst  # type: ignore[return-value]
+
+
+def _resolve_from_pointer(
+    source: Any, pv: Mapping[str, Dict[str, Any]], field: str
+) -> Optional[Any]:
+    """Resolve ('paired_values', field, 'raw') pointer, with fallback to pv[field]['raw']."""
+    if isinstance(source, (tuple, list)) and len(source) == 3:
+        base, fld, key = source
+        if base == "paired_values" and isinstance(fld, str) and key == "raw":
+            return pv.get(fld, {}).get("raw")
+    return pv.get(field, {}).get("raw")
+
+
+__all__ = ["ANCHOR", "run"]

tigrbl/runtime/atoms/wire/__init__.py

@@ -0,0 +1,45 @@
+# tigrbl/v3/runtime/atoms/wire/__init__.py
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple
+import logging
+
+# Atom implementations (per-field)
+from . import build_in as _build_in
+from . import validate_in as _validate_in
+from . import build_out as _build_out
+from . import dump as _dump
+
+# Runner signature: (obj|None, ctx) -> None
+RunFn = Callable[[Optional[object], Any], None]
+
+#: Domain-scoped registry consumed by the kernel plan (and aggregated at atoms/__init__.py).
+#: Keys are (domain, subject); values are (anchor, runner).
+#: Canonical subjects mirror filenames; we keep "validate_in" (not "validate") to avoid duplicates.
+REGISTRY: Dict[Tuple[str, str], Tuple[str, RunFn]] = {
+    ("wire", "build_in"): (_build_in.ANCHOR, _build_in.run),
+    ("wire", "validate_in"): (_validate_in.ANCHOR, _validate_in.run),
+    ("wire", "build_out"): (_build_out.ANCHOR, _build_out.run),
+    ("wire", "dump"): (_dump.ANCHOR, _dump.run),
+}
+
+logger = logging.getLogger("uvicorn")
+
+
+def subjects() -> Tuple[str, ...]:
+    """Return the subject names exported by this domain."""
+    subjects = tuple(s for (_, s) in REGISTRY.keys())
+    logger.debug("Listing 'wire' subjects: %s", subjects)
+    return subjects
+
+
+def get(subject: str) -> Tuple[str, RunFn]:
+    """Return (anchor, runner) for a subject in the 'wire' domain."""
+    key = ("wire", subject)
+    if key not in REGISTRY:
+        raise KeyError(f"Unknown wire atom subject: {subject!r}")
+    logger.debug("Retrieving 'wire' subject %s", subject)
+    return REGISTRY[key]
+
+
+__all__ = ["REGISTRY", "RunFn", "subjects", "get"]