fastapi-voyager 0.16.0a2__tar.gz → 0.16.0a3__tar.gz

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-voyager
-Version: 0.16.0a2
+Version: 0.16.0a3
 Summary: Visualize FastAPI application's routing tree and dependencies
 Project-URL: Homepage, https://github.com/allmonday/fastapi-voyager
 Project-URL: Source, https://github.com/allmonday/fastapi-voyager
@@ -319,8 +319,14 @@ Set `enable_pydantic_resolve_meta=True` in `create_voyager`, then toggle the "py
 ### Start Server
 
 ```bash
-# Open in browser (default port 8000)
-voyager -m tests.demo --server
+# FastAPI
+voyager -m tests.demo --server --web fastapi
+
+# Django Ninja
+voyager -m tests.demo --server --web django-ninja
+
+# Litestar
+voyager -m tests.demo --server --web litestar
 
 # Custom port
 voyager -m tests.demo --server --port=8002

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.0a3}/README.md

@@ -268,8 +268,14 @@ Set `enable_pydantic_resolve_meta=True` in `create_voyager`, then toggle the "py
 ### Start Server
 
 ```bash
-# Open in browser (default port 8000)
-voyager -m tests.demo --server
+# FastAPI
+voyager -m tests.demo --server --web fastapi
+
+# Django Ninja
+voyager -m tests.demo --server --web django-ninja
+
+# Litestar
+voyager -m tests.demo --server --web litestar
 
 # Custom port
 voyager -m tests.demo --server --port=8002

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.0a3}/docs/changelog.md

@@ -181,6 +181,8 @@
     - [x] support django ninja and litestar
 - 0.16.0alpha-2
     - [x] fix import error
+- 0.16.0alpha-3
+    - [x] fix voyager cli, add web parameter
 
 ## 0.17, enhance er diagram
 - 0.17.0

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.0a3}/src/fastapi_voyager/adapters/base.py

@@ -32,13 +32,3 @@ class VoyagerAdapter(ABC):
             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-0.16.0a2 → fastapi_voyager-0.16.0a3}/src/fastapi_voyager/adapters/django_ninja_adapter.py

@@ -32,6 +32,7 @@ class DjangoNinjaAdapter(VoyagerAdapter):
         ga_id: str | None = None,
         er_diagram: Any = None,
         enable_pydantic_resolve_meta: bool = False,
+        server_mode: bool = False,
     ):
         self.ctx = VoyagerContext(
             target_app=target_app,
@@ -45,6 +46,7 @@ class DjangoNinjaAdapter(VoyagerAdapter):
             enable_pydantic_resolve_meta=enable_pydantic_resolve_meta,
             framework_name="Django Ninja",
         )
+        self.server_mode = server_mode
         # Note: gzip should be handled by Django's middleware, not here
 
     async def _handle_request(self, scope, receive, send):
@@ -55,8 +57,8 @@ class DjangoNinjaAdapter(VoyagerAdapter):
         # Parse the request
         method = scope["method"]
         path = scope["path"]
-        # Remove /voyager prefix for internal routing
-        if path.startswith("/voyager"):
+        # Remove /voyager prefix for internal routing (unless in server_mode)
+        if not self.server_mode and path.startswith("/voyager"):
             path = path[8:]  # Remove '/voyager'
             if path == "":
                 path = "/"
@@ -284,16 +286,15 @@ class DjangoNinjaAdapter(VoyagerAdapter):
         """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)
+            # In server_mode, handle all paths; otherwise only handle /voyager/*
+            if scope["type"] == "http":
+                if self.server_mode or 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)
             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"

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.0a3}/src/fastapi_voyager/adapters/fastapi_adapter.py

@@ -79,6 +79,7 @@ class FastAPIAdapter(VoyagerAdapter):
         ga_id: str | None = None,
         er_diagram: Any = None,
         enable_pydantic_resolve_meta: bool = False,
+        server_mode: bool = False,
     ):
         self.ctx = VoyagerContext(
             target_app=target_app,
@@ -93,6 +94,8 @@ class FastAPIAdapter(VoyagerAdapter):
             framework_name="FastAPI",
         )
         self.gzip_minimum_size = gzip_minimum_size
+        # Note: server_mode is accepted for API consistency but not used
+        # since FastAPI apps are always standalone with routes at /
 
     def create_app(self) -> Any:
         """Create and return a FastAPI application with voyager endpoints."""
@@ -161,7 +164,3 @@ class FastAPIAdapter(VoyagerAdapter):
         app.include_router(router)
 
         return app
-
-    def get_mount_path(self) -> str:
-        """Get the recommended mount path for voyager."""
-        return "/voyager"

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.0a3}/src/fastapi_voyager/adapters/litestar_adapter.py

@@ -29,6 +29,7 @@ class LitestarAdapter(VoyagerAdapter):
         ga_id: str | None = None,
         er_diagram: Any = None,
         enable_pydantic_resolve_meta: bool = False,
+        server_mode: bool = False,
     ):
         self.ctx = VoyagerContext(
             target_app=target_app,
@@ -43,6 +44,8 @@ class LitestarAdapter(VoyagerAdapter):
             framework_name="Litestar",
         )
         self.gzip_minimum_size = gzip_minimum_size
+        # Note: server_mode is accepted for API consistency but not used
+        # since Litestar apps are always standalone with routes at /
 
     def create_app(self) -> Any:
         """Create and return a Litestar application with voyager endpoints."""
@@ -182,7 +185,3 @@ class LitestarAdapter(VoyagerAdapter):
                 for f in schema.fields
             ],
         }
-
-    def get_mount_path(self) -> str:
-        """Get the recommended mount path for voyager."""
-        return "/voyager"

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.0a3}/src/fastapi_voyager/cli.py

@@ -5,54 +5,57 @@ import importlib.util
 import logging
 import os
 import sys
-from typing import TYPE_CHECKING
+from typing import Any
 
 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__)
 
+# Framework type constants
+SUPPORTED_FRAMEWORKS = ["fastapi", "litestar", "django-ninja"]
+
 
-def load_fastapi_app_from_file(module_path: str, app_name: str = "app") -> "FastAPI | None":
-    """Load FastAPI app from a Python module file."""
+def load_app_from_file(module_path: str, app_name: str = "app", framework: str | None = None) -> Any:
+    """Load web framework app from a Python module file."""
     try:
         # Convert relative path to absolute path
         if not os.path.isabs(module_path):
             module_path = os.path.abspath(module_path)
-        
+
         # Load the module
         spec = importlib.util.spec_from_file_location("app_module", module_path)
         if spec is None or spec.loader is None:
             logger.error(f"Could not load module from {module_path}")
             return None
-            
+
         module = importlib.util.module_from_spec(spec)
         sys.modules["app_module"] = module
         spec.loader.exec_module(module)
-        
-        # 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")
+
+        # Get the app instance
+        if not hasattr(module, app_name):
+            logger.error(f"No attribute '{app_name}' found in the module")
             return None
-        logger.error(f"No attribute '{app_name}' found in the module")
-        return None
-            
+
+        app = getattr(module, app_name)
+
+        # Verify app type if framework is specified
+        if framework is not None:
+            if not _validate_app_framework(app, framework):
+                logger.error(f"'{app_name}' is not a {framework} instance")
+                return None
+
+        return app
+
     except Exception as e:
-        logger.error(f"Error loading FastAPI app: {e}")
+        logger.error(f"Error loading app: {e}")
         return None
 
 
-def load_fastapi_app_from_module(module_name: str, app_name: str = "app") -> "FastAPI | None":
-    """Load FastAPI app from a Python module name."""
+def load_app_from_module(module_name: str, app_name: str = "app", framework: str | None = None) -> Any:
+    """Load web framework app from a Python module name."""
     try:
         # Temporarily add the current working directory to sys.path
         current_dir = os.getcwd()
@@ -61,37 +64,62 @@ def load_fastapi_app_from_module(module_name: str, app_name: str = "app") -> "Fa
             path_added = True
         else:
             path_added = False
-        
+
         try:
             # Import the module by name
             module = importlib.import_module(module_name)
-            
-            # 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")
+
+            # Get the app instance
+            if not hasattr(module, app_name):
+                logger.error(f"No attribute '{app_name}' found in module '{module_name}'")
                 return None
-            logger.error(f"No attribute '{app_name}' found in module '{module_name}'")
-            return None
+
+            app = getattr(module, app_name)
+
+            # Verify app type if framework is specified
+            if framework is not None:
+                if not _validate_app_framework(app, framework):
+                    logger.error(f"'{app_name}' is not a {framework} instance")
+                    return None
+
+            return app
         finally:
             # Cleanup: if we added the path, remove it
             if path_added and current_dir in sys.path:
                 sys.path.remove(current_dir)
-            
+
     except ImportError as e:
         logger.error(f"Could not import module '{module_name}': {e}")
         return None
     except Exception as e:
-        logger.error(f"Error loading FastAPI app from module '{module_name}': {e}")
+        logger.error(f"Error loading app from module '{module_name}': {e}")
         return None
 
 
+def _validate_app_framework(app: Any, framework: str) -> bool:
+    """Validate that the app matches the expected framework type."""
+    try:
+        if framework == "fastapi":
+            from fastapi import FastAPI
+            return isinstance(app, FastAPI)
+        elif framework == "litestar":
+            from litestar import Litestar
+            return isinstance(app, Litestar)
+        elif framework == "django-ninja":
+            from ninja import NinjaAPI
+            return isinstance(app, NinjaAPI)
+        return False
+    except ImportError as e:
+        logger.error(
+            f"The {framework} package is not installed. "
+            f"Install it with: uv add fastapi-voyager[{framework}]"
+        )
+        logger.debug(f"Import error details: {e}")
+        return False
+
+
 def generate_visualization(
-    app: "FastAPI",
+    app: Any,
     output_file: str = "router_viz.dot", tags: list[str] | None = None,
     schema: str | None = None,
     show_fields: bool = False,
@@ -99,7 +127,7 @@ def generate_visualization(
     route_name: str | None = None,
 ):
 
-    """Generate DOT file for FastAPI router visualization."""
+    """Generate DOT file for API router visualization."""
     analytics = Voyager(
         include_tags=tags,
         schema=schema,
@@ -123,39 +151,46 @@ def generate_visualization(
 def main():
     """Main CLI entry point."""
     parser = argparse.ArgumentParser(
-        description="Visualize FastAPI application's routing tree and dependencies",
+        description="Visualize web application's routing tree and dependencies (supports FastAPI, Litestar, Django-Ninja)",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
-  voyager app.py                                                             # Load 'app' from app.py
-  voyager -m tests.demo                                                      # Load 'app' from demo module
-  voyager -m tests.demo --app=app                                            # Load 'app' from tests.demo
-  voyager -m tests.demo --schema=NodeA                                       # [str] filter nodes by schema name
-  voyager -m tests.demo --tags=page restful                                  # list[str] filter nodes route's tags
-  voyager -m tests.demo --module_color=tests.demo:red --module_color=tests.service:yellow  # list[str] filter nodes route's tags
-  voyager -m tests.demo -o my_graph.dot                                      # Output to my_graph.dot
-  voyager -m tests.demo --server                                             # start a local server to preview
-  voyager -m tests.demo --server --port=8001                                 # start a local server to preview
+  voyager app.py --web fastapi                                                       # Load 'app' from app.py (FastAPI)
+  voyager app.py --web litestar                                                      # Load 'app' from app.py (Litestar)
+  voyager -m tests.demo --web django-ninja                                             # Load 'app' from demo module (Django-Ninja)
+  voyager -m tests.demo --app=api --web fastapi                                       # Load 'api' from tests.demo
+  voyager -m tests.demo --web fastapi --schema=NodeA                                    # filter nodes by schema name
+  voyager -m tests.demo --web fastapi --tags=page restful                               # filter routes by tags
+  voyager -m tests.demo --web fastapi --module_color=tests.demo:red --module_color=tests.service:yellow
+  voyager -m tests.demo --web fastapi -o my_graph.dot                                   # Output to my_graph.dot
+  voyager -m tests.demo --web fastapi --server                                          # start a local server to preview
+  voyager -m tests.demo --web fastapi --server --port=8001                              # start a local server to preview
 """
     )
-    
+
     # Create mutually exclusive group for module loading options
     group = parser.add_mutually_exclusive_group(required=False)
     group.add_argument(
         "module",
         nargs="?",
-        help="Python file containing the FastAPI application"
+        help="Python file containing the web application"
     )
     group.add_argument(
         "-m", "--module",
         dest="module_name",
-        help="Python module name containing the FastAPI application (like python -m)"
+        help="Python module name containing the web application (like python -m)"
     )
-    
+
+    parser.add_argument(
+        "--web",
+        choices=SUPPORTED_FRAMEWORKS,
+        help="Web framework type (required when using --server): fastapi, litestar, django-ninja"
+    )
+
     parser.add_argument(
         "--app", "-a",
         default="app",
-        help="Name of the FastAPI app variable (default: app)"
+        help="Name of the app variable (default: app)"
     )
     
     parser.add_argument(
@@ -229,26 +264,34 @@ Examples:
     )
     
     args = parser.parse_args()
-    
+
+    # Validate arguments
     if args.module_prefix and not args.server:
         parser.error("--module_prefix can only be used together with --server")
 
     if not (args.module_name or args.module):
-        parser.error("You must provide a module file, -m module name")
+        parser.error("You must provide a module file or -m module name")
+
+    # When --server is used, --web is required
+    if args.server and not args.web:
+        parser.error("--web is required when using --server. Please specify: fastapi, litestar, or django-ninja")
+
+    # Determine the framework (default to the one specified, or None for non-server mode)
+    framework = args.web if args.server else None
 
     # Configure logging based on --log-level
     level_name = (args.log_level or "INFO").upper()
     logging.basicConfig(level=level_name)
 
-    # Load FastAPI app based on the input method (module_name takes precedence)
+    # Load app based on the input method (module_name takes precedence)
     if args.module_name:
-        app = load_fastapi_app_from_module(args.module_name, args.app)
+        app = load_app_from_module(args.module_name, args.app, framework)
     else:
         if not os.path.exists(args.module):
             logger.error(f"File '{args.module}' not found")
             sys.exit(1)
-        app = load_fastapi_app_from_file(args.module, args.app)
-    
+        app = load_app_from_file(args.module, args.app, framework)
+
     if app is None:
         sys.exit(1)
     
@@ -269,18 +312,21 @@ Examples:
     try:
         module_color = parse_kv_pairs(args.module_color)
         if args.server:
-            # Build a preview server which computes DOT via Analytics using closure state
+            # Build a preview server using the appropriate framework
             try:
                 import uvicorn
             except ImportError:
                 logger.info("uvicorn is required to run the server. Install via 'pip install uvicorn' or 'uv add uvicorn'.")
                 sys.exit(1)
+
+            # Create voyager app - it auto-detects framework and returns appropriate app type
             app_server = viz_server.create_voyager(
                 app,
                 module_color=module_color,
                 module_prefix=args.module_prefix,
+                server_mode=True,  # Enable server mode to serve at root path
             )
-            logger.info(f"Starting preview server at http://{args.host}:{args.port} ... (Ctrl+C to stop)")
+            logger.info(f"Starting {args.web} preview server at http://{args.host}:{args.port} ... (Ctrl+C to stop)")
             uvicorn.run(app_server, host=args.host, port=args.port, log_level=level_name.lower())
         else:
             # Generate and write dot file locally

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.0a3}/src/fastapi_voyager/server.py

@@ -25,6 +25,7 @@ def _get_adapter(
     ga_id: str | None = None,
     er_diagram: ErDiagram | None = None,
     enable_pydantic_resolve_meta: bool = False,
+    server_mode: bool = False,
 ) -> Any:
     """
     Get the appropriate adapter for the given target app.
@@ -64,6 +65,7 @@ def _get_adapter(
             ga_id=ga_id,
             er_diagram=er_diagram,
             enable_pydantic_resolve_meta=enable_pydantic_resolve_meta,
+            server_mode=server_mode,
         )
 
     elif framework == FrameworkType.LITESTAR:
@@ -78,6 +80,7 @@ def _get_adapter(
             ga_id=ga_id,
             er_diagram=er_diagram,
             enable_pydantic_resolve_meta=enable_pydantic_resolve_meta,
+            server_mode=server_mode,
         )
 
     elif framework == FrameworkType.DJANGO_NINJA:
@@ -92,6 +95,7 @@ def _get_adapter(
             ga_id=ga_id,
             er_diagram=er_diagram,
             enable_pydantic_resolve_meta=enable_pydantic_resolve_meta,
+            server_mode=server_mode,
         )
 
     # If we get here, the app type is not supported
@@ -114,6 +118,7 @@ def create_voyager(
     ga_id: str | None = None,
     er_diagram: ErDiagram | None = None,
     enable_pydantic_resolve_meta: bool = False,
+    server_mode: bool = False,
 ) -> Any:
     """
     Create a voyager UI application for the given target app.
@@ -136,6 +141,7 @@ def create_voyager(
         ga_id: Optional Google Analytics tracking ID
         er_diagram: Optional ER diagram from pydantic-resolve
         enable_pydantic_resolve_meta: Enable display of pydantic-resolve metadata
+        server_mode: If True, serve voyager UI at root path (for standalone preview mode)
 
     Returns:
         A framework-specific application object that provides the voyager UI
@@ -176,6 +182,7 @@ def create_voyager(
         ga_id=ga_id,
         er_diagram=er_diagram,
         enable_pydantic_resolve_meta=enable_pydantic_resolve_meta,
+        server_mode=server_mode,
     )
 
     return adapter.create_app()

fastapi_voyager-0.16.0a3/src/fastapi_voyager/version.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.16.0alpha-3"

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.0a3}/tests/litestar/demo.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 from typing import Annotated, Generic, TypeVar
 
-from litestar import Controller, get
+from litestar import Controller, Litestar, get
 from pydantic import BaseModel, Field
 from pydantic_resolve import Collector, DefineSubset, ExposeAs, Resolver, SendTo
 
@@ -130,3 +130,9 @@ class DemoController(Controller):
     @get("/page_test_5/", tags=['long_long_long_tag_name', 'group_b'], sync_to_thread=False)
     def get_page_test_3_no_response_model_long_long_long_name(self) -> bool:
         return True
+
+
+# Create a Litestar app instance - this is the main app that can be run directly
+app = Litestar(
+    route_handlers=[DemoController]
+)

fastapi_voyager-0.16.0a3/tests/litestar/embedding.py

@@ -0,0 +1,53 @@
+"""
+Litestar embedding example for fastapi-voyager.
+
+This module demonstrates how to integrate voyager with a Litestar application.
+"""
+from fastapi_voyager import create_voyager
+from tests.litestar.demo import app, diagram
+
+# Create voyager app for visualization
+# Note: create_voyager automatically detects Litestar and returns a Litestar app
+voyager_app = create_voyager(
+    app,
+    er_diagram=diagram,
+    module_color={"tests.service": "purple"},
+    module_prefix="tests.service",
+    swagger_url="/schema/swagger",
+    initial_page_policy='first',
+    ga_id='G-R64S7Q49VL',
+    online_repo_url="https://github.com/allmonday/fastapi-voyager/blob/main",
+    enable_pydantic_resolve_meta=True
+)
+
+# ASGI app that routes between main app and voyager
+# This allows voyager to be accessed at /voyager while the main app handles other routes
+async def asgi_app(scope, receive, send):
+    """
+    ASGI app that routes between main app and voyager.
+
+    Usage:
+        uvicorn tests.litestar.embedding:asgi_app --reload
+
+    Then access:
+        - http://localhost:8000/demo/* for the main app
+        - http://localhost:8000/voyager for voyager UI
+    """
+    if scope["type"] == "http" and scope["path"].startswith("/voyager"):
+        # Forward to voyager app
+        # Remove /voyager prefix for the voyager app (it expects root path)
+        new_scope = dict(scope)
+        new_scope["path"] = scope["path"][8:]  # Remove '/voyager'
+        if new_scope["path"] == "":
+            new_scope["path"] = "/"
+        if "raw_path" in new_scope:
+            new_scope["raw_path"] = scope["raw_path"][8:]
+        await voyager_app(new_scope, receive, send)
+    else:
+        # Forward to main app
+        await app(scope, receive, send)
+
+# Exports
+# - Use `uvicorn tests.litestar.embedding:asgi_app --reload` for combined app (main + voyager at /voyager)
+# - Use `uvicorn tests.litestar.embedding:app --reload` for main app only
+# - Use `uvicorn tests.litestar.embedding:voyager_app --reload` for voyager only