react-router-routes 0.3.0__tar.gz

react_router_routes-0.3.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.3
+Name: react-router-routes
+Version: 0.3.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-Dist: structlog-config>=0.8.0
+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.
+
+[Take a look at this project for a live usage example.](https://github.com/iloveitaly/python-starter-template/blob/0946513b9430c1cd4eb2b115ea596ae2ffc6994a/just/python.just#L61-L62)
+
+## How it works
+
+Given a React Router project, the CLI either:
+
+* Auto-detects your package manager (bun, pnpm, or npm) and runs `<package-manager> 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).
+* Optional `url_params` argument on both functions to append query string parameters.
+
+## 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 a package manager with the `react-router routes --json` command available (React Router v6+ data APIs). The tool automatically detects your package manager (bun, pnpm, or npm) based on lockfiles and availability. 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 `<package-manager> react-router routes --json` by providing a directory (auto-detects bun, pnpm, or npm):
+
+```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
+
+# Basic path generation
+react_router_path('/users/:userId', {'user_id': 123})  # -> '/users/123'
+
+# URL generation with base URL
+react_router_url('/files/*', {'splat': 'docs/readme.md'}, base_url='https://example.com')
+# -> 'https://example.com/files/docs/readme.md'
+
+# Adding query parameters with url_params
+react_router_path('/users/:userId', {'user_id': 123}, url_params={'tab': 'profile', 'edit': 'true'})
+# -> '/users/123?tab=profile&edit=true'
+
+react_router_url('/home', base_url='https://example.com', url_params={'page': '1', 'sort': 'name'})
+# -> 'https://example.com/home?page=1&sort=name'
+```
+
+
+## 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
+```
+
+## [MIT License](LICENSE)

react_router_routes-0.3.0/README.md

@@ -0,0 +1,101 @@
+# 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.
+
+[Take a look at this project for a live usage example.](https://github.com/iloveitaly/python-starter-template/blob/0946513b9430c1cd4eb2b115ea596ae2ffc6994a/just/python.just#L61-L62)
+
+## How it works
+
+Given a React Router project, the CLI either:
+
+* Auto-detects your package manager (bun, pnpm, or npm) and runs `<package-manager> 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).
+* Optional `url_params` argument on both functions to append query string parameters.
+
+## 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 a package manager with the `react-router routes --json` command available (React Router v6+ data APIs). The tool automatically detects your package manager (bun, pnpm, or npm) based on lockfiles and availability. 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 `<package-manager> react-router routes --json` by providing a directory (auto-detects bun, pnpm, or npm):
+
+```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
+
+# Basic path generation
+react_router_path('/users/:userId', {'user_id': 123})  # -> '/users/123'
+
+# URL generation with base URL
+react_router_url('/files/*', {'splat': 'docs/readme.md'}, base_url='https://example.com')
+# -> 'https://example.com/files/docs/readme.md'
+
+# Adding query parameters with url_params
+react_router_path('/users/:userId', {'user_id': 123}, url_params={'tab': 'profile', 'edit': 'true'})
+# -> '/users/123?tab=profile&edit=true'
+
+react_router_url('/home', base_url='https://example.com', url_params={'page': '1', 'sort': 'name'})
+# -> 'https://example.com/home?page=1&sort=name'
+```
+
+
+## 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
+```
+
+## [MIT License](LICENSE)

react_router_routes-0.3.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "react-router-routes"
+version = "0.3.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", "structlog-config>=0.8.0"]
+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.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# avoids the src/ directory structure
+module-root = ""
+
+[dependency-groups]
+dev = ["pytest>=8.3.3", "pyright[nodejs]>=1.1.380", "ruff>=0.8.0"]
+
+[tool.pyright]
+exclude = ["examples/", "playground/", "tmp/", ".venv/", "tests/"]
+
+[tool.ruff]
+extend-exclude = ["playground.py", "playground/"]

react_router_routes-0.3.0/react_router_routes/__init__.py

@@ -0,0 +1,23 @@
+"""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`.
+"""
+
+from structlog_config import configure_logger
+
+from .generate import app
+
+logger = configure_logger()
+
+
+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.3.0/react_router_routes/generate.py

@@ -0,0 +1,383 @@
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+import typer
+from jinja2 import Environment
+from structlog_config import configure_logger
+
+app = typer.Typer()
+log = configure_logger()
+
+
+def detect_package_manager(directory: Path) -> str:
+    """Detect which package manager to use based on lockfiles and availability."""
+    lockfile_to_manager = {
+        "bun.lockb": "bun",
+        "pnpm-lock.yaml": "pnpm",
+        "package-lock.json": "npm",
+        "yarn.lock": "yarn",
+    }
+
+    for lockfile, manager in lockfile_to_manager.items():
+        if not (directory / lockfile).exists():
+            continue
+
+        if _is_package_manager_available(manager):
+            return manager
+
+    for manager in ["bun", "pnpm", "npm"]:
+        if _is_package_manager_available(manager):
+            return manager
+
+    return "npm"
+
+
+def _is_package_manager_available(manager: str) -> bool:
+    """Check if package manager is available on system."""
+    try:
+        subprocess.run([manager, "--version"], capture_output=True, check=True)
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def lint_generated_file(output_file: Path) -> None:
+    """Automatically lint the generated file with ruff if available."""
+    try:
+        # Check if ruff is available
+        subprocess.run(
+            ["ruff", "--version"],
+            capture_output=True,
+            check=True,
+        )
+
+        # Run ruff check with --fix to automatically fix issues
+        subprocess.run(
+            ["ruff", "check", "--fix", str(output_file)],
+            capture_output=True,
+            check=False,  # Don't fail if there are lint errors
+        )
+
+        # Run ruff format to format the code
+        subprocess.run(
+            ["ruff", "format", str(output_file)],
+            capture_output=True,
+            check=False,  # Don't fail if formatting changes are made
+        )
+
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        # ruff is not available or failed, continue silently
+        pass
+
+
+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, urlencode
+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 }}, *, url_params: dict[str, str] | None = None) -> str: ...
+@overload
+def react_router_path(path: Literal["{{ r.pattern }}"], params: Mapping[str, object], *, url_params: dict[str, str] | None = None) -> str: ...
+{% else %}
+@overload
+def react_router_path(path: Literal["{{ r.pattern }}"], params: None | Mapping[str, object] = None, *, url_params: dict[str, str] | None = None) -> str: ...
+{% endif %}
+{% endfor %}
+@overload
+def react_router_path(path: RoutePaths, params: None | Mapping[str, object] = None, *, url_params: dict[str, str] | None = None) -> str: ...
+
+def react_router_path(path: RoutePaths, params: Mapping[str, object] | None = None, *, url_params: dict[str, str] | 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 "/")
+    - Appends query parameters from url_params if provided
+    """
+    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]
+
+    # Append query parameters if provided
+    if url_params:
+        query_string = urlencode(url_params)
+        rendered += f"?{query_string}"
+
+    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, url_params: dict[str, str] | None = None) -> str: ...
+@overload
+def react_router_url(path: Literal["{{ r.pattern }}"], params: Mapping[str, object], *, base_url: str | None = None, url_params: dict[str, 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, url_params: dict[str, str] | None = None) -> str: ...
+{% endif %}
+{% endfor %}
+@overload
+def react_router_url(path: RoutePaths, params: None | Mapping[str, object] = None, *, base_url: str | None = None, url_params: dict[str, str] | None = None) -> str: ...
+
+def react_router_url(path: RoutePaths, params: Mapping[str, object] | None = None, *, base_url: str | None = None, url_params: dict[str, 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, url_params=url_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 (auto-detects package manager: bun, pnpm, or npm)",
+    ),
+    json_file: Path | None = typer.Option(
+        None,
+        "--json-file",
+        "-j",
+        help="Path to an existing react-router routes JSON file (skips package manager detection)",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Enable debug logging",
+    ),
+):
+    """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 verbose:
+        os.environ["LOG_LEVEL"] = "DEBUG"
+        global log
+        log = configure_logger()
+
+    if json_file is not None:
+        routes_json = json.loads(json_file.read_text())
+    else:
+        if directory is None:
+            directory = Path.cwd()
+            log.info("using default directory", directory=directory)
+
+        # Detect and use appropriate package manager
+        package_manager = detect_package_manager(directory)
+        typer.echo(f"Using package manager: {package_manager}")
+
+        result = subprocess.run(
+            [package_manager, "react-router", "routes", "--json"],
+            cwd=directory,
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            command = " ".join(str(arg) for arg in result.args)
+            log.debug(
+                "react-router command failed",
+                package_manager=package_manager,
+                command=command,
+                exit_code=result.returncode,
+                stdout=result.stdout or "",
+                stderr=result.stderr or "",
+            )
+            typer.echo(f"Error running react-router with {package_manager}")
+            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)
+
+    # Automatically lint the generated file with ruff if available
+    lint_generated_file(output_file)
+
+    try:
+        relative_output = output_file.relative_to(Path.cwd())
+    except ValueError:
+        relative_output = output_file
+
+    typer.secho(f"Generated route types: {relative_output}", fg=typer.colors.GREEN)
+
+
+if __name__ == "__main__":
+    app()