react-router-routes 0.2.0__tar.gz

react_router_routes-0.2.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.3
+Name: react-router-routes
+Version: 0.2.0
+Summary: Generate strongly-typed Python helpers (TypedDict param classes + path/url builders) from a React Router v6+ route tree so Python code can build frontend URLs safely.
+Keywords: react-router,router,routes,url-generation,typed-routes,typed,cli,backend,frontend,integration
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+Requires-Dist: typer>=0.12.5
+Requires-Dist: jinja2>=3.1.4
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/iloveitaly/react-router-routes
+Description-Content-Type: text/markdown
+
+# Generate Typed Python URL helpers from React Router routes
+
+Generate strongly-typed Python helpers (TypedDict param objects + overloads) from a React Router v6+ route tree. This is useful when a Python backend, worker, or test suite needs to construct URLs that stay in sync with a JavaScript/TypeScript frontend using React Router.
+
+## What you get
+
+Given a React Router project, the CLI either:
+
+* Runs `pnpm react-router routes --json` (if you pass `--directory`), or
+* Reads a pre-generated JSON file (if you pass `--json-file`)
+
+It walks the returned route objects and produces a Python module containing:
+
+* `RoutePaths` Literal of every concrete route pattern (e.g. `/users/:userId?`, `/files/*`).
+* Per-route `TypedDict` classes containing snake_case parameter keys.
+* Overloaded `react_router_path()` to build a relative path with validation + percent-encoding.
+* Overloaded `react_router_url()` to prepend a base URL (explicit argument or `BASE_URL` env var).
+
+## Installation
+
+Requires Python 3.11+.
+
+Using uv (recommended):
+
+```bash
+uv add react-router-routes
+```
+
+Or with pip:
+
+```bash
+pip install react-router-routes
+```
+
+## Prerequisites
+
+Your JS project must have `react-router` and the `pnpm react-router routes --json` command available (React Router v6+ data APIs). The Python process must run inside (or have access to) that project directory so the CLI can execute the command.
+
+## CLI Usage
+
+The script entry point is named `react-router-routes` (see `pyproject.toml`).
+
+Two ways to supply routes:
+
+1. Have the tool invoke `pnpm react-router routes --json` by providing a directory:
+
+```bash
+react-router-routes ./routes_typing.py --directory ./frontend
+```
+
+1. Provide an existing JSON file (output of `pnpm react-router routes --json`):
+
+```bash
+react-router-routes ./routes_typing.py --json-file tests/react-router.json
+```
+
+Then import the generated module in Python code:
+
+```python
+from routes_typing import react_router_path, react_router_url, RoutePaths
+
+react_router_path('/users/:userId', {'user_id': 123})  # -> '/users/123'
+react_router_url('/files/*', {'splat': 'docs/readme.md'}, base_url='https://example.com')
+```
+
+ 
+## Environment Variables
+
+* `BASE_URL` (optional) – If set and you omit `base_url` when calling `react_router_url`, this value is prepended. If missing the function returns the path and logs a warning.
+* `LOG_LEVEL` (optional) – Standard Python logging level (INFO, DEBUG, etc.).
+
+ 
+## Development
+
+Clone and install dev deps:
+
+```bash
+uv sync --group dev
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+ 
+## Release process
+
+This project uses `uv` for building and publishing. Adjust version in `pyproject.toml`, then build and publish as desired.
+
+ 
+## License
+
+MIT (see repository).

react_router_routes-0.2.0/README.md

@@ -0,0 +1,95 @@
+# Generate Typed Python URL helpers from React Router routes
+
+Generate strongly-typed Python helpers (TypedDict param objects + overloads) from a React Router v6+ route tree. This is useful when a Python backend, worker, or test suite needs to construct URLs that stay in sync with a JavaScript/TypeScript frontend using React Router.
+
+## What you get
+
+Given a React Router project, the CLI either:
+
+* Runs `pnpm react-router routes --json` (if you pass `--directory`), or
+* Reads a pre-generated JSON file (if you pass `--json-file`)
+
+It walks the returned route objects and produces a Python module containing:
+
+* `RoutePaths` Literal of every concrete route pattern (e.g. `/users/:userId?`, `/files/*`).
+* Per-route `TypedDict` classes containing snake_case parameter keys.
+* Overloaded `react_router_path()` to build a relative path with validation + percent-encoding.
+* Overloaded `react_router_url()` to prepend a base URL (explicit argument or `BASE_URL` env var).
+
+## Installation
+
+Requires Python 3.11+.
+
+Using uv (recommended):
+
+```bash
+uv add react-router-routes
+```
+
+Or with pip:
+
+```bash
+pip install react-router-routes
+```
+
+## Prerequisites
+
+Your JS project must have `react-router` and the `pnpm react-router routes --json` command available (React Router v6+ data APIs). The Python process must run inside (or have access to) that project directory so the CLI can execute the command.
+
+## CLI Usage
+
+The script entry point is named `react-router-routes` (see `pyproject.toml`).
+
+Two ways to supply routes:
+
+1. Have the tool invoke `pnpm react-router routes --json` by providing a directory:
+
+```bash
+react-router-routes ./routes_typing.py --directory ./frontend
+```
+
+1. Provide an existing JSON file (output of `pnpm react-router routes --json`):
+
+```bash
+react-router-routes ./routes_typing.py --json-file tests/react-router.json
+```
+
+Then import the generated module in Python code:
+
+```python
+from routes_typing import react_router_path, react_router_url, RoutePaths
+
+react_router_path('/users/:userId', {'user_id': 123})  # -> '/users/123'
+react_router_url('/files/*', {'splat': 'docs/readme.md'}, base_url='https://example.com')
+```
+
+ 
+## Environment Variables
+
+* `BASE_URL` (optional) – If set and you omit `base_url` when calling `react_router_url`, this value is prepended. If missing the function returns the path and logs a warning.
+* `LOG_LEVEL` (optional) – Standard Python logging level (INFO, DEBUG, etc.).
+
+ 
+## Development
+
+Clone and install dev deps:
+
+```bash
+uv sync --group dev
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+ 
+## Release process
+
+This project uses `uv` for building and publishing. Adjust version in `pyproject.toml`, then build and publish as desired.
+
+ 
+## License
+
+MIT (see repository).

react_router_routes-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "react-router-routes"
+version = "0.2.0"
+description = "Generate strongly-typed Python helpers (TypedDict param classes + path/url builders) from a React Router v6+ route tree so Python code can build frontend URLs safely."
+keywords = [
+	"react-router",
+	"router",
+	"routes",
+	"url-generation",
+	"typed-routes",
+	"typed",
+	"cli",
+	"backend",
+	"frontend",
+	"integration",
+]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["typer>=0.12.5", "jinja2>=3.1.4"]
+authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
+urls = { "Repository" = "https://github.com/iloveitaly/react-router-routes" }
+
+# additional packaging information: https://packaging.python.org/en/latest/specifications/core-metadata/#license
+[project.scripts]
+react-router-routes = "react_router_routes:main"
+
+[build-system]
+requires = ["uv_build>=0.8.11,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# avoids the src/ directory structure
+module-root = ""
+
+[dependency-groups]
+dev = ["pytest>=8.3.3"]

react_router_routes-0.2.0/react_router_routes/__init__.py

@@ -0,0 +1,28 @@
+"""Package entrypoint for the react-router-routes CLI.
+
+Running the installed script (configured via [project.scripts]) will
+invoke Typer's CLI defined in `generate.py`.
+"""
+
+import logging
+import os
+
+from .generate import app
+
+logging.basicConfig(
+    level=os.environ.get("LOG_LEVEL", "INFO").upper(),
+)
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:  # console_scripts entry point
+    """Dispatch to the Typer application.
+
+    Example:
+        react-router-routes generate-route-types ./js-app ./routes_typing.py
+    """
+    app()
+
+
+__all__ = ["main", "app"]

react_router_routes-0.2.0/react_router_routes/generate.py

@@ -0,0 +1,282 @@
+"""
+py app/lib/react_router_generate.py web/ ./react_router_routes.py
+"""
+
+import json
+import re
+import subprocess
+from pathlib import Path
+
+import typer
+from jinja2 import Environment
+
+app = typer.Typer()
+
+
+def collect_route_patterns(routes: list[dict], parent_path: str = "") -> list[str]:
+    patterns: list[str] = []
+    for route in routes:
+        # Clean up path by collapsing repeated slashes and removing trailing slashes
+        raw = f"{parent_path}/{route.get('path', '')}"
+        current_path = re.sub(r"/{2,}", "/", raw).rstrip("/") or "/"
+        if "file" in route and ("path" in route or "index" in route):
+            patterns.append(current_path)
+        if "children" in route:
+            patterns.extend(collect_route_patterns(route["children"], current_path))
+
+    # De-duplicate while preserving order
+    deduped: list[str] = []
+    seen: set[str] = set()
+    for p in patterns:
+        if p not in seen:
+            seen.add(p)
+            deduped.append(p)
+    return deduped
+
+
+def camel_to_snake(name: str) -> str:
+    out: list[str] = []
+    for ch in name:
+        if ch.isupper():
+            if out:
+                out.append("_")
+            out.append(ch.lower())
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+def segment_to_pascal(segment: str) -> str:
+    if not segment:
+        return ""
+    parts = re.split(r"[^A-Za-z0-9]+", segment)
+    return "".join(s[:1].upper() + s[1:] for s in parts if s)
+
+
+def pattern_to_class_name(pattern: str) -> str:
+    if pattern == "/":
+        return "RootParams"
+    name_parts: list[str] = []
+    for seg in pattern.strip("/").split("/"):
+        if not seg:
+            continue
+        if seg == "*":
+            name_parts.append("Splat")
+            continue
+        if seg.startswith(":"):
+            token = seg.lstrip(":").rstrip("?")
+            name_parts.append(segment_to_pascal(token))
+            continue
+        name_parts.append(segment_to_pascal(seg))
+    base = "".join(name_parts) or "Root"
+    return f"{base}Params"
+
+
+def parse_params(pattern: str) -> tuple[list[tuple[str, bool]], bool]:
+    """Return ([(param_name, is_optional)], has_splat). param_name is the token as written (camelCase)."""
+    params: list[tuple[str, bool]] = []
+    for m in re.finditer(r":([A-Za-z0-9_]+)(\?)?", pattern):
+        name = m.group(1)
+        is_optional = m.group(2) is not None
+        params.append((name, is_optional))
+    has_splat = "*" in pattern
+    return params, has_splat
+
+
+JINJA_TEMPLATE = r'''
+"""AUTOGENERATED FILE: Do not edit manually.
+Generated by react-router-routes from the React Router config.
+
+- RoutePaths is a Literal of route patterns
+- Per-route TypedDicts define snake_case keys for params
+- react_router_path builds a path from a pattern and params
+- react_router_url prepends BASE_URL (env) or an explicit base_url
+"""
+from typing import Literal, overload, TypedDict, Mapping, NotRequired
+import re
+from urllib.parse import quote
+import os
+import logging
+
+logger = logging.getLogger("react_router_routes.generated")
+
+RoutePaths = Literal[{% for p in patterns %}{% if not loop.first %}, {% endif %}"{{ p }}"{% endfor %}]
+
+{% for r in routes if r.params or r.has_splat %}
+class {{ r.class_name }}(TypedDict):
+{% if r.has_splat %}
+    splat: str
+{% endif %}
+{% for p in r.params %}
+    {{ p.snake }}: {% if p.optional %}NotRequired[str]{% else %}str{% endif %}
+{% endfor %}
+
+{% endfor %}
+
+ALIAS_MAP: dict[str, dict[str, str]] = {
+{% for r in routes if r.alias_map %}
+    "{{ r.pattern }}": {
+        {% for k,v in r.alias_map.items() %}"{{ k }}": "{{ v }}"{% if not loop.last %},
+        {% endif %}{% endfor %}
+    },
+{% endfor %}
+}
+
+# overloads for path
+{% for r in routes %}
+{% if r.params or r.has_splat %}
+@overload
+def react_router_path(path: Literal["{{ r.pattern }}"], params: {{ r.class_name }}, /) -> str: ...
+@overload
+def react_router_path(path: Literal["{{ r.pattern }}"], params: Mapping[str, object], /) -> str: ...
+{% else %}
+@overload
+def react_router_path(path: Literal["{{ r.pattern }}"], params: None | Mapping[str, object] = None, /) -> str: ...
+{% endif %}
+{% endfor %}
+@overload
+def react_router_path(path: RoutePaths, params: None | Mapping[str, object] = None, /) -> str: ...
+
+def react_router_path(path: RoutePaths, params: Mapping[str, object] | None = None) -> str:
+    """Render a URL path from a typed pattern and params.
+
+    - Accepts snake_case or original token keys (via ALIAS_MAP)
+    - Replaces required ":name" and optional ":name?" tokens
+    - Replaces "*" with the "splat" param
+    - Percent-encodes values (splat keeps "/")
+    """
+    values: dict[str, object] = {} if params is None else dict(params)
+    alias = ALIAS_MAP.get(path, {})
+    # accept both snake_case and original token keys
+    for k, v in list(values.items()):
+        if k in alias:
+            values[alias[k]] = v
+
+    rendered = path
+
+    def _replace_optional(match: re.Match[str]) -> str:
+        name = match.group(1)
+        if name in values:
+            return quote(str(values[name]), safe="")
+        return ""
+
+    rendered = re.sub(r":([A-Za-z0-9_]+)\?", _replace_optional, rendered)
+
+    def _replace_required(match: re.Match[str]) -> str:
+        name = match.group(1)
+        assert name in values, f"missing required param: {name}"
+        return quote(str(values[name]), safe="")
+
+    rendered = re.sub(r":([A-Za-z0-9_]+)(?!\?)", _replace_required, rendered)
+
+    if "*" in rendered:
+        assert "splat" in values, "missing required param: splat"
+        rendered = rendered.replace("*", quote(str(values["splat"]), safe="/"))
+
+    rendered = re.sub(r"/{2,}", "/", rendered)
+    if rendered != "/" and rendered.endswith("/"):
+        rendered = rendered[:-1]
+    return rendered
+
+# overloads for url
+{% for r in routes %}
+{% if r.params or r.has_splat %}
+@overload
+def react_router_url(path: Literal["{{ r.pattern }}"], params: {{ r.class_name }}, base_url: str | None = None, /) -> str: ...
+@overload
+def react_router_url(path: Literal["{{ r.pattern }}"], params: Mapping[str, object], base_url: str | None = None, /) -> str: ...
+{% else %}
+@overload
+def react_router_url(path: Literal["{{ r.pattern }}"], params: None | Mapping[str, object] = None, base_url: str | None = None, /) -> str: ...
+{% endif %}
+{% endfor %}
+@overload
+def react_router_url(path: RoutePaths, params: None | Mapping[str, object] = None, base_url: str | None = None, /) -> str: ...
+
+def react_router_url(path: RoutePaths, params: Mapping[str, object] | None = None, base_url: str | None = None) -> str:
+    """Build a full URL by prepending base_url or ENV BASE_URL to the path."""
+    built = react_router_path(path, params)
+    base = base_url if base_url is not None else os.environ.get("BASE_URL")
+    if not base:
+        logger.warning("BASE_URL missing; returning path only: %s", path)
+        return built
+
+    return base.rstrip("/") + built
+'''
+
+
+def render_routes_module(patterns: list[str]) -> str:
+    # Build context for Jinja
+    routes = []
+    for pattern in patterns:
+        params, has_splat = parse_params(pattern)
+        route = {
+            "pattern": pattern,
+            "class_name": pattern_to_class_name(pattern),
+            "has_splat": has_splat,
+            "params": [
+                {
+                    "name": token,
+                    "snake": camel_to_snake(token),
+                    "optional": is_optional,
+                }
+                for token, is_optional in params
+            ],
+            "alias_map": {camel_to_snake(token): token for token, _ in params},
+        }
+        routes.append(route)
+
+    env = Environment()
+    template = env.from_string(JINJA_TEMPLATE)
+    return template.render(patterns=patterns, routes=routes) + "\n"
+
+
+@app.command()
+def generate_route_types(
+    output_file: Path = typer.Argument(
+        ..., help="Path to output routes_typing.py file"
+    ),
+    directory: Path | None = typer.Option(
+        None,
+        "--directory",
+        "-d",
+        help="Path to React Router project directory (used to invoke 'pnpm react-router routes --json')",
+    ),
+    json_file: Path | None = typer.Option(
+        None,
+        "--json-file",
+        "-j",
+        help="Path to an existing react-router routes JSON file (skips invoking pnpm)",
+    ),
+):
+    """Generate Python route typings and helpers from React Router routes.
+
+    You must supply either --json-file or --directory. If both are supplied, --json-file wins.
+    """
+
+    if json_file is None and directory is None:
+        raise typer.BadParameter("Provide either --json-file or --directory")
+
+    if json_file is not None:
+        routes_json = json.loads(json_file.read_text())
+    else:
+        # Fallback to invoking the CLI
+        result = subprocess.run(
+            ["pnpm", "react-router", "routes", "--json"],
+            cwd=directory,
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            typer.echo(f"Error running react-router: {result.stderr}")
+            raise typer.Exit(1)
+        routes_json = json.loads(result.stdout)
+
+    patterns = collect_route_patterns(routes_json)
+    content = render_routes_module(patterns)
+    output_file.write_text(content)
+
+
+if __name__ == "__main__":
+    app()