generate-fastapi-typed-routes 0.1.1__tar.gz

generate_fastapi_typed_routes-0.1.1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.3
+Name: generate-fastapi-typed-routes
+Version: 0.1.1
+Summary: Generate typed url_path_for functions for FastAPI applications.
+Keywords: fastapi,typing,routes,codegen
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+Requires-Dist: click>=8.3.1
+Requires-Dist: fastapi>=0.128.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: structlog-config>=0.6.0
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/iloveitaly/generate-fastapi-typed-routes
+Description-Content-Type: text/markdown
+
+# Type-Safe Route URL Generator for FastAPI
+
+Stop guessing route names. This tool analyzes your FastAPI application and generates a typed wrapper for `url_path_for`, giving you instant autocompletion and catching typos before they hit production.
+
+## Installation
+
+```bash
+uvx generate-fastapi-typed-routes@latest
+```
+
+## Usage
+
+Point the tool at your FastAPI app and tell it where to save the generated code:
+
+```bash
+uvx generate-fastapi-typed-routes@latest --app-module myapp.main:app --output myapp/routes.py
+```
+
+Now, instead of using the raw `app.url_path_for`, import your generated function:
+
+```python
+from myapp.routes import app_url_path_for
+
+# Complete with IDE autocompletion and type checking!
+url = app_url_path_for("get_user_profile", user_id=123)
+```
+
+### CLI Arguments
+
+*   `--app-module`: The import path to your FastAPI app instance (e.g., `src.main:app`). You can pass this multiple times to generate helpers for multiple apps in one file.
+*   `--output`: The file path where the generated Python code will be saved.
+*   `--prefix`: (Optional) Custom prefix for the generated function. Defaults to the app variable name (e.g., `app` becomes `app_url_path_for`). Use this if you have multiple apps to keep things distinct.
+
+## Features
+
+*   **Zero Runtime Overhead:** The generated code is just type hints and a simple wrapper.
+*   **IDE Autocompletion:** Never type a route name manually again. Your editor will list every available route name defined in your app.
+*   **Refactoring Safe:** Change a route name in your app, and your type checker (mypy, pyright) will flag every place usage that needs updating.
+*   **Multi-App Support:** Easily manage routes for projects with multiple FastAPI instances.
+
+# [MIT License](LICENSE.md)

generate_fastapi_typed_routes-0.1.1/README.md

@@ -0,0 +1,41 @@
+# Type-Safe Route URL Generator for FastAPI
+
+Stop guessing route names. This tool analyzes your FastAPI application and generates a typed wrapper for `url_path_for`, giving you instant autocompletion and catching typos before they hit production.
+
+## Installation
+
+```bash
+uvx generate-fastapi-typed-routes@latest
+```
+
+## Usage
+
+Point the tool at your FastAPI app and tell it where to save the generated code:
+
+```bash
+uvx generate-fastapi-typed-routes@latest --app-module myapp.main:app --output myapp/routes.py
+```
+
+Now, instead of using the raw `app.url_path_for`, import your generated function:
+
+```python
+from myapp.routes import app_url_path_for
+
+# Complete with IDE autocompletion and type checking!
+url = app_url_path_for("get_user_profile", user_id=123)
+```
+
+### CLI Arguments
+
+*   `--app-module`: The import path to your FastAPI app instance (e.g., `src.main:app`). You can pass this multiple times to generate helpers for multiple apps in one file.
+*   `--output`: The file path where the generated Python code will be saved.
+*   `--prefix`: (Optional) Custom prefix for the generated function. Defaults to the app variable name (e.g., `app` becomes `app_url_path_for`). Use this if you have multiple apps to keep things distinct.
+
+## Features
+
+*   **Zero Runtime Overhead:** The generated code is just type hints and a simple wrapper.
+*   **IDE Autocompletion:** Never type a route name manually again. Your editor will list every available route name defined in your app.
+*   **Refactoring Safe:** Change a route name in your app, and your type checker (mypy, pyright) will flag every place usage that needs updating.
+*   **Multi-App Support:** Easily manage routes for projects with multiple FastAPI instances.
+
+# [MIT License](LICENSE.md)

generate_fastapi_typed_routes-0.1.1/generate_fastapi_typed_routes/__init__.py

@@ -0,0 +1,167 @@
+from pathlib import Path
+from types import ModuleType
+
+import click
+from fastapi import FastAPI
+from fastapi.routing import APIRoute
+from jinja2 import Template
+from pydantic import BaseModel
+from structlog_config import configure_logger
+
+log = configure_logger()
+
+MODULE_TEMPLATE = '''\
+"""Auto-generated typed url_path_for functions for FastAPI apps."""
+
+from typing import overload, Literal
+{% for app_info in apps %}
+from {{ app_info.import_path }} import {{ app_info.name }}
+{% endfor %}
+
+{% for app_info in apps %}
+# Routes for {{ app_info.name }}
+{% for route in app_info.routes %}
+@overload
+def {{ app_info.prefix }}_url_path_for(name: Literal["{{ route.name }}"], **path_params) -> str: ...
+{% endfor %}
+
+def {{ app_info.prefix }}_url_path_for(name: str, **path_params) -> str:
+    """Type-safe wrapper around {{ app_info.name }}.url_path_for() with overloads for all routes."""
+    return {{ app_info.name }}.url_path_for(name, **path_params)
+
+{% endfor %}
+'''
+
+
+class RouteInfo(BaseModel):
+    name: str
+    path: str
+
+
+class AppInfo(BaseModel):
+    import_path: str
+    name: str
+    prefix: str
+    routes: list[RouteInfo]
+
+
+def extract_routes(app: FastAPI) -> list[RouteInfo]:
+    """Extract route information from a FastAPI app."""
+    routes: list[RouteInfo] = []
+
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+
+        if not route.name:
+            continue
+
+        routes.append(
+            RouteInfo(
+                name=route.name,
+                path=route.path,
+            )
+        )
+
+    # Sort for consistent output
+    routes.sort(key=lambda x: x.name)
+
+    log.info("extracted_routes", count=len(routes))
+    return routes
+
+
+def load_app(app_module: str, prefix: str | None) -> AppInfo:
+    """Load a FastAPI app and extract its information."""
+    module_path, app_name = app_module.split(":")
+    module: ModuleType = __import__(module_path, fromlist=[app_name])
+    app = getattr(module, app_name)
+
+    if not isinstance(app, FastAPI):
+        raise click.ClickException(f"{app_module} is not a FastAPI app")
+
+    log.info("app_loaded", module=module_path, app=app_name)
+
+    routes = extract_routes(app)
+
+    # Determine prefix - default to app_name if not provided
+    if prefix is None:
+        prefix = app_name
+        log.info("using_default_prefix", prefix=prefix)
+
+    return AppInfo(
+        import_path=module_path,
+        name=app_name,
+        prefix=prefix,
+        routes=routes,
+    )
+
+
+def generate_typed_module(apps_info: list[AppInfo], output_path: Path) -> None:
+    """Generate Python module with typed url_path_for functions."""
+
+    log.info(
+        "generating_module", output_path=str(output_path), app_count=len(apps_info)
+    )
+
+    # Render the template
+    template = Template(MODULE_TEMPLATE)
+    output = template.render(apps=apps_info)
+
+    # Create parent directories if needed
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    output_path.write_text(output)
+
+    total_routes = sum(len(app.routes) for app in apps_info)
+    log.info(
+        "module_generated", output_path=str(output_path), total_routes=total_routes
+    )
+
+
+@click.command()
+@click.option(
+    "--app-module",
+    multiple=True,
+    required=True,
+    help="Python module path to FastAPI app (e.g., 'myapp.main:api_app'). Can be specified multiple times.",
+)
+@click.option(
+    "--output",
+    type=click.Path(path_type=Path),
+    required=True,
+    help="Output path for the generated module (required)",
+)
+@click.option(
+    "--prefix",
+    multiple=True,
+    default=None,
+    help="Prefix for the generated function (default: uses app variable name). Should match order of --app-module.",
+)
+def main(
+    app_module: tuple[str, ...], output: Path, prefix: tuple[str, ...] | None
+) -> None:
+    """Generate typed url_path_for functions for FastAPI applications."""
+
+    log.info("starting_generation", app_modules=app_module, output=str(output))
+
+    try:
+        # Parse prefixes - if provided, must match number of apps
+        prefixes = list(prefix) if prefix else [None] * len(app_module)
+
+        if len(prefixes) != len(app_module):
+            raise click.ClickException(
+                f"Number of prefixes ({len(prefixes)}) must match number of app modules ({len(app_module)})"
+            )
+
+        # Load all apps
+        apps_info = []
+        for app_mod, app_prefix in zip(app_module, prefixes):
+            app_info = load_app(app_mod, app_prefix)
+            apps_info.append(app_info)
+
+        # Generate module
+        generate_typed_module(apps_info, output)
+
+    except Exception as e:
+        log.error("generation_failed", error=str(e), exc_info=True)
+        raise click.ClickException(str(e))

generate_fastapi_typed_routes-0.1.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "generate-fastapi-typed-routes"
+version = "0.1.1"
+description = "Generate typed url_path_for functions for FastAPI applications."
+keywords = ["fastapi", "typing", "routes", "codegen"]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.3.1",
+    "fastapi>=0.128.0",
+    "jinja2>=3.1.6",
+    "pydantic>=2.12.5",
+    "structlog-config>=0.6.0",
+]
+authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
+urls = { "Repository" = "https://github.com/iloveitaly/generate-fastapi-typed-routes" }
+
+# additional packaging information: https://packaging.python.org/en/latest/specifications/core-metadata/#license
+[project.scripts]
+generate-fastapi-typed-routes = "generate_fastapi_typed_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/"]