simple-module-inertia 0.0.35__py3-none-any.whl

simple_module_inertia/__init__.py

@@ -0,0 +1,47 @@
+"""Inertia.js v3 server adapter for FastAPI. See README.md and NOTICE."""
+
+from __future__ import annotations
+
+from simple_module_inertia.config import InertiaConfig
+from simple_module_inertia.deps import inertia_dependency_factory
+from simple_module_inertia.errors import (
+    InertiaVersionConflictException,
+    inertia_request_validation_exception_handler,
+    inertia_version_conflict_exception_handler,
+)
+from simple_module_inertia.inertia import Inertia
+from simple_module_inertia.page import PropEncodingError
+from simple_module_inertia.props import (
+    always,
+    deep_merge,
+    defer,
+    lazy,
+    merge,
+    once,
+    optional,
+    prepend,
+    scroll,
+)
+from simple_module_inertia.response import InertiaResponse
+from simple_module_inertia.templating import InertiaExtension
+
+__all__ = [
+    "Inertia",
+    "InertiaConfig",
+    "InertiaExtension",
+    "InertiaResponse",
+    "InertiaVersionConflictException",
+    "PropEncodingError",
+    "always",
+    "deep_merge",
+    "defer",
+    "inertia_dependency_factory",
+    "inertia_request_validation_exception_handler",
+    "inertia_version_conflict_exception_handler",
+    "lazy",
+    "merge",
+    "once",
+    "optional",
+    "prepend",
+    "scroll",
+]

simple_module_inertia/config.py

@@ -0,0 +1,41 @@
+"""Adapter configuration.
+
+Field names match upstream ``fastapi-inertia`` so ``simple_module_hosting``'s
+``setup_inertia`` keeps constructing it the same way. The one addition is that
+``version`` may be a zero-arg callable, so an app can derive the asset version
+from its Vite manifest hash at boot instead of hard-coding ``"1.0"``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from fastapi.templating import Jinja2Templates
+
+
+@dataclass
+class InertiaConfig:
+    templates: Jinja2Templates
+    environment: Literal["development", "production"] = "development"
+    version: str | Callable[[], str] = "1.0"
+    dev_url: str = "http://localhost:5173"
+    ssr_url: str = "http://localhost:13714"
+    ssr_enabled: bool = False
+    manifest_json_path: str = ""
+    root_directory: str = "src"
+    root_template_filename: str = "index.html"
+    entrypoint_filename: str = "main.js"
+    use_flash_messages: bool = False
+    use_flash_errors: bool = False
+    flash_message_key: str = "messages"
+    flash_error_key: str = "errors"
+    assets_prefix: str = ""
+    extra_template_context: dict[str, Any] = field(default_factory=dict)
+
+
+def resolved_version(config: InertiaConfig) -> str:
+    """The asset version as a string, calling ``version`` if it is a callable."""
+    version = config.version
+    return str(version()) if callable(version) else str(version)

simple_module_inertia/deps.py

@@ -0,0 +1,23 @@
+"""Build the per-request dependency hosting publishes on ``app.state``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import Request
+
+from simple_module_inertia.config import InertiaConfig
+from simple_module_inertia.inertia import Inertia
+from simple_module_inertia.templating import InertiaExtension
+
+
+def inertia_dependency_factory(config: InertiaConfig) -> Callable[..., Inertia]:
+    env = config.templates.env
+    if InertiaExtension not in env.extensions.values():
+        env.add_extension(InertiaExtension)
+
+    def inertia_dependency(request: Request, client: Any = None) -> Inertia:
+        return Inertia(request, config, client)
+
+    return inertia_dependency

simple_module_inertia/errors.py

@@ -0,0 +1,53 @@
+"""Exception types and handlers. Names match upstream — hosting imports them."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Request, Response, status
+from fastapi.exception_handlers import request_validation_exception_handler
+from fastapi.exceptions import RequestValidationError
+from starlette.responses import RedirectResponse
+
+
+class InertiaVersionConflictException(Exception):  # noqa: N818 - upstream name; hosting imports it
+    """Raised on a GET whose ``X-Inertia-Version`` no longer matches ours."""
+
+    def __init__(self, url: str) -> None:
+        self.url = url
+        super().__init__()
+
+
+async def inertia_version_conflict_exception_handler(
+    _: Request, exc: InertiaVersionConflictException
+) -> Response:
+    return Response(
+        status_code=status.HTTP_409_CONFLICT, headers={"X-Inertia-Location": str(exc.url)}
+    )
+
+
+def _field(loc: tuple[Any, ...]) -> Any:
+    return loc[1] if len(loc) > 1 else loc[0]
+
+
+async def inertia_request_validation_exception_handler(
+    request: Request, exc: RequestValidationError
+) -> Response:
+    """Flash validation errors and send the browser back, scoped by error bag."""
+    if "x-inertia" not in request.headers:
+        return await request_validation_exception_handler(request, exc)
+
+    errors: dict[str, Any] = {}
+    bag = request.headers.get("X-Inertia-Error-Bag")
+    for error in exc.errors():
+        field = _field(tuple(error["loc"]))
+        if bag is None:
+            errors[field] = error["msg"]
+        else:
+            errors.setdefault(bag, {})[field] = error["msg"]
+    request.session["_errors"] = errors
+
+    code = (
+        status.HTTP_307_TEMPORARY_REDIRECT if request.method == "GET" else status.HTTP_303_SEE_OTHER
+    )
+    return RedirectResponse(url=request.headers.get("Referer", "/"), status_code=code)

simple_module_inertia/inertia.py

@@ -0,0 +1,145 @@
+"""The request-scoped facade. Thin: each stage lives in its own module."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from fastapi import Request
+from jinja2.utils import htmlsafe_json_dumps
+from pydantic import BaseModel
+from starlette.responses import RedirectResponse, Response
+
+from simple_module_inertia.config import InertiaConfig, resolved_version
+from simple_module_inertia.errors import InertiaVersionConflictException
+from simple_module_inertia.manifest import entry_assets
+from simple_module_inertia.page import build_page, encode_page
+from simple_module_inertia.request import InertiaRequest
+from simple_module_inertia.resolve import resolve_props
+from simple_module_inertia.response import (
+    InertiaResponse,
+    fragment_redirect,
+    json_response,
+    location,
+    redirect,
+)
+from simple_module_inertia.templating import InertiaContext
+
+
+class Inertia:
+    def __init__(self, request: Request, config: InertiaConfig, client: Any = None) -> None:
+        self._request = request
+        self._config = config
+        self._client = client  # kept for signature compatibility; SSR is not implemented
+        self._req = InertiaRequest.from_headers(request.headers, request.method)
+        self._version = resolved_version(config)
+        self._shared: dict[str, Any] = {}
+        self._encrypt_history = False
+        self._clear_history = False
+        self._preserve_fragment = False
+        if self._is_stale():
+            raise InertiaVersionConflictException(url=str(request.url))
+
+    # -- request state ----------------------------------------------------
+
+    def _is_stale(self) -> bool:
+        """Only a GET is rejected; the client re-submits mutations itself."""
+        return (
+            self._req.is_inertia
+            and self._req.method == "GET"
+            and self._req.version is not None
+            and self._req.version != self._version
+        )
+
+    def share(self, **props: Any) -> None:
+        self._shared.update(props)
+
+    def flash(self, message: str, category: str) -> None:
+        if not self._config.use_flash_messages:
+            raise NotImplementedError("Flash messages are not enabled")
+        self._request.session.setdefault("_messages", []).append(
+            {"message": message, "category": category}
+        )
+
+    def encrypt_history(self) -> Inertia:
+        self._encrypt_history = True
+        return self
+
+    def clear_history(self) -> Inertia:
+        self._clear_history = True
+        return self
+
+    def preserve_fragment(self) -> Inertia:
+        self._preserve_fragment = True
+        return self
+
+    # -- redirects --------------------------------------------------------
+
+    def redirect(self, url: str) -> RedirectResponse:
+        return redirect(url, method=self._request.method)
+
+    def back(self) -> RedirectResponse:
+        return self.redirect(self._request.headers.get("Referer", "/"))
+
+    @staticmethod
+    def location(url: str) -> Response:
+        return location(url)
+
+    @staticmethod
+    def redirect_with_fragment(url: str) -> Response:
+        return fragment_redirect(url)
+
+    # -- render -----------------------------------------------------------
+
+    def _pop_session(self, key: str, default: Any) -> Any:
+        session = self._request.session
+        return session.pop(key) if key in session else default
+
+    async def render(
+        self, component: str, props: dict[str, Any] | BaseModel | None = None
+    ) -> InertiaResponse:
+        page_props: dict[str, Any] = (
+            props.model_dump() if isinstance(props, BaseModel) else dict(props or {})
+        )
+        if self._config.use_flash_messages:
+            page_props[self._config.flash_message_key] = self._pop_session("_messages", [])
+        errors = self._pop_session("_errors", {}) if self._config.use_flash_errors else {}
+        # ``errors`` is the protocol's always-prop; keep the configured key
+        # pointing at the same dict so a custom flash_error_key still works.
+        if self._config.flash_error_key != "errors":
+            page_props[self._config.flash_error_key] = errors
+
+        resolved = await resolve_props(page_props, self._shared, component, self._req)
+        page = build_page(
+            component=component,
+            resolved=resolved,
+            url=str(self._request.url),
+            version=self._version,
+            errors=errors,
+            encrypt_history=self._encrypt_history,
+            clear_history=self._clear_history,
+            preserve_fragment=self._preserve_fragment,
+        )
+        if self._req.is_inertia:
+            return json_response(page)
+        return self._render_html(page)
+
+    def _render_html(self, page: dict[str, Any]) -> InertiaResponse:
+        files = entry_assets(self._config)
+        # encode_page yields a JSON-safe dict; htmlsafe_json_dumps serialises it
+        # exactly once with HTML-safe escaping. Passing a pre-dumped string here
+        # would double-encode the page object into a quoted JSON literal.
+        page_json = htmlsafe_json_dumps(encode_page(page))
+        context = {
+            "inertia": InertiaContext(
+                environment=self._config.environment,
+                dev_url=self._config.dev_url,
+                is_ssr=False,
+                data=cast(str, page_json),
+                js=files.js,
+                css=files.css,
+            ),
+            **self._config.extra_template_context,
+        }
+        return self._config.templates.TemplateResponse(
+            name=self._config.root_template_filename, request=self._request, context=context
+        )

simple_module_inertia/manifest.py

@@ -0,0 +1,70 @@
+"""Locate the entry's JS and CSS for the current environment.
+
+Vite keys its manifest by the entry's path relative to the Vite root
+(``"main.tsx"``); upstream looked it up as ``f"{root_directory}/{entrypoint}"``
+and ``KeyError``'d, which is why hosting used to rewrite the manifest file.
+Try Vite's key first, upstream's shape second, the first ``isEntry`` chunk
+last — and say which manifest was searched when none of them hit.
+"""
+
+from __future__ import annotations
+
+import json
+import posixpath
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from simple_module_inertia.config import InertiaConfig
+
+
+@dataclass
+class InertiaFiles:
+    js: str
+    css: list[str] = field(default_factory=list)
+
+
+@lru_cache
+def read_manifest(path: str) -> dict[str, Any]:
+    with Path(path).open(encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def _find_entry(manifest: dict[str, Any], config: InertiaConfig) -> dict[str, Any] | None:
+    keys = (
+        config.entrypoint_filename,
+        f"{config.root_directory}/{config.entrypoint_filename}",
+    )
+    for key in keys:
+        if key in manifest:
+            return manifest[key]
+    return next((chunk for chunk in manifest.values() if chunk.get("isEntry")), None)
+
+
+def _public(prefix: str, file: str) -> str:
+    return posixpath.join("/", prefix, file) if prefix else posixpath.join("/", file)
+
+
+def entry_assets(config: InertiaConfig) -> InertiaFiles:
+    if config.environment == "production" or config.ssr_enabled:
+        if not config.manifest_json_path:
+            raise LookupError(
+                "Production rendering needs InertiaConfig.manifest_json_path to point at "
+                "the built Vite manifest; it is empty"
+            )
+        manifest = read_manifest(config.manifest_json_path)
+        entry = _find_entry(manifest, config)
+        if entry is None:
+            raise LookupError(
+                f"No entry chunk for {config.entrypoint_filename!r} in {config.manifest_json_path}"
+            )
+        return InertiaFiles(
+            js=_public(config.assets_prefix, entry["file"]),
+            css=[_public(config.assets_prefix, f) for f in entry.get("css") or []],
+        )
+    root = config.root_directory.strip("/")
+    path = (
+        config.entrypoint_filename if root in ("", ".") else f"{root}/{config.entrypoint_filename}"
+    )
+    return InertiaFiles(js=f"{config.dev_url.rstrip('/')}/{path}")

simple_module_inertia/page.py

@@ -0,0 +1,105 @@
+"""Page-object assembly and serialisation.
+
+Two upstream defects are closed here rather than patched around it:
+
+* the page ``url`` is root-relative, as the protocol specifies — an absolute
+  url is handed to ``history.pushState`` and rejected behind a TLS-terminating
+  proxy (GH #223);
+* one encoder serves both the HTML and JSON branches, so a prop that renders
+  on a full page load also renders on a client-side visit.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlsplit
+
+from fastapi.encoders import jsonable_encoder
+
+from simple_module_inertia.resolve import ResolvedProps
+
+
+class PropEncodingError(ValueError):
+    """A prop could not be serialised; ``prop_path`` names it."""
+
+    def __init__(self, prop_path: str, cause: Exception) -> None:
+        self.prop_path = prop_path
+        super().__init__(f"Inertia prop {prop_path} is not JSON-serialisable: {cause}")
+
+
+def to_relative_url(url: str) -> str:
+    """Path-and-query only. Already-relative input is returned unchanged."""
+    try:
+        parts = urlsplit(url)
+    except ValueError:  # pragma: no cover - urlsplit is near-total
+        return url
+    if not parts.scheme and not parts.netloc:
+        return url
+    relative = parts.path or "/"
+    return f"{relative}?{parts.query}" if parts.query else relative
+
+
+def build_page(
+    *,
+    component: str,
+    resolved: ResolvedProps,
+    url: str,
+    version: str,
+    errors: dict[str, Any],
+    encrypt_history: bool = False,
+    clear_history: bool = False,
+    preserve_fragment: bool = False,
+) -> dict[str, Any]:
+    """The page object. Conditional fields are present only when set."""
+    page: dict[str, Any] = {
+        "component": component,
+        "props": {**resolved.props, "errors": errors},
+        "url": to_relative_url(url),
+        "version": version,
+    }
+    optional_fields: list[tuple[str, Any]] = [
+        ("deferredProps", resolved.deferred),
+        ("mergeProps", resolved.merge),
+        ("prependProps", resolved.prepend),
+        ("deepMergeProps", resolved.deep_merge),
+        ("matchPropsOn", resolved.match_on),
+        ("onceProps", resolved.once),
+        ("scrollProps", resolved.scroll),
+        ("sharedProps", resolved.shared),
+    ]
+    for key, value in optional_fields:
+        if value:
+            page[key] = value
+    for key, flag in (
+        ("encryptHistory", encrypt_history),
+        ("clearHistory", clear_history),
+        ("preserveFragment", preserve_fragment),
+    ):
+        if flag:
+            page[key] = True
+    return page
+
+
+def _locate_failure(value: Any, path: str) -> str:
+    """Find the deepest prop path that fails to encode, for the error message."""
+    if isinstance(value, dict):
+        for key, child in value.items():
+            try:
+                jsonable_encoder(child)
+            except Exception:
+                return _locate_failure(child, f"{path}.{key}")
+    elif isinstance(value, list):
+        for index, child in enumerate(value):
+            try:
+                jsonable_encoder(child)
+            except Exception:
+                return _locate_failure(child, f"{path}[{index}]")
+    return path
+
+
+def encode_page(page: dict[str, Any]) -> Any:
+    """JSON-safe structure for both render branches; names the failing prop."""
+    try:
+        return jsonable_encoder(page)
+    except Exception as exc:
+        raise PropEncodingError(_locate_failure(page["props"], "props"), exc) from exc

simple_module_inertia/props.py

@@ -0,0 +1,121 @@
+"""Prop wrappers.
+
+One frozen ``Prop`` carries every v3 flag; each factory sets one of them and
+accepts either a raw value or an existing ``Prop``, so wrappers compose by
+stacking: ``merge(defer(load_feed), match_on="id")``. The resolver reads the
+flags; nothing here talks to a request.
+"""
+
+from __future__ import annotations
+
+import inspect
+import warnings
+from dataclasses import dataclass, replace
+from typing import Any, Literal
+
+MergeMode = Literal["append", "prepend", "deep"]
+
+
+@dataclass(frozen=True)
+class ScrollMeta:
+    """Infinite-scroll cursor metadata, reported under ``scrollProps``."""
+
+    page_name: str
+    current_page: int
+    previous_page: int | None
+    next_page: int | None
+    reset: bool = False
+
+    def as_page_object(self) -> dict[str, Any]:
+        return {
+            "pageName": self.page_name,
+            "currentPage": self.current_page,
+            "previousPage": self.previous_page,
+            "nextPage": self.next_page,
+            "reset": self.reset,
+        }
+
+
+@dataclass(frozen=True)
+class Prop:
+    value: Any
+    optional: bool = False
+    always: bool = False
+    deferred_group: str | None = None
+    merge_mode: MergeMode | None = None
+    match_on: str | None = None
+    once_key: str | None = None
+    once_expires_at: int | None = None
+    scroll: ScrollMeta | None = None
+    # ``once(value)`` with no key still marks the prop as once; the key defaults
+    # to the prop name at resolve time. A private flag keeps that distinction
+    # without making ``once_key`` a sentinel.
+    _once_flag: bool = False
+
+    @property
+    def is_once(self) -> bool:
+        return self._once_flag
+
+
+def as_prop(value: Any) -> Prop:
+    return value if isinstance(value, Prop) else Prop(value)
+
+
+def optional(value: Any) -> Prop:
+    return replace(as_prop(value), optional=True)
+
+
+def always(value: Any) -> Prop:
+    return replace(as_prop(value), always=True)
+
+
+def defer(value: Any, group: str = "default") -> Prop:
+    return replace(as_prop(value), deferred_group=group)
+
+
+def merge(value: Any, match_on: str | None = None) -> Prop:
+    return replace(as_prop(value), merge_mode="append", match_on=match_on)
+
+
+def prepend(value: Any, match_on: str | None = None) -> Prop:
+    return replace(as_prop(value), merge_mode="prepend", match_on=match_on)
+
+
+def deep_merge(value: Any, match_on: str | None = None) -> Prop:
+    return replace(as_prop(value), merge_mode="deep", match_on=match_on)
+
+
+def once(value: Any, key: str | None = None, expires_at: int | None = None) -> Prop:
+    return replace(as_prop(value), once_key=key, once_expires_at=expires_at, _once_flag=True)
+
+
+def scroll(
+    value: Any,
+    *,
+    page_name: str,
+    current_page: int,
+    previous_page: int | None,
+    next_page: int | None,
+    reset: bool = False,
+) -> Prop:
+    if not page_name:
+        raise ValueError("scroll() requires a non-empty page_name")
+    meta = ScrollMeta(page_name, current_page, previous_page, next_page, reset)
+    return replace(as_prop(value), scroll=meta)
+
+
+def lazy(value: Any) -> Prop:
+    """Deprecated alias kept for callers migrating from fastapi-inertia."""
+    warnings.warn("lazy() is deprecated; use optional()", DeprecationWarning, stacklevel=2)
+    return optional(value)
+
+
+async def resolve_value(value: Any) -> Any:
+    """Unwrap a ``Prop``, call a callable, await an awaitable — recursively."""
+    if isinstance(value, Prop):
+        value = value.value
+    if callable(value):
+        value = value()
+    if inspect.isawaitable(value):
+        value = await value
+    return value

simple_module_inertia/request.py

@@ -0,0 +1,59 @@
+"""The request half of the protocol: every ``X-Inertia-*`` header, typed.
+
+A pure function of the header mapping and method — no Starlette ``Request``
+crosses this boundary, so the resolver and its conformance tests never need
+a server.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal
+
+MergeIntent = Literal["append", "prepend"]
+
+
+def _csv(value: str | None) -> frozenset[str]:
+    if not value:
+        return frozenset()
+    return frozenset(part.strip() for part in value.split(",") if part.strip())
+
+
+@dataclass(frozen=True)
+class InertiaRequest:
+    is_inertia: bool
+    version: str | None
+    partial_component: str | None
+    partial_data: frozenset[str]
+    partial_except: frozenset[str]
+    reset: frozenset[str]
+    error_bag: str | None
+    merge_intent: MergeIntent | None
+    except_once_props: frozenset[str]
+    is_prefetch: bool
+    method: str
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str], method: str) -> InertiaRequest:
+        lower = {k.lower(): v for k, v in headers.items()}
+        intent = (lower.get("x-inertia-infinite-scroll-merge-intent") or "").lower()
+        return cls(
+            is_inertia="x-inertia" in lower,
+            version=lower.get("x-inertia-version"),
+            partial_component=lower.get("x-inertia-partial-component") or None,
+            partial_data=_csv(lower.get("x-inertia-partial-data")),
+            partial_except=_csv(lower.get("x-inertia-partial-except")),
+            reset=_csv(lower.get("x-inertia-reset")),
+            error_bag=lower.get("x-inertia-error-bag") or None,
+            merge_intent=intent if intent in ("append", "prepend") else None,
+            except_once_props=_csv(lower.get("x-inertia-except-once-props")),
+            is_prefetch=(lower.get("purpose") or "").lower() == "prefetch",
+            method=method.upper(),
+        )
+
+    def is_partial_for(self, component: str) -> bool:
+        """A partial reload targets one component and names data or exclusions."""
+        return self.partial_component == component and bool(
+            self.partial_data or self.partial_except
+        )

simple_module_inertia/resolve.py

@@ -0,0 +1,99 @@
+"""Prop resolution — the v3 rules in one place.
+
+Input: the page's props, the shared props, the component being rendered and
+the typed request. Output: the resolved values plus every piece of metadata
+the page object announces (deferred groups, merge strategies, once keys,
+scroll cursors, shared keys). Nothing here knows about HTTP.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from simple_module_inertia.props import Prop, as_prop, resolve_value
+from simple_module_inertia.request import InertiaRequest
+
+
+@dataclass
+class ResolvedProps:
+    props: dict[str, Any] = field(default_factory=dict)
+    deferred: dict[str, list[str]] = field(default_factory=dict)
+    merge: list[str] = field(default_factory=list)
+    prepend: list[str] = field(default_factory=list)
+    deep_merge: list[str] = field(default_factory=list)
+    match_on: list[str] = field(default_factory=list)
+    once: dict[str, dict[str, Any]] = field(default_factory=dict)
+    scroll: dict[str, dict[str, Any]] = field(default_factory=dict)
+    shared: list[str] = field(default_factory=list)
+
+
+async def _deep_resolve(value: Any) -> Any:
+    """Resolve callables/awaitables/Props anywhere inside a container."""
+    value = await resolve_value(value)
+    if isinstance(value, dict):
+        return {k: await _deep_resolve(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [await _deep_resolve(v) for v in value]
+    return value
+
+
+def _wants(name: str, prop: Prop, req: InertiaRequest, partial: bool) -> bool:
+    """Should this prop's value be resolved for this response?"""
+    if prop.is_once and name in req.except_once_props:
+        return False
+    if prop.always:
+        return True
+    if partial:
+        if req.partial_data and name not in req.partial_data:
+            return False
+        return name not in req.partial_except
+    return prop.optional is False and prop.deferred_group is None
+
+
+def _announce_merge(name: str, prop: Prop, req: InertiaRequest, out: ResolvedProps) -> None:
+    if name in req.reset:
+        return
+    mode = prop.merge_mode
+    if prop.scroll is not None:
+        mode = req.merge_intent or "append"
+    if mode == "append":
+        out.merge.append(name)
+    elif mode == "prepend":
+        out.prepend.append(name)
+    elif mode == "deep":
+        out.deep_merge.append(name)
+    else:
+        return
+    if prop.match_on:
+        out.match_on.append(f"{name}.{prop.match_on}")
+
+
+async def resolve_props(
+    page_props: Mapping[str, Any],
+    shared_props: Mapping[str, Any],
+    component: str,
+    req: InertiaRequest,
+) -> ResolvedProps:
+    out = ResolvedProps()
+    partial = req.is_partial_for(component)
+    combined: dict[str, Any] = {**shared_props, **page_props}
+
+    for name, raw in combined.items():
+        prop = as_prop(raw)
+        if not partial and prop.deferred_group is not None:
+            out.deferred.setdefault(prop.deferred_group, []).append(name)
+        if prop.merge_mode is not None or prop.scroll is not None:
+            _announce_merge(name, prop, req, out)
+        if not _wants(name, prop, req, partial):
+            continue
+        out.props[name] = await _deep_resolve(prop)
+        if prop.is_once:
+            key = prop.once_key or name
+            out.once[key] = {"prop": name, "expiresAt": prop.once_expires_at}
+        if prop.scroll is not None:
+            out.scroll[name] = prop.scroll.as_page_object()
+
+    out.shared = [k for k in shared_props if k in out.props and k not in page_props]
+    return out

simple_module_inertia/response.py

@@ -0,0 +1,46 @@
+"""HTTP responses for each protocol outcome.
+
+``Vary: Accept`` is upstream's value and is kept on purpose: hosting's
+``InertiaCacheMiddleware`` appends ``X-Inertia`` on the way out and its tests
+pin today's header set.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import status
+from fastapi.responses import HTMLResponse, JSONResponse
+from starlette.responses import RedirectResponse, Response
+
+from simple_module_inertia.page import encode_page
+
+InertiaResponse = HTMLResponse | JSONResponse
+
+_JSON_HEADERS = {"X-Inertia": "true", "Vary": "Accept"}
+
+
+def json_response(page: dict[str, Any]) -> JSONResponse:
+    return JSONResponse(content=encode_page(page), headers=_JSON_HEADERS)
+
+
+def version_conflict(url: str, version: str) -> Response:
+    return Response(
+        status_code=status.HTTP_409_CONFLICT,
+        headers={"X-Inertia-Location": url, "X-Inertia-Version": version},
+    )
+
+
+def redirect(url: str, *, method: str) -> RedirectResponse:
+    code = (
+        status.HTTP_307_TEMPORARY_REDIRECT if method.upper() == "GET" else status.HTTP_303_SEE_OTHER
+    )
+    return RedirectResponse(url=url, status_code=code)
+
+
+def location(url: str) -> Response:
+    return Response(status_code=status.HTTP_409_CONFLICT, headers={"X-Inertia-Location": url})
+
+
+def fragment_redirect(url: str) -> Response:
+    return Response(status_code=status.HTTP_409_CONFLICT, headers={"X-Inertia-Redirect": url})

simple_module_inertia/templating.py

@@ -0,0 +1,74 @@
+"""Jinja glue: the template context and the ``inertia_head``/``inertia_body`` tags.
+
+Ported from upstream. The SSR branches stay so the template contract is the
+same, but nothing in this package calls an SSR server.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from jinja2 import nodes
+from jinja2.ext import Extension
+from jinja2.parser import Parser
+from jinja2.runtime import Context
+from markupsafe import Markup
+
+
+@dataclass
+class InertiaContext:
+    environment: Literal["development", "production"]
+    dev_url: str
+    css: list[str]
+    js: str
+    is_ssr: bool
+    data: str | None = None
+    ssr_head: str | None = None
+    ssr_body: str | None = None
+
+
+class InertiaExtension(Extension):
+    tags = {"inertia_head", "inertia_body"}  # noqa: RUF012 - Jinja declares this an instance attr
+
+    def parse(self, parser: Parser) -> nodes.Node:
+        tag_name = next(parser.stream).value
+        lineno = parser.stream.current.lineno
+        node = self.call_method(f"_render_{tag_name}", [nodes.ContextReference()], lineno=lineno)
+        return nodes.Output([node]).set_lineno(lineno)
+
+    def _render_inertia_head(self, context: Context) -> Markup:
+        inertia: InertiaContext = context["inertia"]
+        fragments: list[str] = []
+        if inertia.environment == "development":
+            fragments.append(
+                f'<script type="module" src="{inertia.dev_url}/@vite/client"></script>'
+            )
+        if inertia.is_ssr:
+            if inertia.ssr_head is None:
+                raise ValueError("SSR is enabled but no SSR head was provided")
+            fragments.append(inertia.ssr_head)
+        fragments.extend(f'<link rel="stylesheet" href="{css}">' for css in inertia.css)
+        return Markup("\n".join(fragments))
+
+    def _render_inertia_body(self, context: Context) -> Markup:
+        inertia: InertiaContext = context["inertia"]
+        fragments: list[str] = []
+        if inertia.is_ssr:
+            if inertia.ssr_body is None:
+                raise ValueError("SSR is enabled but no SSR body was provided")
+            fragments.append(inertia.ssr_body)
+        else:
+            if inertia.data is None:
+                raise ValueError("No data was provided for the Inertia page")
+            # Inertia 3's getInitialPageFromDOM reads only the JSON script
+            # element; Inertia 2 read only the data-page attribute. Emit both
+            # so the adapter ships before the client migrates and keeps working
+            # after. ``data`` is htmlsafe_json_dumps output, so it cannot break
+            # out of either the attribute or the script element.
+            fragments.append(
+                f'<script data-page="app" type="application/json">{inertia.data}</script>'
+            )
+            fragments.append(f"<div id=\"app\" data-page='{inertia.data}'></div>")
+        fragments.append(f'<script type="module" src="{inertia.js}"></script>')
+        return Markup("\n".join(fragments))

simple_module_inertia-0.0.35.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: simple_module_inertia
+Version: 0.0.35
+Summary: Inertia.js v3 server adapter for FastAPI — the protocol half of simple_module's React frontend
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: fastapi,inertia,inertiajs,react,simple-module
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: jinja2>=3.1
+Requires-Dist: starlette>=0.44
+Description-Content-Type: text/markdown
+
+# simple_module_inertia
+
+Inertia.js **v3** server adapter for FastAPI. This is the protocol half of a
+simple_module app's React frontend: it turns `inertia.render("Users/Index", props)`
+into either the JSON page object an Inertia visit expects or the HTML document a
+full page load expects, and implements every v3 prop type (`optional`, `always`,
+`defer`, `merge`, `prepend`, `deep_merge`, `once`, `scroll`).
+
+Forked from [fastapi-inertia](https://github.com/hxjo/fastapi-inertia) (MIT) —
+see `NOTICE`. Precognition and SSR are not implemented.
+
+## Install
+
+`simple_module_hosting` depends on this package, so any app scaffolded with
+`smpy new` already has it. To use the adapter on its own:
+
+```bash
+uv add simple_module_inertia
+```
+
+## Usage
+
+Inside a simple_module app, reach the per-request `Inertia` instance through
+`InertiaDep` and import the response type and prop factories from here:
+
+```python
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_inertia import InertiaResponse, defer, merge, optional
+
+
+async def index(inertia: InertiaDep) -> InertiaResponse:
+    return await inertia.render(
+        "Feed/Index",
+        {
+            "posts": merge(load_posts, match_on="id"),  # append on navigation
+            "analytics": defer(load_analytics),  # loaded after first paint
+            "stats": optional(load_stats),  # only on partial reloads that ask
+        },
+    )
+```
+
+Standalone, configure it once and register the two exception handlers:
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi.templating import Jinja2Templates
+from simple_module_inertia import (
+    Inertia,
+    InertiaConfig,
+    InertiaVersionConflictException,
+    inertia_dependency_factory,
+    inertia_version_conflict_exception_handler,
+)
+
+config = InertiaConfig(
+    templates=Jinja2Templates(directory="templates"),
+    entrypoint_filename="main.tsx",
+    root_directory=".",
+    dev_url="http://localhost:5173",
+)
+inertia_dep = inertia_dependency_factory(config)
+
+app = FastAPI()
+app.add_exception_handler(
+    InertiaVersionConflictException, inertia_version_conflict_exception_handler
+)
+
+
+@app.get("/")
+async def home(inertia: Inertia = Depends(inertia_dep)):
+    return await inertia.render("Home", {"greeting": "hello"})
+```
+
+The root template needs `{% inertia_head %}` in `<head>` and `{% inertia_body %}`
+in `<body>`; the page object lands in `<div id="app" data-page="…">`.

simple_module_inertia-0.0.35.dist-info/RECORD

@@ -0,0 +1,18 @@
+simple_module_inertia/__init__.py,sha256=m4a7iyProurReZX_H2W0usjUOLdzzYIH1XaTyiX7rkg,1218
+simple_module_inertia/config.py,sha256=cGcID9UV4TmnY95eoDNKQ74WOZcL4S9lpSX40nww7xY,1461
+simple_module_inertia/deps.py,sha256=YkqA2WFOqoki84urzdiwCz1MBWu69G86SvJhj-s2-z4,740
+simple_module_inertia/errors.py,sha256=sMjXj59P2uQLL2jh4YEVyz8VxmPzTHNulvyJgYJ4mx8,1842
+simple_module_inertia/inertia.py,sha256=gLKyKxAyW9bsAqSMxmMdN71AfieOnYD0S_oB5Jt35nU,5597
+simple_module_inertia/manifest.py,sha256=Y5R3bUzuoOFCHPuYhI0j5UsmYfjK07xwtYC60Sn_Wyc,2473
+simple_module_inertia/page.py,sha256=hyZQTGLXJvKTWUNwE3ZCUflE02_4cRloQkjrIBT_6kE,3463
+simple_module_inertia/props.py,sha256=p3jCLjbauW2NEpOTVZ40Q2QRhf-ulkN5LpMvhYzGVMc,3554
+simple_module_inertia/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simple_module_inertia/request.py,sha256=SvqkN3V_xxcPwR6qr7ANM96fWPavZFLr6-esUarWPq8,2197
+simple_module_inertia/resolve.py,sha256=RJsJRRwO0Wx0Fvu70QMxdGFyZIVFFWqRY1s5Jqo59Gk,3598
+simple_module_inertia/response.py,sha256=kSjJIB6F-GaXx512JmRQqz-ivot2zDDhBr16emX-Fkk,1436
+simple_module_inertia/templating.py,sha256=814QcF8P4yQ6fJbvEn0CMyO_g7uTEtgW-n74w3aW88o,3010
+simple_module_inertia-0.0.35.dist-info/METADATA,sha256=wq0SaiBR5dQwmiEY1VhdoFNK17Zner82n9CbQw_WdyE,3590
+simple_module_inertia-0.0.35.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+simple_module_inertia-0.0.35.dist-info/licenses/LICENSE,sha256=Yn66lhLklsF5p7pa85_ksQrJ79Q-FgOaUAHevLBjer4,1068
+simple_module_inertia-0.0.35.dist-info/licenses/NOTICE,sha256=DSPMTNIt3v8BzJXayZth8xzn72FMhfFigTNxmzMFzpk,1266
+simple_module_inertia-0.0.35.dist-info/RECORD,,

simple_module_inertia-0.0.35.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

simple_module_inertia-0.0.35.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anto Subash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simple_module_inertia-0.0.35.dist-info/licenses/NOTICE

@@ -0,0 +1,25 @@
+This package is a fork of fastapi-inertia 1.1.0 (https://github.com/hxjo/fastapi-inertia),
+distributed under the MIT License. The original license text follows, as the
+MIT License requires.
+
+The MIT License (MIT)
+
+Copyright (c) 2022 Bellawatt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.