simple-module-inertia 0.0.35__tar.gz

simple_module_inertia-0.0.35/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# VitePress (docs)
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+host/client_app/modules.assets.json
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/
+.qa/
+.verify/

simple_module_inertia-0.0.35/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/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.

simple_module_inertia-0.0.35/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,75 @@
+# 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/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "simple_module_inertia"
+version = "0.0.35"
+description = "Inertia.js v3 server adapter for FastAPI — the protocol half of simple_module's React frontend"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.12"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "inertia", "inertiajs", "fastapi", "react"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastapi>=0.115",
+    "jinja2>=3.1",
+    "starlette>=0.44",
+]
+
+[project.urls]
+Homepage = "https://github.com/antosubash/simple_module_python"
+Repository = "https://github.com/antosubash/simple_module_python"
+Issues = "https://github.com/antosubash/simple_module_python/issues"
+Changelog = "https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["simple_module_inertia"]

simple_module_inertia-0.0.35/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-0.0.35/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-0.0.35/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-0.0.35/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-0.0.35/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
+        )