index.html not found. Create one under src/fastapi_voyager/web/index.html
\n \n \n \"\"\"\n\n def get_source_code(self, schema_name: str) -> dict:\n \"\"\"Get source code for a schema.\"\"\"\n try:\n components = schema_name.split(\".\")\n if len(components) < 2:\n return {\"error\": \"Invalid schema name format. Expected format: module.ClassName\"}\n\n module_name = \".\".join(components[:-1])\n class_name = components[-1]\n\n mod = __import__(module_name, fromlist=[class_name])\n obj = getattr(mod, class_name)\n source_code = get_source(obj)\n\n return {\"source_code\": source_code}\n except ImportError as e:\n return {\"error\": f\"Module not found: {e}\"}\n except AttributeError as e:\n return {\"error\": f\"Class not found: {e}\"}\n except Exception as e:\n return {\"error\": f\"Internal error: {str(e)}\"}\n\n def get_vscode_link(self, schema_name: str) -> dict:\n \"\"\"Get VSCode link for a schema.\"\"\"\n try:\n components = schema_name.split(\".\")\n if len(components) < 2:\n return {\"error\": \"Invalid schema name format. Expected format: module.ClassName\"}\n\n module_name = \".\".join(components[:-1])\n class_name = components[-1]\n\n mod = __import__(module_name, fromlist=[class_name])\n obj = getattr(mod, class_name)\n link = get_vscode_link(obj, online_repo_url=self.online_repo_url)\n\n return {\"link\": link}\n except ImportError as e:\n return {\"error\": f\"Module not found: {e}\"}\n except AttributeError as e:\n return {\"error\": f\"Class not found: {e}\"}\n except Exception as e:\n return {\"error\": f\"Internal error: {str(e)}\"}\n\n def get_service_worker(self) -> str:\n \"\"\"Get the Service Worker JavaScript content with placeholders replaced.\"\"\"\n sw_file = WEB_DIR / \"sw.js\"\n if sw_file.exists():\n content = sw_file.read_text(encoding=\"utf-8\")\n content = content.replace(VERSION_PLACEHOLDER, __version__)\n content = content.replace(STATIC_PATH_PLACEHOLDER, STATIC_FILES_PATH.lstrip(\"/\"))\n return content\n return \"\"\n\n def get_manifest(self) -> str:\n \"\"\"Get the PWA manifest JSON content with placeholders replaced.\"\"\"\n manifest_file = WEB_DIR / \"icon\" / \"site.webmanifest\"\n if manifest_file.exists():\n content = manifest_file.read_text(encoding=\"utf-8\")\n # VOYAGER_PATH will be replaced with the voyager mount path (e.g., \"/voyager/\")\n # This is set by adapters based on how they are mounted\n content = content.replace(THEME_COLOR_PLACEHOLDER, self._get_theme_color())\n return content\n return \"{}\"\n" }, { "path": "src/fastapi_voyager/adapters/django_ninja_adapter.py", "content": "\"\"\"\nDjango Ninja adapter for fastapi-voyager.\n\nThis module provides the Django Ninja-specific implementation of the voyager server.\nIt creates an ASGI application that can be integrated with Django.\n\"\"\"\nimport json\nimport mimetypes\nfrom typing import Any\n\nfrom fastapi_voyager.adapters.base import VoyagerAdapter\nfrom fastapi_voyager.adapters.common import STATIC_FILES_PATH, VOYAGER_PATH_PLACEHOLDER, WEB_DIR, VoyagerContext\nfrom fastapi_voyager.type import CoreData, SchemaNode, Tag\n\n\nclass DjangoNinjaAdapter(VoyagerAdapter):\n \"\"\"\n Django Ninja-specific implementation of VoyagerAdapter.\n\n Creates an ASGI application with voyager endpoints that can be integrated with Django.\n \"\"\"\n\n def __init__(\n self,\n target_app: Any,\n module_color: dict[str, str] | None = None,\n gzip_minimum_size: int | None = 500,\n module_prefix: str | None = None,\n swagger_url: str | None = None,\n online_repo_url: str | None = None,\n initial_page_policy: str = \"first\",\n ga_id: str | None = None,\n er_diagram: Any = None,\n enable_pydantic_resolve_meta: bool = False,\n server_mode: bool = False,\n ):\n self.ctx = VoyagerContext(\n target_app=target_app,\n module_color=module_color,\n module_prefix=module_prefix,\n swagger_url=swagger_url,\n online_repo_url=online_repo_url,\n initial_page_policy=initial_page_policy,\n ga_id=ga_id,\n er_diagram=er_diagram,\n enable_pydantic_resolve_meta=enable_pydantic_resolve_meta,\n framework_name=\"Django Ninja\",\n )\n self.server_mode = server_mode\n # Note: gzip should be handled by Django's middleware, not here\n\n async def _handle_request(self, scope, receive, send):\n \"\"\"ASGI request handler.\"\"\"\n if scope[\"type\"] != \"http\":\n return\n\n # Parse the request\n method = scope[\"method\"]\n path = scope[\"path\"]\n # Remove /voyager prefix for internal routing (unless in server_mode)\n if not self.server_mode and path.startswith(\"/voyager\"):\n path = path[8:] # Remove '/voyager'\n if path == \"\":\n path = \"/\"\n\n # Handle static files\n if method == \"GET\" and path.startswith(f\"{STATIC_FILES_PATH}/\"):\n await self._handle_static_file(path, send)\n return\n\n # Route the request\n if method == \"GET\" and path == \"/\":\n await self._handle_index(send)\n elif method == \"GET\" and path == \"/sw.js\":\n await self._handle_service_worker(send)\n elif method == \"GET\" and path == \"/manifest.webmanifest\":\n await self._handle_manifest(send)\n elif method == \"GET\" and path == \"/dot\":\n await self._handle_get_dot(send)\n elif method == \"POST\" and path == \"/er-diagram\":\n await self._handle_post_request(receive, send, self._handle_er_diagram)\n elif method == \"POST\" and path == \"/dot-search\":\n await self._handle_post_request(receive, send, self._handle_search_dot)\n elif method == \"POST\" and path == \"/dot\":\n await self._handle_post_request(receive, send, self._handle_filtered_dot)\n elif method == \"POST\" and path == \"/dot-core-data\":\n await self._handle_post_request(receive, send, self._handle_core_data)\n elif method == \"POST\" and path == \"/dot-render-core-data\":\n await self._handle_post_request(receive, send, self._handle_render_core_data)\n elif method == \"POST\" and path == \"/source\":\n await self._handle_post_request(receive, send, self._handle_source)\n elif method == \"POST\" and path == \"/vscode-link\":\n await self._handle_post_request(receive, send, self._handle_vscode_link)\n else:\n await self._send_404(send)\n\n async def _handle_post_request(self, receive, send, handler):\n \"\"\"Helper to handle POST requests with JSON body.\"\"\"\n body = b\"\"\n more_body = True\n\n while more_body:\n message = await receive()\n if message[\"type\"] == \"http.request\":\n body += message.get(\"body\", b\"\")\n more_body = message.get(\"more_body\", False)\n\n try:\n payload = json.loads(body.decode())\n await handler(payload, send)\n except Exception as e:\n await self._send_json({\"error\": str(e)}, send, status_code=400)\n\n async def _handle_static_file(self, path: str, send):\n \"\"\"Handle GET {STATIC_FILES_PATH}/* - serve static files.\"\"\"\n # Remove /fastapi-voyager-static/ prefix\n prefix = f\"{STATIC_FILES_PATH}/\"\n file_path = path[len(prefix):]\n full_path = WEB_DIR / file_path\n\n # Security check: ensure the path is within WEB_DIR\n try:\n full_path = full_path.resolve()\n web_dir_resolved = WEB_DIR.resolve()\n if not str(full_path).startswith(str(web_dir_resolved)):\n await self._send_404(send)\n return\n except Exception:\n await self._send_404(send)\n return\n\n if not full_path.exists() or not full_path.is_file():\n await self._send_404(send)\n return\n\n # Read file content\n try:\n with open(full_path, \"rb\") as f:\n content = f.read()\n\n # Determine content type\n content_type, _ = mimetypes.guess_type(str(full_path))\n if content_type is None:\n content_type = \"application/octet-stream\"\n\n await self._send_response(content_type, content, send)\n except Exception:\n await self._send_404(send)\n\n async def _handle_index(self, send):\n \"\"\"Handle GET / - return the index HTML.\"\"\"\n html = self.ctx.get_index_html()\n await self._send_html(html, send)\n\n async def _handle_service_worker(self, send):\n \"\"\"Handle GET /sw.js - return the Service Worker.\"\"\"\n sw_content = self.ctx.get_service_worker()\n await self._send_response(\n \"application/javascript\",\n sw_content.encode(\"utf-8\"),\n send,\n )\n\n async def _handle_manifest(self, send):\n \"\"\"Handle GET /manifest.webmanifest - return the PWA manifest.\"\"\"\n content = self.ctx.get_manifest()\n content = content.replace(VOYAGER_PATH_PLACEHOLDER, \"./\")\n await self._send_response(\n \"application/manifest+json\",\n content.encode(\"utf-8\"),\n send,\n )\n\n async def _handle_get_dot(self, send):\n \"\"\"Handle GET /dot - return options and initial dot graph.\"\"\"\n data = self.ctx.get_option_param()\n # Convert tags and schemas to dicts for JSON serialization\n response_data = {\n \"tags\": [self._tag_to_dict(t) for t in data[\"tags\"]],\n \"schemas\": [self._schema_to_dict(s) for s in data[\"schemas\"]],\n \"dot\": data[\"dot\"],\n \"enable_brief_mode\": data[\"enable_brief_mode\"],\n \"version\": data[\"version\"],\n \"initial_page_policy\": data[\"initial_page_policy\"],\n \"swagger_url\": data[\"swagger_url\"],\n \"has_er_diagram\": data[\"has_er_diagram\"],\n \"enable_pydantic_resolve_meta\": data[\"enable_pydantic_resolve_meta\"],\n \"framework_name\": data[\"framework_name\"],\n }\n await self._send_json(response_data, send)\n\n async def _handle_er_diagram(self, payload, send):\n \"\"\"Handle POST /er-diagram.\"\"\"\n data = self.ctx.get_er_diagram_data(payload)\n await self._send_json(data, send)\n\n async def _handle_search_dot(self, payload, send):\n \"\"\"Handle POST /dot-search.\"\"\"\n tags = self.ctx.get_search_dot(payload)\n response_data = {\"tags\": [self._tag_to_dict(t) for t in tags]}\n await self._send_json(response_data, send)\n\n async def _handle_filtered_dot(self, payload, send):\n \"\"\"Handle POST /dot.\"\"\"\n dot = self.ctx.get_filtered_dot(payload)\n await self._send_text(dot, send)\n\n async def _handle_core_data(self, payload, send):\n \"\"\"Handle POST /dot-core-data.\"\"\"\n core_data = self.ctx.get_core_data(payload)\n await self._send_json(core_data.model_dump(), send)\n\n async def _handle_render_core_data(self, payload, send):\n \"\"\"Handle POST /dot-render-core-data.\"\"\"\n core_data = CoreData(**payload)\n dot = self.ctx.render_dot_from_core_data(core_data)\n await self._send_text(dot, send)\n\n async def _handle_source(self, payload, send):\n \"\"\"Handle POST /source.\"\"\"\n result = self.ctx.get_source_code(payload.get(\"schema_name\", \"\"))\n status_code = 200 if \"error\" not in result else 400\n if \"error\" in result and \"not found\" in result[\"error\"]:\n status_code = 404\n await self._send_json(result, send, status_code=status_code)\n\n async def _handle_vscode_link(self, payload, send):\n \"\"\"Handle POST /vscode-link.\"\"\"\n result = self.ctx.get_vscode_link(payload.get(\"schema_name\", \"\"))\n status_code = 200 if \"error\" not in result else 400\n if \"error\" in result and \"not found\" in result[\"error\"]:\n status_code = 404\n await self._send_json(result, send, status_code=status_code)\n\n async def _send_html(self, html: str, send):\n \"\"\"Send HTML response.\"\"\"\n await self._send_response(\n \"text/html; charset=utf-8\",\n html.encode(\"utf-8\"),\n send,\n status_code=200,\n )\n\n async def _send_json(self, data: dict, send, status_code: int = 200):\n \"\"\"Send JSON response.\"\"\"\n body = json.dumps(data).encode(\"utf-8\")\n await self._send_response(\"application/json\", body, send, status_code=status_code)\n\n async def _send_text(self, text: str, send):\n \"\"\"Send plain text response.\"\"\"\n await self._send_response(\"text/plain; charset=utf-8\", text.encode(\"utf-8\"), send)\n\n async def _send_404(self, send):\n \"\"\"Send 404 response.\"\"\"\n await self._send_response(\"text/plain\", b\"Not Found\", send, status_code=404)\n\n async def _send_response(\n self, content_type: str, body: bytes, send, status_code: int = 200\n ):\n \"\"\"Send ASGI response.\"\"\"\n await send(\n {\n \"type\": \"http.response.start\",\n \"status\": status_code,\n \"headers\": [\n [b\"content-type\", content_type.encode()],\n [b\"content-length\", str(len(body)).encode()],\n ],\n }\n )\n await send({\"type\": \"http.response.body\", \"body\": body})\n\n def _tag_to_dict(self, tag: Tag) -> dict:\n \"\"\"Convert Tag object to dict.\"\"\"\n return {\n \"id\": tag.id,\n \"name\": tag.name,\n \"routes\": [\n {\n \"id\": r.id,\n \"name\": r.name,\n \"module\": r.module,\n \"unique_id\": r.unique_id,\n \"response_schema\": r.response_schema,\n \"is_primitive\": r.is_primitive,\n }\n for r in tag.routes\n ],\n }\n\n def _schema_to_dict(self, schema: SchemaNode) -> dict:\n \"\"\"Convert SchemaNode to dict.\"\"\"\n return {\n \"id\": schema.id,\n \"module\": schema.module,\n \"name\": schema.name,\n \"fields\": [\n {\n \"name\": f.name,\n \"type_name\": f.type_name,\n \"is_object\": f.is_object,\n \"is_exclude\": f.is_exclude,\n }\n for f in schema.fields\n ],\n }\n\n def create_app(self):\n \"\"\"Create and return an ASGI application.\"\"\"\n\n async def asgi_app(scope, receive, send):\n # In server_mode, handle all paths; otherwise only handle /voyager/*\n if scope[\"type\"] == \"http\":\n if self.server_mode or scope[\"path\"].startswith(\"/voyager\"):\n await self._handle_request(scope, receive, send)\n else:\n # Return 404 for non-voyager paths\n # (Django should handle these before they reach here)\n await self._send_404(send)\n else:\n await self._send_404(send)\n\n return asgi_app\n" }, { "path": "src/fastapi_voyager/adapters/fastapi_adapter.py", "content": "\"\"\"\nFastAPI adapter for fastapi-voyager.\n\nThis module provides the FastAPI-specific implementation of the voyager server.\n\"\"\"\nfrom typing import Any, Literal\n\nfrom pydantic import BaseModel\n\nfrom fastapi_voyager.adapters.base import VoyagerAdapter\nfrom fastapi_voyager.adapters.common import STATIC_FILES_PATH, VOYAGER_PATH_PLACEHOLDER, VoyagerContext\nfrom fastapi_voyager.type import CoreData, SchemaNode, Tag\n\n\nclass OptionParam(BaseModel):\n tags: list[Tag]\n schemas: list[SchemaNode]\n dot: str\n enable_brief_mode: bool\n version: str\n initial_page_policy: Literal[\"first\", \"full\", \"empty\"]\n swagger_url: str | None = None\n has_er_diagram: bool = False\n enable_pydantic_resolve_meta: bool = False\n framework_name: str = \"API\"\n\n\nclass Payload(BaseModel):\n tags: list[str] | None = None\n schema_name: str | None = None\n schema_field: str | None = None\n route_name: str | None = None\n show_fields: str = \"object\"\n brief: bool = False\n hide_primitive_route: bool = False\n show_module: bool = True\n show_pydantic_resolve_meta: bool = False\n\n\nclass SearchResultOptionParam(BaseModel):\n tags: list[Tag]\n\n\nclass SchemaSearchPayload(BaseModel):\n schema_name: str | None = None\n schema_field: str | None = None\n show_fields: str = \"object\"\n brief: bool = False\n hide_primitive_route: bool = False\n show_module: bool = True\n show_pydantic_resolve_meta: bool = False\n\n\nclass ErDiagramPayload(BaseModel):\n show_fields: str = \"object\"\n show_module: bool = True\n edge_minlen: int = 3\n show_methods: bool = True\n\n\nclass SourcePayload(BaseModel):\n schema_name: str\n\n\nclass FastAPIAdapter(VoyagerAdapter):\n \"\"\"\n FastAPI-specific implementation of VoyagerAdapter.\n\n Creates a FastAPI application with voyager endpoints.\n \"\"\"\n\n def __init__(\n self,\n target_app: Any,\n module_color: dict[str, str] | None = None,\n gzip_minimum_size: int | None = 500,\n module_prefix: str | None = None,\n swagger_url: str | None = None,\n online_repo_url: str | None = None,\n initial_page_policy: str = \"first\",\n ga_id: str | None = None,\n er_diagram: Any = None,\n enable_pydantic_resolve_meta: bool = False,\n server_mode: bool = False,\n ):\n self.ctx = VoyagerContext(\n target_app=target_app,\n module_color=module_color,\n module_prefix=module_prefix,\n swagger_url=swagger_url,\n online_repo_url=online_repo_url,\n initial_page_policy=initial_page_policy,\n ga_id=ga_id,\n er_diagram=er_diagram,\n enable_pydantic_resolve_meta=enable_pydantic_resolve_meta,\n framework_name=\"FastAPI\",\n )\n self.gzip_minimum_size = gzip_minimum_size\n # Note: server_mode is accepted for API consistency but not used\n # since FastAPI apps are always standalone with routes at /\n\n def create_app(self) -> Any:\n \"\"\"Create and return a FastAPI application with voyager endpoints.\"\"\"\n # Lazy import FastAPI to avoid import errors when framework is not installed\n from fastapi import APIRouter, FastAPI\n from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse\n from fastapi.staticfiles import StaticFiles\n from starlette.middleware.gzip import GZipMiddleware\n\n router = APIRouter(tags=[\"fastapi-voyager\"])\n\n @router.post(\"/er-diagram\")\n def get_er_diagram(payload: ErDiagramPayload):\n return self.ctx.get_er_diagram_data(payload.model_dump())\n\n @router.get(\"/dot\", response_model=OptionParam)\n def get_dot() -> OptionParam:\n data = self.ctx.get_option_param()\n return OptionParam(**data)\n\n @router.post(\"/dot-search\", response_model=SearchResultOptionParam)\n def get_search_dot(payload: SchemaSearchPayload) -> SearchResultOptionParam:\n tags = self.ctx.get_search_dot(payload.model_dump())\n return SearchResultOptionParam(tags=tags)\n\n @router.post(\"/dot\", response_class=PlainTextResponse)\n def get_filtered_dot(payload: Payload) -> str:\n return self.ctx.get_filtered_dot(payload.model_dump())\n\n @router.post(\"/dot-core-data\", response_model=CoreData)\n def get_filtered_dot_core_data(payload: Payload) -> CoreData:\n return self.ctx.get_core_data(payload.model_dump())\n\n @router.post(\"/dot-render-core-data\", response_class=PlainTextResponse)\n def render_dot_from_core_data(core_data: CoreData) -> str:\n return self.ctx.render_dot_from_core_data(core_data)\n\n @router.get(\"/\", response_class=HTMLResponse)\n def index() -> str:\n return self.ctx.get_index_html()\n\n @router.get(\"/sw.js\")\n def get_service_worker():\n \"\"\"Serve the Service Worker with correct content type.\"\"\"\n from fastapi.responses import PlainTextResponse\n return PlainTextResponse(\n content=self.ctx.get_service_worker(),\n media_type=\"application/javascript\"\n )\n\n @router.get(\"/manifest.webmanifest\")\n def get_manifest():\n \"\"\"Serve the PWA manifest with correct content type.\"\"\"\n from fastapi.responses import PlainTextResponse\n content = self.ctx.get_manifest()\n # Replace VOYAGER_PATH with root-relative path (works for any mount point)\n content = content.replace(VOYAGER_PATH_PLACEHOLDER, \"./\")\n return PlainTextResponse(\n content=content,\n media_type=\"application/manifest+json\"\n )\n\n @router.post(\"/source\")\n def get_object_by_module_name(payload: SourcePayload) -> JSONResponse:\n result = self.ctx.get_source_code(payload.schema_name)\n status_code = 200 if \"error\" not in result else 400\n if \"error\" in result and \"not found\" in result[\"error\"]:\n status_code = 404\n return JSONResponse(content=result, status_code=status_code)\n\n @router.post(\"/vscode-link\")\n def get_vscode_link_by_module_name(payload: SourcePayload) -> JSONResponse:\n result = self.ctx.get_vscode_link(payload.schema_name)\n status_code = 200 if \"error\" not in result else 400\n if \"error\" in result and \"not found\" in result[\"error\"]:\n status_code = 404\n return JSONResponse(content=result, status_code=status_code)\n\n app = FastAPI(title=\"fastapi-voyager demo server\")\n\n if self.gzip_minimum_size is not None and self.gzip_minimum_size >= 0:\n app.add_middleware(GZipMiddleware, minimum_size=self.gzip_minimum_size)\n\n from fastapi_voyager.adapters.common import WEB_DIR\n\n app.mount(STATIC_FILES_PATH, StaticFiles(directory=str(WEB_DIR)), name=\"static\")\n app.include_router(router)\n\n return app\n" }, { "path": "src/fastapi_voyager/adapters/litestar_adapter.py", "content": "\"\"\"\nLitestar adapter for fastapi-voyager.\n\nThis module provides the Litestar-specific implementation of the voyager server.\n\"\"\"\nfrom typing import Any\n\nfrom fastapi_voyager.adapters.base import VoyagerAdapter\nfrom fastapi_voyager.adapters.common import STATIC_FILES_PATH, VOYAGER_PATH_PLACEHOLDER, WEB_DIR, VoyagerContext\nfrom fastapi_voyager.type import CoreData, SchemaNode, Tag\n\n\nclass LitestarAdapter(VoyagerAdapter):\n \"\"\"\n Litestar-specific implementation of VoyagerAdapter.\n\n Creates a Litestar application with voyager endpoints.\n \"\"\"\n\n def __init__(\n self,\n target_app: Any,\n module_color: dict[str, str] | None = None,\n gzip_minimum_size: int | None = 500,\n module_prefix: str | None = None,\n swagger_url: str | None = None,\n online_repo_url: str | None = None,\n initial_page_policy: str = \"first\",\n ga_id: str | None = None,\n er_diagram: Any = None,\n enable_pydantic_resolve_meta: bool = False,\n server_mode: bool = False,\n ):\n self.ctx = VoyagerContext(\n target_app=target_app,\n module_color=module_color,\n module_prefix=module_prefix,\n swagger_url=swagger_url,\n online_repo_url=online_repo_url,\n initial_page_policy=initial_page_policy,\n ga_id=ga_id,\n er_diagram=er_diagram,\n enable_pydantic_resolve_meta=enable_pydantic_resolve_meta,\n framework_name=\"Litestar\",\n )\n self.gzip_minimum_size = gzip_minimum_size\n # Note: server_mode is accepted for API consistency but not used\n # since Litestar apps are always standalone with routes at /\n\n def create_app(self) -> Any:\n \"\"\"Create and return a Litestar application with voyager endpoints.\"\"\"\n # Lazy import Litestar to avoid import errors when framework is not installed\n from litestar import Litestar, MediaType, Request, Response, get, post\n from litestar.static_files import create_static_files_router\n\n @post(\"/er-diagram\")\n async def get_er_diagram(request: Request) -> dict:\n payload = await request.json()\n return self.ctx.get_er_diagram_data(payload)\n\n @get(\"/dot\")\n async def get_dot(request: Request) -> dict:\n data = self.ctx.get_option_param()\n # Convert tags and schemas to dicts for JSON serialization\n return {\n \"tags\": [self._tag_to_dict(t) for t in data[\"tags\"]],\n \"schemas\": [self._schema_to_dict(s) for s in data[\"schemas\"]],\n \"dot\": data[\"dot\"],\n \"enable_brief_mode\": data[\"enable_brief_mode\"],\n \"version\": data[\"version\"],\n \"initial_page_policy\": data[\"initial_page_policy\"],\n \"swagger_url\": data[\"swagger_url\"],\n \"has_er_diagram\": data[\"has_er_diagram\"],\n \"enable_pydantic_resolve_meta\": data[\"enable_pydantic_resolve_meta\"],\n \"framework_name\": data[\"framework_name\"],\n }\n\n @post(\"/dot-search\")\n async def get_search_dot(request: Request) -> dict:\n payload = await request.json()\n tags = self.ctx.get_search_dot(payload)\n return {\"tags\": [self._tag_to_dict(t) for t in tags]}\n\n @post(\"/dot\")\n async def get_filtered_dot(request: Request) -> str:\n payload = await request.json()\n return self.ctx.get_filtered_dot(payload)\n\n @post(\"/dot-core-data\")\n async def get_filtered_dot_core_data(request: Request) -> CoreData:\n payload = await request.json()\n return self.ctx.get_core_data(payload)\n\n @post(\"/dot-render-core-data\")\n async def render_dot_from_core_data(request: Request) -> str:\n payload = await request.json()\n core_data = CoreData(**payload)\n return self.ctx.render_dot_from_core_data(core_data)\n\n @get(\"/\", media_type=MediaType.HTML)\n async def index() -> str:\n return self.ctx.get_index_html()\n\n @get(\"/sw.js\", media_type=\"application/javascript\")\n async def get_service_worker() -> str:\n \"\"\"Serve the Service Worker.\"\"\"\n return self.ctx.get_service_worker()\n\n @get(\"/manifest.webmanifest\", media_type=\"application/manifest+json\")\n async def get_manifest() -> str:\n \"\"\"Serve the PWA manifest.\"\"\"\n content = self.ctx.get_manifest()\n return content.replace(VOYAGER_PATH_PLACEHOLDER, \"./\")\n\n @post(\"/source\")\n async def get_object_by_module_name(request: Request) -> dict:\n payload = await request.json()\n result = self.ctx.get_source_code(payload.get(\"schema_name\", \"\"))\n status_code = 200 if \"error\" not in result else 400\n if \"error\" in result and \"not found\" in result[\"error\"]:\n status_code = 404\n return Response(\n content=result,\n status_code=status_code,\n media_type=MediaType.JSON,\n )\n\n @post(\"/vscode-link\")\n async def get_vscode_link_by_module_name(request: Request) -> dict:\n payload = await request.json()\n result = self.ctx.get_vscode_link(payload.get(\"schema_name\", \"\"))\n status_code = 200 if \"error\" not in result else 400\n if \"error\" in result and \"not found\" in result[\"error\"]:\n status_code = 404\n return Response(\n content=result,\n status_code=status_code,\n media_type=MediaType.JSON,\n )\n\n # Create static files router using the new API (replaces deprecated StaticFilesConfig)\n static_files_router = create_static_files_router(\n path=STATIC_FILES_PATH,\n directories=[str(WEB_DIR)],\n )\n\n # Create Litestar app\n app = Litestar(\n route_handlers=[\n get_er_diagram,\n get_dot,\n get_search_dot,\n get_filtered_dot,\n get_filtered_dot_core_data,\n render_dot_from_core_data,\n index,\n get_service_worker,\n get_manifest,\n get_object_by_module_name,\n get_vscode_link_by_module_name,\n static_files_router,\n ],\n )\n\n return app\n\n def _tag_to_dict(self, tag: Tag) -> dict:\n \"\"\"Convert Tag object to dict.\"\"\"\n return {\n \"id\": tag.id,\n \"name\": tag.name,\n \"routes\": [\n {\n \"id\": r.id,\n \"name\": r.name,\n \"module\": r.module,\n \"unique_id\": r.unique_id,\n \"response_schema\": r.response_schema,\n \"is_primitive\": r.is_primitive,\n }\n for r in tag.routes\n ],\n }\n\n def _schema_to_dict(self, schema: SchemaNode) -> dict:\n \"\"\"Convert SchemaNode to dict.\"\"\"\n return {\n \"id\": schema.id,\n \"module\": schema.module,\n \"name\": schema.name,\n \"fields\": [\n {\n \"name\": f.name,\n \"type_name\": f.type_name,\n \"is_object\": f.is_object,\n \"is_exclude\": f.is_exclude,\n }\n for f in schema.fields\n ],\n }\n" }, { "path": "src/fastapi_voyager/cli.py", "content": "\"\"\"Command line interface for fastapi-voyager.\"\"\"\nimport argparse\nimport importlib\nimport importlib.util\nimport logging\nimport os\nimport sys\nfrom typing import Any\n\nfrom fastapi_voyager import server as viz_server\nfrom fastapi_voyager.version import __version__\nfrom fastapi_voyager.voyager import Voyager\n\nlogger = logging.getLogger(__name__)\n\n# Framework type constants\nSUPPORTED_FRAMEWORKS = [\"fastapi\", \"litestar\", \"django-ninja\"]\n\n\ndef load_app_from_file(module_path: str, app_name: str = \"app\", framework: str | None = None) -> Any:\n \"\"\"Load web framework app from a Python module file.\"\"\"\n try:\n # Convert relative path to absolute path\n if not os.path.isabs(module_path):\n module_path = os.path.abspath(module_path)\n\n # Load the module\n spec = importlib.util.spec_from_file_location(\"app_module\", module_path)\n if spec is None or spec.loader is None:\n logger.error(f\"Could not load module from {module_path}\")\n return None\n\n module = importlib.util.module_from_spec(spec)\n sys.modules[\"app_module\"] = module\n spec.loader.exec_module(module)\n\n # Get the app instance\n if not hasattr(module, app_name):\n logger.error(f\"No attribute '{app_name}' found in the module\")\n return None\n\n app = getattr(module, app_name)\n\n # Verify app type if framework is specified\n if framework is not None:\n if not _validate_app_framework(app, framework):\n logger.error(f\"'{app_name}' is not a {framework} instance\")\n return None\n\n return app\n\n except Exception as e:\n logger.error(f\"Error loading app: {e}\")\n return None\n\n\ndef load_app_from_module(module_name: str, app_name: str = \"app\", framework: str | None = None) -> Any:\n \"\"\"Load web framework app from a Python module name.\"\"\"\n try:\n # Temporarily add the current working directory to sys.path\n current_dir = os.getcwd()\n if current_dir not in sys.path:\n sys.path.insert(0, current_dir)\n path_added = True\n else:\n path_added = False\n\n try:\n # Import the module by name\n module = importlib.import_module(module_name)\n\n # Get the app instance\n if not hasattr(module, app_name):\n logger.error(f\"No attribute '{app_name}' found in module '{module_name}'\")\n return None\n\n app = getattr(module, app_name)\n\n # Verify app type if framework is specified\n if framework is not None:\n if not _validate_app_framework(app, framework):\n logger.error(f\"'{app_name}' is not a {framework} instance\")\n return None\n\n return app\n finally:\n # Cleanup: if we added the path, remove it\n if path_added and current_dir in sys.path:\n sys.path.remove(current_dir)\n\n except ImportError as e:\n logger.error(f\"Could not import module '{module_name}': {e}\")\n return None\n except Exception as e:\n logger.error(f\"Error loading app from module '{module_name}': {e}\")\n return None\n\n\ndef _validate_app_framework(app: Any, framework: str) -> bool:\n \"\"\"Validate that the app matches the expected framework type.\"\"\"\n try:\n if framework == \"fastapi\":\n from fastapi import FastAPI\n return isinstance(app, FastAPI)\n elif framework == \"litestar\":\n from litestar import Litestar\n return isinstance(app, Litestar)\n elif framework == \"django-ninja\":\n from ninja import NinjaAPI\n return isinstance(app, NinjaAPI)\n return False\n except ImportError as e:\n logger.error(\n f\"The {framework} package is not installed. \"\n f\"Install it with: uv add fastapi-voyager[{framework}]\"\n )\n logger.debug(f\"Import error details: {e}\")\n return False\n\n\ndef generate_visualization(\n app: Any,\n output_file: str = \"router_viz.dot\", tags: list[str] | None = None,\n schema: str | None = None,\n show_fields: bool = False,\n module_color: dict[str, str] | None = None,\n route_name: str | None = None,\n):\n\n \"\"\"Generate DOT file for API router visualization.\"\"\"\n analytics = Voyager(\n include_tags=tags,\n schema=schema,\n show_fields=show_fields,\n module_color=module_color,\n route_name=route_name,\n )\n\n analytics.analysis(app)\n\n dot_content = analytics.render_dot()\n \n # Optionally write to file\n with open(output_file, 'w', encoding='utf-8') as f:\n f.write(dot_content)\n logger.info(f\"DOT file generated: {output_file}\")\n logger.info(\"To render the graph, use: dot -Tpng router_viz.dot -o router_viz.png\")\n logger.info(\"Or view online: https://dreampuf.github.io/GraphvizOnline/\")\n\n\ndef main():\n \"\"\"Main CLI entry point.\"\"\"\n parser = argparse.ArgumentParser(\n description=\"Visualize web application's routing tree and dependencies (supports FastAPI, Litestar, Django-Ninja)\",\n formatter_class=argparse.RawDescriptionHelpFormatter,\n epilog=\"\"\"\nExamples:\n voyager app.py --web fastapi # Load 'app' from app.py (FastAPI)\n voyager app.py --web litestar # Load 'app' from app.py (Litestar)\n voyager -m tests.demo --web django-ninja # Load 'app' from demo module (Django-Ninja)\n voyager -m tests.demo --app=api --web fastapi # Load 'api' from tests.demo\n voyager -m tests.demo --web fastapi --schema=NodeA # filter nodes by schema name\n voyager -m tests.demo --web fastapi --tags=page restful # filter routes by tags\n voyager -m tests.demo --web fastapi --module_color=tests.demo:red --module_color=tests.service:yellow\n voyager -m tests.demo --web fastapi -o my_graph.dot # Output to my_graph.dot\n voyager -m tests.demo --web fastapi --server # start a local server to preview\n voyager -m tests.demo --web fastapi --server --port=8001 # start a local server to preview\n\"\"\"\n )\n\n # Create mutually exclusive group for module loading options\n group = parser.add_mutually_exclusive_group(required=False)\n group.add_argument(\n \"module\",\n nargs=\"?\",\n help=\"Python file containing the web application\"\n )\n group.add_argument(\n \"-m\", \"--module\",\n dest=\"module_name\",\n help=\"Python module name containing the web application (like python -m)\"\n )\n\n parser.add_argument(\n \"--web\",\n choices=SUPPORTED_FRAMEWORKS,\n help=\"Web framework type (required when using --server): fastapi, litestar, django-ninja\"\n )\n\n parser.add_argument(\n \"--app\", \"-a\",\n default=\"app\",\n help=\"Name of the app variable (default: app)\"\n )\n \n parser.add_argument(\n \"--output\", \"-o\",\n default=\"router_viz.dot\",\n help=\"Output DOT file name (default: router_viz.dot)\"\n )\n parser.add_argument(\n \"--server\",\n action=\"store_true\",\n help=\"Start a local server to preview the generated DOT graph\"\n )\n parser.add_argument(\n \"--port\",\n type=int,\n default=8000,\n help=\"Port for the preview server when --server is used (default: 8000)\"\n )\n parser.add_argument(\n \"--host\",\n type=str,\n default=\"127.0.0.1\",\n help=\"Host/IP for the preview server when --server is used (default: 127.0.0.1). Use 0.0.0.0 to listen on all interfaces.\"\n )\n parser.add_argument(\n \"--module_prefix\",\n type=str,\n default=None,\n help=\"Prefix routes with module name when rendering brief view (only valid with --server)\"\n )\n \n parser.add_argument(\n \"--version\", \"-v\",\n action=\"version\",\n version=f\"fastapi-voyager {__version__}\"\n )\n parser.add_argument(\n \"--tags\",\n nargs=\"+\",\n help=\"Only include routes whose first tag is in the provided list\"\n )\n parser.add_argument(\n \"--module_color\",\n action=\"append\",\n metavar=\"KEY:VALUE\",\n help=\"Module color mapping as key1:value1 key2:value2 (module name to Graphviz color)\"\n )\n # removed service_prefixes option\n parser.add_argument(\n \"--schema\",\n default=None,\n help=\"Filter schemas by name\"\n )\n parser.add_argument(\n \"--show_fields\",\n choices=[\"single\", \"object\", \"all\"],\n default=\"object\",\n help=\"Field display mode: single (no fields), object (only object-like fields), all (all fields). Default: object\"\n )\n parser.add_argument(\n \"--route_name\",\n type=str,\n default=None,\n help=\"Filter by route id (format:Count: {{ store.state.item.count }}
\n \n\n {{ shortName(sourceEntity) }} → {{ shortName(targetEntity) }}\n
\n\n {{ label }}\n
\n\n {{ loaderFullname }}\n
\n \n Open in VSCode\n \n{{ code }}{{ schemaName }}
\n \n Open in VSCode\n \n| Field | \nType | \nDescription | \nInherited | \n
|---|---|---|---|
| {{ f.name }} | \n{{ f.type_name }} | \n{{ f.desc }} | \n{{ f.from_base ? '✔︎' : '' }} | \n
| No fields | \n
{{ code }}\n {{ shortName(sourceEntity) }} → {{ shortName(targetEntity) }}\n
\n\n {{ label }}\n
\n\n {{ loaderFullname }}\n
\n{{ code }}{{ code }}{{ schemaName }}
\n \n Open in VSCode\n \n{{ code }}