fastapi-voyager 0.16.0a2__tar.gz → 0.16.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-voyager
-Version: 0.16.0a2
+Version: 0.16.1
 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
@@ -205,34 +205,44 @@ uvicorn your_app:application --reload
 
 ### Litestar
 
+Litestar doesn't support mounting to an existing app like FastAPI. The recommended pattern is to export `ROUTE_HANDLERS` from your main app:
+
 ```python
-from litestar import Litestar, get
-from fastapi_voyager import create_voyager
+# In your main app file (e.g., app.py)
+from litestar import Litestar, Controller
 
-# Create Litestar app
-app = Litestar()
+class MyController(Controller):
+    # ... your routes ...
 
-@get("/hello")
-def hello() -> dict:
-    return {"message": "Hello World"}
+ROUTE_HANDLERS = [MyController]  # Export for extension
+app = Litestar(route_handlers=ROUTE_HANDLERS)
+```
 
-# Create voyager app (returns a Litestar app)
-voyager_app = create_voyager(app)
+Then create voyager by reusing `ROUTE_HANDLERS`:
 
-# Create ASGI application that routes between main app and voyager
-async def asgi_app(scope, receive, send):
-    if scope["type"] == "http" and scope["path"].startswith("/voyager"):
-        # Remove /voyager prefix for voyager app
-        new_scope = dict(scope)
-        new_scope["path"] = scope["path"][8:] or "/"
-        await voyager_app(new_scope, receive, send)
-    else:
-        await app(scope, receive, send)
+```python
+# In your voyager embedding file
+from typing import Any, Awaitable, Callable
+from litestar import Litestar, asgi
+from fastapi_voyager import create_voyager
+from your_app import ROUTE_HANDLERS, app as your_app
+
+voyager_app = create_voyager(your_app)
+
+@asgi("/voyager", is_mount=True, copy_scope=True)
+async def voyager_mount(
+    scope: dict[str, Any],
+    receive: Callable[[], Awaitable[dict[str, Any]]],
+    send: Callable[[dict[str, Any]], Awaitable[None]]
+) -> None:
+    await voyager_app(scope, receive, send)
+
+app = Litestar(route_handlers=ROUTE_HANDLERS + [voyager_mount])
 ```
 
 Start with:
 ```bash
-uvicorn your_app:asgi_app --reload
+uvicorn your_app:app --reload
 # Visit http://localhost:8000/voyager
 ```
 
@@ -319,8 +329,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
@@ -329,6 +345,8 @@ voyager -m tests.demo --server --port=8002
 voyager -m tests.demo --server --app my_app
 ```
 
+> **Note**: Server mode does not support ER diagram or pydantic-resolve metadata configuration. Use `create_voyager()` in your code with `er_diagram` and `enable_pydantic_resolve_meta` parameters to enable these features.
+
 ### Generate DOT File
 
 ```bash

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

@@ -154,34 +154,44 @@ uvicorn your_app:application --reload
 
 ### Litestar
 
+Litestar doesn't support mounting to an existing app like FastAPI. The recommended pattern is to export `ROUTE_HANDLERS` from your main app:
+
 ```python
-from litestar import Litestar, get
-from fastapi_voyager import create_voyager
+# In your main app file (e.g., app.py)
+from litestar import Litestar, Controller
 
-# Create Litestar app
-app = Litestar()
+class MyController(Controller):
+    # ... your routes ...
 
-@get("/hello")
-def hello() -> dict:
-    return {"message": "Hello World"}
+ROUTE_HANDLERS = [MyController]  # Export for extension
+app = Litestar(route_handlers=ROUTE_HANDLERS)
+```
 
-# Create voyager app (returns a Litestar app)
-voyager_app = create_voyager(app)
+Then create voyager by reusing `ROUTE_HANDLERS`:
 
-# Create ASGI application that routes between main app and voyager
-async def asgi_app(scope, receive, send):
-    if scope["type"] == "http" and scope["path"].startswith("/voyager"):
-        # Remove /voyager prefix for voyager app
-        new_scope = dict(scope)
-        new_scope["path"] = scope["path"][8:] or "/"
-        await voyager_app(new_scope, receive, send)
-    else:
-        await app(scope, receive, send)
+```python
+# In your voyager embedding file
+from typing import Any, Awaitable, Callable
+from litestar import Litestar, asgi
+from fastapi_voyager import create_voyager
+from your_app import ROUTE_HANDLERS, app as your_app
+
+voyager_app = create_voyager(your_app)
+
+@asgi("/voyager", is_mount=True, copy_scope=True)
+async def voyager_mount(
+    scope: dict[str, Any],
+    receive: Callable[[], Awaitable[dict[str, Any]]],
+    send: Callable[[dict[str, Any]], Awaitable[None]]
+) -> None:
+    await voyager_app(scope, receive, send)
+
+app = Litestar(route_handlers=ROUTE_HANDLERS + [voyager_mount])
 ```
 
 Start with:
 ```bash
-uvicorn your_app:asgi_app --reload
+uvicorn your_app:app --reload
 # Visit http://localhost:8000/voyager
 ```
 
@@ -268,8 +278,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
@@ -278,6 +294,8 @@ voyager -m tests.demo --server --port=8002
 voyager -m tests.demo --server --app my_app
 ```
 
+> **Note**: Server mode does not support ER diagram or pydantic-resolve metadata configuration. Use `create_voyager()` in your code with `er_diagram` and `enable_pydantic_resolve_meta` parameters to enable these features.
+
 ### Generate DOT File
 
 ```bash

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.1}/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.1}/setup-litestar.sh

@@ -39,10 +39,10 @@ echo ""
 
 # Start Litestar server
 echo "🌟 Starting Litestar Voyager server..."
-echo "   App: tests.litestar.embedding:asgi_app"
+echo "   App: tests.litestar.embedding:app"
 echo "   URL: http://127.0.0.1:8000"
 echo ""
 echo "Press Ctrl+C to stop the server"
 echo ""
 
-uv run uvicorn tests.litestar.embedding:asgi_app --reload --host 127.0.0.1 --port 8000
+uv run uvicorn tests.litestar.embedding:app --reload --host 127.0.0.1 --port 8000

{fastapi_voyager-0.16.0a2 → fastapi_voyager-0.16.1}/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.1}/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.1}/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.1}/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.1}/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