fastapi-voyager 0.15.6__py3-none-any.whl → 0.16.0a2__py3-none-any.whl

fastapi_voyager/adapters/fastapi_adapter.py

@@ -0,0 +1,167 @@
+"""
+FastAPI adapter for fastapi-voyager.
+
+This module provides the FastAPI-specific implementation of the voyager server.
+"""
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+from fastapi_voyager.adapters.base import VoyagerAdapter
+from fastapi_voyager.adapters.common import STATIC_FILES_PATH, VoyagerContext
+from fastapi_voyager.type import CoreData, SchemaNode, Tag
+
+
+class OptionParam(BaseModel):
+    tags: list[Tag]
+    schemas: list[SchemaNode]
+    dot: str
+    enable_brief_mode: bool
+    version: str
+    initial_page_policy: Literal["first", "full", "empty"]
+    swagger_url: str | None = None
+    has_er_diagram: bool = False
+    enable_pydantic_resolve_meta: bool = False
+    framework_name: str = "API"
+
+
+class Payload(BaseModel):
+    tags: list[str] | None = None
+    schema_name: str | None = None
+    schema_field: str | None = None
+    route_name: str | None = None
+    show_fields: str = "object"
+    brief: bool = False
+    hide_primitive_route: bool = False
+    show_module: bool = True
+    show_pydantic_resolve_meta: bool = False
+
+
+class SearchResultOptionParam(BaseModel):
+    tags: list[Tag]
+
+
+class SchemaSearchPayload(BaseModel):
+    schema_name: str | None = None
+    schema_field: str | None = None
+    show_fields: str = "object"
+    brief: bool = False
+    hide_primitive_route: bool = False
+    show_module: bool = True
+    show_pydantic_resolve_meta: bool = False
+
+
+class ErDiagramPayload(BaseModel):
+    show_fields: str = "object"
+    show_module: bool = True
+
+
+class SourcePayload(BaseModel):
+    schema_name: str
+
+
+class FastAPIAdapter(VoyagerAdapter):
+    """
+    FastAPI-specific implementation of VoyagerAdapter.
+
+    Creates a FastAPI application with voyager endpoints.
+    """
+
+    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="FastAPI",
+        )
+        self.gzip_minimum_size = gzip_minimum_size
+
+    def create_app(self) -> Any:
+        """Create and return a FastAPI application with voyager endpoints."""
+        # Lazy import FastAPI to avoid import errors when framework is not installed
+        from fastapi import APIRouter, FastAPI
+        from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse
+        from fastapi.staticfiles import StaticFiles
+        from starlette.middleware.gzip import GZipMiddleware
+
+        router = APIRouter(tags=["fastapi-voyager"])
+
+        @router.post("/er-diagram", response_class=PlainTextResponse)
+        def get_er_diagram(payload: ErDiagramPayload) -> str:
+            return self.ctx.get_er_diagram_dot(payload.model_dump())
+
+        @router.get("/dot", response_model=OptionParam)
+        def get_dot() -> OptionParam:
+            data = self.ctx.get_option_param()
+            return OptionParam(**data)
+
+        @router.post("/dot-search", response_model=SearchResultOptionParam)
+        def get_search_dot(payload: SchemaSearchPayload) -> SearchResultOptionParam:
+            tags = self.ctx.get_search_dot(payload.model_dump())
+            return SearchResultOptionParam(tags=tags)
+
+        @router.post("/dot", response_class=PlainTextResponse)
+        def get_filtered_dot(payload: Payload) -> str:
+            return self.ctx.get_filtered_dot(payload.model_dump())
+
+        @router.post("/dot-core-data", response_model=CoreData)
+        def get_filtered_dot_core_data(payload: Payload) -> CoreData:
+            return self.ctx.get_core_data(payload.model_dump())
+
+        @router.post("/dot-render-core-data", response_class=PlainTextResponse)
+        def render_dot_from_core_data(core_data: CoreData) -> str:
+            return self.ctx.render_dot_from_core_data(core_data)
+
+        @router.get("/", response_class=HTMLResponse)
+        def index() -> str:
+            return self.ctx.get_index_html()
+
+        @router.post("/source")
+        def get_object_by_module_name(payload: SourcePayload) -> JSONResponse:
+            result = self.ctx.get_source_code(payload.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
+            return JSONResponse(content=result, status_code=status_code)
+
+        @router.post("/vscode-link")
+        def get_vscode_link_by_module_name(payload: SourcePayload) -> JSONResponse:
+            result = self.ctx.get_vscode_link(payload.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
+            return JSONResponse(content=result, status_code=status_code)
+
+        app = FastAPI(title="fastapi-voyager demo server")
+
+        if self.gzip_minimum_size is not None and self.gzip_minimum_size >= 0:
+            app.add_middleware(GZipMiddleware, minimum_size=self.gzip_minimum_size)
+
+        from fastapi_voyager.adapters.common import WEB_DIR
+
+        app.mount(STATIC_FILES_PATH, StaticFiles(directory=str(WEB_DIR)), name="static")
+        app.include_router(router)
+
+        return app
+
+    def get_mount_path(self) -> str:
+        """Get the recommended mount path for voyager."""
+        return "/voyager"

fastapi_voyager/adapters/litestar_adapter.py

@@ -0,0 +1,188 @@
+"""
+Litestar adapter for fastapi-voyager.
+
+This module provides the Litestar-specific implementation of the voyager server.
+"""
+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 LitestarAdapter(VoyagerAdapter):
+    """
+    Litestar-specific implementation of VoyagerAdapter.
+
+    Creates a Litestar application with voyager endpoints.
+    """
+
+    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="Litestar",
+        )
+        self.gzip_minimum_size = gzip_minimum_size
+
+    def create_app(self) -> Any:
+        """Create and return a Litestar application with voyager endpoints."""
+        # Lazy import Litestar to avoid import errors when framework is not installed
+        from litestar import Litestar, MediaType, Request, Response, get, post
+        from litestar.static_files import create_static_files_router
+
+        @get("/er-diagram")
+        async def get_er_diagram(request: Request) -> str:
+            payload = await request.json()
+            return self.ctx.get_er_diagram_dot(payload)
+
+        @get("/dot")
+        async def get_dot(request: Request) -> dict:
+            data = self.ctx.get_option_param()
+            # Convert tags and schemas to dicts for JSON serialization
+            return {
+                "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"],
+            }
+
+        @post("/dot-search")
+        async def get_search_dot(request: Request) -> dict:
+            payload = await request.json()
+            tags = self.ctx.get_search_dot(payload)
+            return {"tags": [self._tag_to_dict(t) for t in tags]}
+
+        @post("/dot")
+        async def get_filtered_dot(request: Request) -> str:
+            payload = await request.json()
+            return self.ctx.get_filtered_dot(payload)
+
+        @post("/dot-core-data")
+        async def get_filtered_dot_core_data(request: Request) -> CoreData:
+            payload = await request.json()
+            return self.ctx.get_core_data(payload)
+
+        @post("/dot-render-core-data")
+        async def render_dot_from_core_data(request: Request) -> str:
+            payload = await request.json()
+            core_data = CoreData(**payload)
+            return self.ctx.render_dot_from_core_data(core_data)
+
+        @get("/", media_type=MediaType.HTML)
+        async def index() -> str:
+            return self.ctx.get_index_html()
+
+        @post("/source")
+        async def get_object_by_module_name(request: Request) -> dict:
+            payload = await request.json()
+            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
+            return Response(
+                content=result,
+                status_code=status_code,
+                media_type=MediaType.JSON,
+            )
+
+        @post("/vscode-link")
+        async def get_vscode_link_by_module_name(request: Request) -> dict:
+            payload = await request.json()
+            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
+            return Response(
+                content=result,
+                status_code=status_code,
+                media_type=MediaType.JSON,
+            )
+
+        # Create static files router using the new API (replaces deprecated StaticFilesConfig)
+        static_files_router = create_static_files_router(
+            path=STATIC_FILES_PATH,
+            directories=[str(WEB_DIR)],
+        )
+
+        # Create Litestar app
+        app = Litestar(
+            route_handlers=[
+                get_er_diagram,
+                get_dot,
+                get_search_dot,
+                get_filtered_dot,
+                get_filtered_dot_core_data,
+                render_dot_from_core_data,
+                index,
+                get_object_by_module_name,
+                get_vscode_link_by_module_name,
+                static_files_router,
+            ],
+        )
+
+        return app
+
+    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 get_mount_path(self) -> str:
+        """Get the recommended mount path for voyager."""
+        return "/voyager"

fastapi_voyager/cli.py

@@ -5,17 +5,19 @@ import importlib.util
 import logging
 import os
 import sys
-
-from fastapi import FastAPI
+from typing import TYPE_CHECKING
 
 from fastapi_voyager import server as viz_server
 from fastapi_voyager.version import __version__
 from fastapi_voyager.voyager import Voyager
 
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
 logger = logging.getLogger(__name__)
 
 
-def load_fastapi_app_from_file(module_path: str, app_name: str = "app") -> FastAPI | None:
+def load_fastapi_app_from_file(module_path: str, app_name: str = "app") -> "FastAPI | None":
     """Load FastAPI app from a Python module file."""
     try:
         # Convert relative path to absolute path
@@ -35,6 +37,8 @@ def load_fastapi_app_from_file(module_path: str, app_name: str = "app") -> FastA
         # Get the FastAPI app instance
         if hasattr(module, app_name):
             app = getattr(module, app_name)
+            # Lazy import to avoid import errors when FastAPI is not installed
+            from fastapi import FastAPI
             if isinstance(app, FastAPI):
                 return app
             logger.error(f"'{app_name}' is not a FastAPI instance")
@@ -47,7 +51,7 @@ def load_fastapi_app_from_file(module_path: str, app_name: str = "app") -> FastA
         return None
 
 
-def load_fastapi_app_from_module(module_name: str, app_name: str = "app") -> FastAPI | None:
+def load_fastapi_app_from_module(module_name: str, app_name: str = "app") -> "FastAPI | None":
     """Load FastAPI app from a Python module name."""
     try:
         # Temporarily add the current working directory to sys.path
@@ -65,6 +69,8 @@ def load_fastapi_app_from_module(module_name: str, app_name: str = "app") -> Fas
             # Get the FastAPI app instance
             if hasattr(module, app_name):
                 app = getattr(module, app_name)
+                # Lazy import to avoid import errors when FastAPI is not installed
+                from fastapi import FastAPI
                 if isinstance(app, FastAPI):
                     return app
                 logger.error(f"'{app_name}' is not a FastAPI instance")
@@ -85,7 +91,7 @@ def load_fastapi_app_from_module(module_name: str, app_name: str = "app") -> Fas
 
 
 def generate_visualization(
-    app: FastAPI,
+    app: "FastAPI",
     output_file: str = "router_viz.dot", tags: list[str] | None = None,
     schema: str | None = None,
     show_fields: bool = False,

fastapi_voyager/er_diagram.py

@@ -1,25 +1,26 @@
 from __future__ import annotations
 
-from fastapi_voyager.type_helper import (
-    update_forward_refs,
-    full_class_name,
-    get_core_types,
-    get_type_name
-)
+from logging import getLogger
+
+from pydantic import BaseModel
+from pydantic_resolve import Entity, ErDiagram, MultipleRelationship, Relationship
+
+from fastapi_voyager.render import Renderer
+from fastapi_voyager.render_style import RenderConfig
 from fastapi_voyager.type import (
-    FieldInfo,
     PK,
+    FieldInfo,
     FieldType,
-    LinkType,
     Link,
-    ModuleNode,
+    LinkType,
     SchemaNode,
 )
-from fastapi_voyager.render import Renderer
-from fastapi_voyager.render_style import RenderConfig
-from pydantic import BaseModel
-from pydantic_resolve import ErDiagram, Entity, Relationship, MultipleRelationship
-from logging import getLogger
+from fastapi_voyager.type_helper import (
+    full_class_name,
+    get_core_types,
+    get_type_name,
+    update_forward_refs,
+)
 
 logger = getLogger(__name__)
 

fastapi_voyager/introspectors/__init__.py

@@ -0,0 +1,34 @@
+"""
+Introspectors for different web frameworks.
+
+This package contains built-in introspector implementations for various frameworks.
+"""
+from .base import AppIntrospector, RouteInfo
+from .detector import FrameworkType, detect_framework, get_introspector
+
+# Try to import each introspector, but don't fail if the framework isn't installed
+try:
+    from .fastapi import FastAPIIntrospector
+except ImportError:
+    FastAPIIntrospector = None  # type: ignore
+
+try:
+    from .django_ninja import DjangoNinjaIntrospector
+except ImportError:
+    DjangoNinjaIntrospector = None  # type: ignore
+
+try:
+    from .litestar import LitestarIntrospector
+except ImportError:
+    LitestarIntrospector = None  # type: ignore
+
+__all__ = [
+    "AppIntrospector",
+    "RouteInfo",
+    "FastAPIIntrospector",
+    "DjangoNinjaIntrospector",
+    "LitestarIntrospector",
+    "FrameworkType",
+    "detect_framework",
+    "get_introspector",
+]

fastapi_voyager/introspectors/base.py

@@ -0,0 +1,81 @@
+"""
+Introspection abstraction layer for framework-agnostic route analysis.
+
+This module provides the abstraction that allows fastapi-voyager to work with
+different web frameworks that support OpenAPI and Pydantic, such as:
+- FastAPI
+- Django Ninja
+- Litestar
+- Flask-OpenAPI
+"""
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class RouteInfo:
+    """
+    Standardized route information that works across different frameworks.
+
+    This data class encapsulates the essential information needed by voyager
+    to analyze and visualize routes, independent of the underlying framework.
+    """
+    # Unique identifier for the route (function path)
+    id: str
+
+    # Human-readable name (function name)
+    name: str
+
+    # Module where the route handler is defined
+    module: str
+
+    # Operation ID from OpenAPI spec
+    operation_id: str | None
+
+    # List of tags associated with this route
+    tags: list[str]
+
+    # The route handler function/endpoint
+    endpoint: Callable
+
+    # Response model (should be a Pydantic BaseModel)
+    response_model: type[Any]
+
+    # Any additional framework-specific data
+    extra: dict[str, Any] | None = None
+
+
+class AppIntrospector(ABC):
+    """
+    Abstract base class for app introspection.
+
+    Implement this class to add support for different web frameworks.
+    The introspector is responsible for extracting route information
+    from the framework's internal structure.
+    """
+
+    @abstractmethod
+    def get_routes(self) -> Iterator[RouteInfo]:
+        """
+        Iterate over all available routes in the application.
+
+        Yields:
+            RouteInfo: Standardized route information
+
+        Example:
+            >>> for route in introspector.get_routes():
+            ...     print(f"{route.id}: {route.tags}")
+        """
+        pass
+
+    @abstractmethod
+    def get_swagger_url(self) -> str | None:
+        """
+        Get the URL to the Swagger/OpenAPI documentation.
+
+        Returns:
+            The URL path or None if not available
+        """
+        pass

fastapi_voyager/introspectors/detector.py

@@ -0,0 +1,123 @@
+"""
+Framework detection utility for fastapi-voyager.
+
+This module provides a centralized framework detection mechanism that is used
+by both introspectors and adapters to avoid code duplication.
+"""
+from enum import Enum
+from typing import Any
+
+from fastapi_voyager.introspectors.base import AppIntrospector
+
+
+class FrameworkType(Enum):
+    """Supported framework types."""
+    FASTAPI = "fastapi"
+    DJANGO_NINJA = "django_ninja"
+    LITESTAR = "litestar"
+    UNKNOWN = "unknown"
+
+
+def detect_framework(app: Any) -> FrameworkType:
+    """
+    Detect the framework type of the given application.
+
+    This function uses the same detection logic as the introspector system,
+    ensuring consistency across the codebase.
+
+    Args:
+        app: A web application instance
+
+    Returns:
+        FrameworkType: The detected framework type
+
+    Note:
+        The detection order matters: Litestar is checked before Django Ninja
+        to avoid Django import issues.
+    """
+    # If it's already an introspector, try to determine framework from it
+    if isinstance(app, AppIntrospector):
+        app_class_name = type(app).__name__
+        if "FastAPI" in app_class_name:
+            return FrameworkType.FASTAPI
+        elif "DjangoNinja" in app_class_name or "Ninja" in app_class_name:
+            return FrameworkType.DJANGO_NINJA
+        elif "Litestar" in app_class_name:
+            return FrameworkType.LITESTAR
+        return FrameworkType.UNKNOWN
+
+    # Get the class name for type checking
+    app_class_name = type(app).__name__
+
+    # Try FastAPI
+    try:
+        from fastapi import FastAPI
+        if isinstance(app, FastAPI):
+            return FrameworkType.FASTAPI
+    except ImportError:
+        pass
+
+    # Try Litestar (check before Django Ninja to avoid Django import issues)
+    try:
+        from litestar import Litestar
+        if isinstance(app, Litestar):
+            return FrameworkType.LITESTAR
+    except ImportError:
+        pass
+
+    # Try Django Ninja (check by class name first to avoid import if not needed)
+    try:
+        if app_class_name == "NinjaAPI":
+            from ninja import NinjaAPI
+            if isinstance(app, NinjaAPI):
+                return FrameworkType.DJANGO_NINJA
+    except ImportError:
+        pass
+
+    return FrameworkType.UNKNOWN
+
+
+def get_introspector(app: Any) -> AppIntrospector | None:
+    """
+    Get the appropriate introspector for the given app.
+
+    This is a centralized function that uses the framework detection logic
+    to return the correct introspector instance.
+
+    Args:
+        app: A web application instance or AppIntrospector
+
+    Returns:
+        An AppIntrospector instance, or None if framework not supported
+
+    Raises:
+        TypeError: If the app type is not supported
+    """
+    # If it's already an introspector, return it
+    if isinstance(app, AppIntrospector):
+        return app
+
+    framework = detect_framework(app)
+
+    if framework == FrameworkType.FASTAPI:
+        from fastapi_voyager.introspectors import FastAPIIntrospector
+        if FastAPIIntrospector:
+            return FastAPIIntrospector(app)
+
+    elif framework == FrameworkType.LITESTAR:
+        from fastapi_voyager.introspectors import LitestarIntrospector
+        if LitestarIntrospector:
+            return LitestarIntrospector(app)
+
+    elif framework == FrameworkType.DJANGO_NINJA:
+        from fastapi_voyager.introspectors import DjangoNinjaIntrospector
+        if DjangoNinjaIntrospector:
+            return DjangoNinjaIntrospector(app)
+
+    # If we get here, the app type is not supported
+    raise TypeError(
+        f"Unsupported app type: {type(app).__name__}. "
+        f"Supported types: FastAPI, Django Ninja API, Litestar, or any AppIntrospector implementation. "
+        f"If you're using a different framework, please implement AppIntrospector for that framework. "
+        f"See ADAPTER_EXAMPLE.md for instructions."
+    )