fastapi-voyager 0.15.5__py3-none-any.whl → 0.16.0a1__py3-none-any.whl

fastapi_voyager/__init__.py

@@ -1,8 +1,8 @@
 """fastapi_voyager
 
-Utilities to introspect a FastAPI application and visualize its routing tree.
+Utilities to introspect web applications and visualize their routing tree.
 """
 from .server import create_voyager
 from .version import __version__  # noqa: F401
 
-__all__ = ["__version__", "create_voyager"]
+__all__ = [ "__version__", "create_voyager" ]

fastapi_voyager/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""
+Framework adapters for fastapi-voyager.
+
+This module provides adapters that allow voyager to work with different web frameworks.
+"""
+from fastapi_voyager.adapters.base import VoyagerAdapter
+from fastapi_voyager.adapters.django_ninja_adapter import DjangoNinjaAdapter
+from fastapi_voyager.adapters.fastapi_adapter import FastAPIAdapter
+from fastapi_voyager.adapters.litestar_adapter import LitestarAdapter
+
+__all__ = [
+    "VoyagerAdapter",
+    "FastAPIAdapter",
+    "DjangoNinjaAdapter",
+    "LitestarAdapter",
+]

fastapi_voyager/adapters/base.py

@@ -0,0 +1,44 @@
+"""
+Base adapter interface for framework-agnostic voyager server.
+
+This module defines the abstract interface that all framework adapters must implement.
+"""
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class VoyagerAdapter(ABC):
+    """
+    Abstract base class for framework-specific voyager adapters.
+
+    Each adapter is responsible for:
+    1. Creating routes/endpoints for the voyager UI
+    2. Handling HTTP requests and responses in a framework-specific way
+    3. Returning an object that can be mounted/integrated with the target app
+    """
+
+    @abstractmethod
+    def create_app(self) -> Any:
+        """
+        Create and return a framework-specific application object.
+
+        The returned object should be mountable/integrable with the target framework.
+        For example:
+        - FastAPI: returns a FastAPI app
+        - Django Ninja: returns an ASGI application
+        - Litestar: returns a Litestar app
+
+        Returns:
+            A framework-specific application object
+        """
+        pass
+
+    @abstractmethod
+    def get_mount_path(self) -> str:
+        """
+        Get the recommended mount path for the voyager UI.
+
+        Returns:
+            The path where voyager should be mounted (e.g., "/voyager")
+        """
+        pass

fastapi_voyager/adapters/common.py

@@ -0,0 +1,260 @@
+"""
+Shared business logic for voyager endpoints.
+
+This module contains the core logic that is reused across all framework adapters.
+"""
+from pathlib import Path
+from typing import Any
+
+from pydantic_resolve import ErDiagram
+
+from fastapi_voyager.er_diagram import VoyagerErDiagram
+from fastapi_voyager.render import Renderer
+from fastapi_voyager.type import CoreData, SchemaNode, Tag
+from fastapi_voyager.type_helper import get_source, get_vscode_link
+from fastapi_voyager.version import __version__
+from fastapi_voyager.voyager import Voyager
+
+WEB_DIR = Path(__file__).parent.parent / "web"
+WEB_DIR.mkdir(exist_ok=True)
+
+STATIC_FILES_PATH = "/fastapi-voyager-static"
+
+GA_PLACEHOLDER = "<!-- GA_SNIPPET -->"
+VERSION_PLACEHOLDER = "<!-- VERSION_PLACEHOLDER -->"
+STATIC_PATH_PLACEHOLDER = "<!-- STATIC_PATH -->"
+
+
+def build_ga_snippet(ga_id: str | None) -> str:
+    """Build Google Analytics snippet."""
+    if not ga_id:
+        return ""
+
+    return f"""    <script async src="https://www.googletagmanager.com/gtag/js?id={ga_id}"></script>
+    <script>
+      window.dataLayer = window.dataLayer || [];
+      function gtag(){{dataLayer.push(arguments);}}
+      gtag('js', new Date());
+
+      gtag('config', '{ga_id}');
+    </script>
+"""
+
+
+class VoyagerContext:
+    """
+    Context object that holds configuration and provides business logic methods.
+
+    This is shared across all framework adapters to avoid code duplication.
+    """
+
+    def __init__(
+        self,
+        target_app: Any,
+        module_color: dict[str, str] | None = None,
+        module_prefix: str | None = None,
+        swagger_url: str | None = None,
+        online_repo_url: str | None = None,
+        initial_page_policy: str = 'first',
+        ga_id: str | None = None,
+        er_diagram: ErDiagram | None = None,
+        enable_pydantic_resolve_meta: bool = False,
+        framework_name: str | None = None,
+    ):
+        self.target_app = target_app
+        self.module_color = module_color or {}
+        self.module_prefix = module_prefix
+        self.swagger_url = swagger_url
+        self.online_repo_url = online_repo_url
+        self.initial_page_policy = initial_page_policy
+        self.ga_id = ga_id
+        self.er_diagram = er_diagram
+        self.enable_pydantic_resolve_meta = enable_pydantic_resolve_meta
+        self.framework_name = framework_name or "API"
+
+    def get_voyager(self, **kwargs) -> Voyager:
+        """Create a Voyager instance with common configuration."""
+        config = {
+            "module_color": self.module_color,
+            "show_pydantic_resolve_meta": self.enable_pydantic_resolve_meta,
+        }
+        config.update(kwargs)
+        return Voyager(**config)
+
+    def analyze_and_get_dot(self) -> tuple[str, list[Tag], list[SchemaNode]]:
+        """
+        Analyze the target app and return dot graph, tags, and schemas.
+
+        Returns:
+            Tuple of (dot_graph, tags, schemas)
+        """
+        voyager = self.get_voyager()
+        voyager.analysis(self.target_app)
+        dot = voyager.render_dot()
+
+        # include tags and their routes
+        tags = voyager.tags
+        for t in tags:
+            t.routes.sort(key=lambda r: r.name)
+        tags.sort(key=lambda t: t.name)
+
+        schemas = voyager.nodes[:]
+        schemas.sort(key=lambda s: s.name)
+
+        return dot, tags, schemas
+
+    def get_option_param(self) -> dict:
+        """Get the option parameter for the voyager UI."""
+        dot, tags, schemas = self.analyze_and_get_dot()
+
+        return {
+            "tags": tags,
+            "schemas": schemas,
+            "dot": dot,
+            "enable_brief_mode": bool(self.module_prefix),
+            "version": __version__,
+            "swagger_url": self.swagger_url,
+            "initial_page_policy": self.initial_page_policy,
+            "has_er_diagram": self.er_diagram is not None,
+            "enable_pydantic_resolve_meta": self.enable_pydantic_resolve_meta,
+            "framework_name": self.framework_name,
+        }
+
+    def get_search_dot(self, payload: dict) -> list[Tag]:
+        """Get filtered tags for search."""
+        voyager = self.get_voyager(
+            schema=payload.get("schema_name"),
+            schema_field=payload.get("schema_field"),
+            show_fields=payload.get("show_fields", "object"),
+            hide_primitive_route=payload.get("hide_primitive_route", False),
+            show_module=payload.get("show_module", True),
+            show_pydantic_resolve_meta=payload.get("show_pydantic_resolve_meta", False),
+        )
+        voyager.analysis(self.target_app)
+        tags = voyager.calculate_filtered_tag_and_route()
+
+        for t in tags:
+            t.routes.sort(key=lambda r: r.name)
+        tags.sort(key=lambda t: t.name)
+
+        return tags
+
+    def get_filtered_dot(self, payload: dict) -> str:
+        """Get filtered dot graph."""
+        voyager = self.get_voyager(
+            include_tags=payload.get("tags"),
+            schema=payload.get("schema_name"),
+            schema_field=payload.get("schema_field"),
+            show_fields=payload.get("show_fields", "object"),
+            route_name=payload.get("route_name"),
+            hide_primitive_route=payload.get("hide_primitive_route", False),
+            show_module=payload.get("show_module", True),
+            show_pydantic_resolve_meta=payload.get("show_pydantic_resolve_meta", False),
+        )
+        voyager.analysis(self.target_app)
+
+        if payload.get("brief"):
+            if payload.get("tags"):
+                return voyager.render_tag_level_brief_dot(module_prefix=self.module_prefix)
+            else:
+                return voyager.render_overall_brief_dot(module_prefix=self.module_prefix)
+        else:
+            return voyager.render_dot()
+
+    def get_core_data(self, payload: dict) -> CoreData:
+        """Get core data for the graph."""
+        voyager = self.get_voyager(
+            include_tags=payload.get("tags"),
+            schema=payload.get("schema_name"),
+            schema_field=payload.get("schema_field"),
+            show_fields=payload.get("show_fields", "object"),
+            route_name=payload.get("route_name"),
+        )
+        voyager.analysis(self.target_app)
+        return voyager.dump_core_data()
+
+    def render_dot_from_core_data(self, core_data: CoreData) -> str:
+        """Render dot graph from core data."""
+        renderer = Renderer(
+            show_fields=core_data.show_fields,
+            module_color=core_data.module_color,
+            schema=core_data.schema,
+        )
+        return renderer.render_dot(
+            core_data.tags, core_data.routes, core_data.nodes, core_data.links
+        )
+
+    def get_er_diagram_dot(self, payload: dict) -> str:
+        """Get ER diagram dot graph."""
+        if self.er_diagram:
+            return VoyagerErDiagram(
+                self.er_diagram,
+                show_fields=payload.get("show_fields", "object"),
+                show_module=payload.get("show_module", True),
+            ).render_dot()
+        return ""
+
+    def get_index_html(self) -> str:
+        """Get the index HTML content."""
+        index_file = WEB_DIR / "index.html"
+        if index_file.exists():
+            content = index_file.read_text(encoding="utf-8")
+            content = content.replace(GA_PLACEHOLDER, build_ga_snippet(self.ga_id))
+            content = content.replace(VERSION_PLACEHOLDER, f"?v={__version__}")
+            # Replace static files path placeholder with actual path (without leading slash)
+            content = content.replace(STATIC_PATH_PLACEHOLDER, STATIC_FILES_PATH.lstrip("/"))
+            return content
+        # fallback simple page if index.html missing
+        return """
+        <!doctype html>
+        <html>
+        <head><meta charset="utf-8"><title>Graphviz Preview</title></head>
+        <body>
+          <p>index.html not found. Create one under src/fastapi_voyager/web/index.html</p>
+        </body>
+        </html>
+        """
+
+    def get_source_code(self, schema_name: str) -> dict:
+        """Get source code for a schema."""
+        try:
+            components = schema_name.split(".")
+            if len(components) < 2:
+                return {"error": "Invalid schema name format. Expected format: module.ClassName"}
+
+            module_name = ".".join(components[:-1])
+            class_name = components[-1]
+
+            mod = __import__(module_name, fromlist=[class_name])
+            obj = getattr(mod, class_name)
+            source_code = get_source(obj)
+
+            return {"source_code": source_code}
+        except ImportError as e:
+            return {"error": f"Module not found: {e}"}
+        except AttributeError as e:
+            return {"error": f"Class not found: {e}"}
+        except Exception as e:
+            return {"error": f"Internal error: {str(e)}"}
+
+    def get_vscode_link(self, schema_name: str) -> dict:
+        """Get VSCode link for a schema."""
+        try:
+            components = schema_name.split(".")
+            if len(components) < 2:
+                return {"error": "Invalid schema name format. Expected format: module.ClassName"}
+
+            module_name = ".".join(components[:-1])
+            class_name = components[-1]
+
+            mod = __import__(module_name, fromlist=[class_name])
+            obj = getattr(mod, class_name)
+            link = get_vscode_link(obj, online_repo_url=self.online_repo_url)
+
+            return {"link": link}
+        except ImportError as e:
+            return {"error": f"Module not found: {e}"}
+        except AttributeError as e:
+            return {"error": f"Class not found: {e}"}
+        except Exception as e:
+            return {"error": f"Internal error: {str(e)}"}

fastapi_voyager/adapters/django_ninja_adapter.py

@@ -0,0 +1,299 @@
+"""
+Django Ninja adapter for fastapi-voyager.
+
+This module provides the Django Ninja-specific implementation of the voyager server.
+It creates an ASGI application that can be integrated with Django.
+"""
+import json
+import mimetypes
+from typing import Any
+
+from fastapi_voyager.adapters.base import VoyagerAdapter
+from fastapi_voyager.adapters.common import STATIC_FILES_PATH, WEB_DIR, VoyagerContext
+from fastapi_voyager.type import CoreData, SchemaNode, Tag
+
+
+class DjangoNinjaAdapter(VoyagerAdapter):
+    """
+    Django Ninja-specific implementation of VoyagerAdapter.
+
+    Creates an ASGI application with voyager endpoints that can be integrated with Django.
+    """
+
+    def __init__(
+        self,
+        target_app: Any,
+        module_color: dict[str, str] | None = None,
+        gzip_minimum_size: int | None = 500,
+        module_prefix: str | None = None,
+        swagger_url: str | None = None,
+        online_repo_url: str | None = None,
+        initial_page_policy: str = "first",
+        ga_id: str | None = None,
+        er_diagram: Any = None,
+        enable_pydantic_resolve_meta: bool = False,
+    ):
+        self.ctx = VoyagerContext(
+            target_app=target_app,
+            module_color=module_color,
+            module_prefix=module_prefix,
+            swagger_url=swagger_url,
+            online_repo_url=online_repo_url,
+            initial_page_policy=initial_page_policy,
+            ga_id=ga_id,
+            er_diagram=er_diagram,
+            enable_pydantic_resolve_meta=enable_pydantic_resolve_meta,
+            framework_name="Django Ninja",
+        )
+        # Note: gzip should be handled by Django's middleware, not here
+
+    async def _handle_request(self, scope, receive, send):
+        """ASGI request handler."""
+        if scope["type"] != "http":
+            return
+
+        # Parse the request
+        method = scope["method"]
+        path = scope["path"]
+        # Remove /voyager prefix for internal routing
+        if path.startswith("/voyager"):
+            path = path[8:]  # Remove '/voyager'
+            if path == "":
+                path = "/"
+
+        # Handle static files
+        if method == "GET" and path.startswith(f"{STATIC_FILES_PATH}/"):
+            await self._handle_static_file(path, send)
+            return
+
+        # Route the request
+        if method == "GET" and path == "/":
+            await self._handle_index(send)
+        elif method == "GET" and path == "/dot":
+            await self._handle_get_dot(send)
+        elif method == "POST" and path == "/er-diagram":
+            await self._handle_post_request(receive, send, self._handle_er_diagram)
+        elif method == "POST" and path == "/dot-search":
+            await self._handle_post_request(receive, send, self._handle_search_dot)
+        elif method == "POST" and path == "/dot":
+            await self._handle_post_request(receive, send, self._handle_filtered_dot)
+        elif method == "POST" and path == "/dot-core-data":
+            await self._handle_post_request(receive, send, self._handle_core_data)
+        elif method == "POST" and path == "/dot-render-core-data":
+            await self._handle_post_request(receive, send, self._handle_render_core_data)
+        elif method == "POST" and path == "/source":
+            await self._handle_post_request(receive, send, self._handle_source)
+        elif method == "POST" and path == "/vscode-link":
+            await self._handle_post_request(receive, send, self._handle_vscode_link)
+        else:
+            await self._send_404(send)
+
+    async def _handle_post_request(self, receive, send, handler):
+        """Helper to handle POST requests with JSON body."""
+        body = b""
+        more_body = True
+
+        while more_body:
+            message = await receive()
+            if message["type"] == "http.request":
+                body += message.get("body", b"")
+                more_body = message.get("more_body", False)
+
+        try:
+            payload = json.loads(body.decode())
+            await handler(payload, send)
+        except Exception as e:
+            await self._send_json({"error": str(e)}, send, status_code=400)
+
+    async def _handle_static_file(self, path: str, send):
+        """Handle GET {STATIC_FILES_PATH}/* - serve static files."""
+        # Remove /fastapi-voyager-static/ prefix
+        prefix = f"{STATIC_FILES_PATH}/"
+        file_path = path[len(prefix):]
+        full_path = WEB_DIR / file_path
+
+        # Security check: ensure the path is within WEB_DIR
+        try:
+            full_path = full_path.resolve()
+            web_dir_resolved = WEB_DIR.resolve()
+            if not str(full_path).startswith(str(web_dir_resolved)):
+                await self._send_404(send)
+                return
+        except Exception:
+            await self._send_404(send)
+            return
+
+        if not full_path.exists() or not full_path.is_file():
+            await self._send_404(send)
+            return
+
+        # Read file content
+        try:
+            with open(full_path, "rb") as f:
+                content = f.read()
+
+            # Determine content type
+            content_type, _ = mimetypes.guess_type(str(full_path))
+            if content_type is None:
+                content_type = "application/octet-stream"
+
+            await self._send_response(content_type, content, send)
+        except Exception:
+            await self._send_404(send)
+
+    async def _handle_index(self, send):
+        """Handle GET / - return the index HTML."""
+        html = self.ctx.get_index_html()
+        await self._send_html(html, send)
+
+    async def _handle_get_dot(self, send):
+        """Handle GET /dot - return options and initial dot graph."""
+        data = self.ctx.get_option_param()
+        # Convert tags and schemas to dicts for JSON serialization
+        response_data = {
+            "tags": [self._tag_to_dict(t) for t in data["tags"]],
+            "schemas": [self._schema_to_dict(s) for s in data["schemas"]],
+            "dot": data["dot"],
+            "enable_brief_mode": data["enable_brief_mode"],
+            "version": data["version"],
+            "initial_page_policy": data["initial_page_policy"],
+            "swagger_url": data["swagger_url"],
+            "has_er_diagram": data["has_er_diagram"],
+            "enable_pydantic_resolve_meta": data["enable_pydantic_resolve_meta"],
+            "framework_name": data["framework_name"],
+        }
+        await self._send_json(response_data, send)
+
+    async def _handle_er_diagram(self, payload, send):
+        """Handle POST /er-diagram."""
+        dot = self.ctx.get_er_diagram_dot(payload)
+        await self._send_text(dot, send)
+
+    async def _handle_search_dot(self, payload, send):
+        """Handle POST /dot-search."""
+        tags = self.ctx.get_search_dot(payload)
+        response_data = {"tags": [self._tag_to_dict(t) for t in tags]}
+        await self._send_json(response_data, send)
+
+    async def _handle_filtered_dot(self, payload, send):
+        """Handle POST /dot."""
+        dot = self.ctx.get_filtered_dot(payload)
+        await self._send_text(dot, send)
+
+    async def _handle_core_data(self, payload, send):
+        """Handle POST /dot-core-data."""
+        core_data = self.ctx.get_core_data(payload)
+        await self._send_json(core_data.model_dump(), send)
+
+    async def _handle_render_core_data(self, payload, send):
+        """Handle POST /dot-render-core-data."""
+        core_data = CoreData(**payload)
+        dot = self.ctx.render_dot_from_core_data(core_data)
+        await self._send_text(dot, send)
+
+    async def _handle_source(self, payload, send):
+        """Handle POST /source."""
+        result = self.ctx.get_source_code(payload.get("schema_name", ""))
+        status_code = 200 if "error" not in result else 400
+        if "error" in result and "not found" in result["error"]:
+            status_code = 404
+        await self._send_json(result, send, status_code=status_code)
+
+    async def _handle_vscode_link(self, payload, send):
+        """Handle POST /vscode-link."""
+        result = self.ctx.get_vscode_link(payload.get("schema_name", ""))
+        status_code = 200 if "error" not in result else 400
+        if "error" in result and "not found" in result["error"]:
+            status_code = 404
+        await self._send_json(result, send, status_code=status_code)
+
+    async def _send_html(self, html: str, send):
+        """Send HTML response."""
+        await self._send_response(
+            "text/html; charset=utf-8",
+            html.encode("utf-8"),
+            send,
+            status_code=200,
+        )
+
+    async def _send_json(self, data: dict, send, status_code: int = 200):
+        """Send JSON response."""
+        body = json.dumps(data).encode("utf-8")
+        await self._send_response("application/json", body, send, status_code=status_code)
+
+    async def _send_text(self, text: str, send):
+        """Send plain text response."""
+        await self._send_response("text/plain; charset=utf-8", text.encode("utf-8"), send)
+
+    async def _send_404(self, send):
+        """Send 404 response."""
+        await self._send_response("text/plain", b"Not Found", send, status_code=404)
+
+    async def _send_response(
+        self, content_type: str, body: bytes, send, status_code: int = 200
+    ):
+        """Send ASGI response."""
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status_code,
+                "headers": [
+                    [b"content-type", content_type.encode()],
+                    [b"content-length", str(len(body)).encode()],
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})
+
+    def _tag_to_dict(self, tag: Tag) -> dict:
+        """Convert Tag object to dict."""
+        return {
+            "id": tag.id,
+            "name": tag.name,
+            "routes": [
+                {
+                    "id": r.id,
+                    "name": r.name,
+                    "module": r.module,
+                    "unique_id": r.unique_id,
+                    "response_schema": r.response_schema,
+                    "is_primitive": r.is_primitive,
+                }
+                for r in tag.routes
+            ],
+        }
+
+    def _schema_to_dict(self, schema: SchemaNode) -> dict:
+        """Convert SchemaNode to dict."""
+        return {
+            "id": schema.id,
+            "module": schema.module,
+            "name": schema.name,
+            "fields": [
+                {
+                    "name": f.name,
+                    "type_name": f.type_name,
+                    "is_object": f.is_object,
+                    "is_exclude": f.is_exclude,
+                }
+                for f in schema.fields
+            ],
+        }
+
+    def create_app(self):
+        """Create and return an ASGI application."""
+
+        async def asgi_app(scope, receive, send):
+            # Route /voyager/* to voyager handler
+            if scope["type"] == "http" and scope["path"].startswith("/voyager"):
+                await self._handle_request(scope, receive, send)
+            else:
+                # Return 404 for non-voyager paths
+                # (Django should handle these before they reach here)
+                await self._send_404(send)
+
+        return asgi_app
+
+    def get_mount_path(self) -> str:
+        """Get the recommended mount path for voyager."""
+        return "/voyager"