fastapi-voyager 0.11.10__py3-none-any.whl → 0.11.11__py3-none-any.whl

fastapi_voyager/cli.py

@@ -1,15 +1,18 @@
 """Command line interface for fastapi-voyager."""
 import argparse
-import sys
-import importlib.util
 import importlib
+import importlib.util
+import logging
 import os
+import sys
 from typing import Optional
 
 from fastapi import FastAPI
-from fastapi_voyager.voyager import Voyager
-from fastapi_voyager.version import __version__
 from fastapi_voyager import server as viz_server
+from fastapi_voyager.version import __version__
+from fastapi_voyager.voyager import Voyager
+
+logger = logging.getLogger(__name__)
 
 
 def load_fastapi_app_from_file(module_path: str, app_name: str = "app") -> Optional[FastAPI]:
@@ -22,7 +25,7 @@ def load_fastapi_app_from_file(module_path: str, app_name: str = "app") -> Optio
         # Load the module
         spec = importlib.util.spec_from_file_location("app_module", module_path)
         if spec is None or spec.loader is None:
-            print(f"Error: Could not load module from {module_path}")
+            logger.error(f"Could not load module from {module_path}")
             return None
             
         module = importlib.util.module_from_spec(spec)
@@ -34,15 +37,13 @@ def load_fastapi_app_from_file(module_path: str, app_name: str = "app") -> Optio
             app = getattr(module, app_name)
             if isinstance(app, FastAPI):
                 return app
-            else:
-                print(f"Error: '{app_name}' is not a FastAPI instance")
-                return None
-        else:
-            print(f"Error: No attribute '{app_name}' found in the module")
+            logger.error(f"'{app_name}' is not a FastAPI instance")
             return None
+        logger.error(f"No attribute '{app_name}' found in the module")
+        return None
             
     except Exception as e:
-        print(f"Error loading FastAPI app: {e}")
+        logger.error(f"Error loading FastAPI app: {e}")
         return None
 
 
@@ -66,22 +67,20 @@ def load_fastapi_app_from_module(module_name: str, app_name: str = "app") -> Opt
                 app = getattr(module, app_name)
                 if isinstance(app, FastAPI):
                     return app
-                else:
-                    print(f"Error: '{app_name}' is not a FastAPI instance")
-                    return None
-            else:
-                print(f"Error: No attribute '{app_name}' found in module '{module_name}'")
+                logger.error(f"'{app_name}' is not a FastAPI instance")
                 return None
+            logger.error(f"No attribute '{app_name}' found in module '{module_name}'")
+            return None
         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:
-        print(f"Error: Could not import module '{module_name}': {e}")
+        logger.error(f"Could not import module '{module_name}': {e}")
         return None
     except Exception as e:
-        print(f"Error loading FastAPI app from module '{module_name}': {e}")
+        logger.error(f"Error loading FastAPI app from module '{module_name}': {e}")
         return None
 
 
@@ -110,9 +109,9 @@ def generate_visualization(
     # Optionally write to file
     with open(output_file, 'w', encoding='utf-8') as f:
         f.write(dot_content)
-    print(f"DOT file generated: {output_file}")
-    print("To render the graph, use: dot -Tpng router_viz.dot -o router_viz.png")
-    print("Or view online: https://dreampuf.github.io/GraphvizOnline/")
+    logger.info(f"DOT file generated: {output_file}")
+    logger.info("To render the graph, use: dot -Tpng router_viz.dot -o router_viz.png")
+    logger.info("Or view online: https://dreampuf.github.io/GraphvizOnline/")
 
 
 def main():
@@ -217,41 +216,30 @@ Examples:
         help="Filter by route id (format: <endpoint>_<path with _>)"
     )
     parser.add_argument(
-        "--demo",
-        action="store_true",
-        help="Run built-in demo (equivalent to: --module tests.demo --server --module_color=tests.service:blue --module_color=tests.demo:tomato)"
+        "--log-level",
+        dest="log_level",
+        default="INFO",
+        help="Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)"
     )
     
     args = parser.parse_args()
     
-    # Handle demo mode: override module_name and defaults
-    if args.demo:
-        # Force module loading path
-        args.module_name = "tests.demo"
-        # Ensure server mode on
-        args.server = True
-        # Inject default module colors if absent / merge
-        demo_defaults = ["tests.service:blue", "tests.demo:tomato"]
-        existing = set(args.module_color or [])
-        for d in demo_defaults:
-            # only add if same key not already provided
-            key = d.split(":", 1)[0]
-            if not any(mc.startswith(key + ":") for mc in existing):
-                args.module_color = (args.module_color or []) + [d]
-
     if args.module_prefix and not args.server:
         parser.error("--module_prefix can only be used together with --server")
 
-    # Validate required target if not demo
-    if not args.demo and not (args.module_name or args.module):
-        parser.error("You must provide a module file, -m module name, or use --demo")
+    if not (args.module_name or args.module):
+        parser.error("You must provide a module file, -m module name")
+
+    # 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)
     if args.module_name:
         app = load_fastapi_app_from_module(args.module_name, args.app)
     else:
         if not os.path.exists(args.module):
-            print(f"Error: File '{args.module}' not found")
+            logger.error(f"File '{args.module}' not found")
             sys.exit(1)
         app = load_fastapi_app_from_file(args.module, args.app)
     
@@ -279,15 +267,15 @@ Examples:
             try:
                 import uvicorn
             except ImportError:
-                print("Error: uvicorn is required to run the server. Install via 'pip install uvicorn' or 'uv add uvicorn'.")
+                logger.info("uvicorn is required to run the server. Install via 'pip install uvicorn' or 'uv add uvicorn'.")
                 sys.exit(1)
             app_server = viz_server.create_voyager(
                 app,
                 module_color=module_color,
                 module_prefix=args.module_prefix,
             )
-            print(f"Starting preview server at http://{args.host}:{args.port} ... (Ctrl+C to stop)")
-            uvicorn.run(app_server, host=args.host, port=args.port)
+            logger.info(f"Starting 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
             generate_visualization(
@@ -300,7 +288,7 @@ Examples:
                 route_name=args.route_name,
             )
     except Exception as e:
-        print(f"Error generating visualization: {e}")
+        logger.info(f"Error generating visualization: {e}")
         sys.exit(1)
 
 

fastapi_voyager/filter.py

@@ -236,7 +236,6 @@ def filter_subgraph_from_tag_to_schema_by_module_prefix(
     seen_pairs: set[tuple[str, str]] = set()
 
     for link in tag_route_links:
-        # print(link)
         tag_id = link.source_origin
         start_node_id = link.target_origin
         if tag_id is None or start_node_id is None:

fastapi_voyager/render.py

@@ -1,6 +1,9 @@
 from typing import Optional
 from fastapi_voyager.type import SchemaNode, ModuleNode, Link, Tag, Route, FieldType, PK, ModuleRoute
 from fastapi_voyager.module import build_module_schema_tree, build_module_route_tree
+from logging import getLogger
+
+logger = getLogger(__name__)
 
 
 class Renderer:
@@ -17,7 +20,10 @@ class Renderer:
         self.schema = schema
         self.show_module = show_module
 
-    def render_schema_label(self, node: SchemaNode) -> str:
+        logger.info(f'show_module: {self.show_module}')
+        logger.info(f'module_color: {self.module_color}')
+
+    def render_schema_label(self, node: SchemaNode, color: Optional[str]=None) -> str:
         has_base_fields = any(f.from_base for f in node.fields)
         fields = [n for n in node.fields if n.from_base is False]
 
@@ -38,7 +44,8 @@ class Renderer:
             field_str = f"""<tr><td align="left" port="f{field.name}" cellpadding="8"><font>  {display_xml}    </font></td></tr>"""
             fields_parts.append(field_str)
 
-        header_color = 'tomato' if node.id == self.schema else '#009485'
+        default_color = '#009485' if color is None else color
+        header_color = 'tomato' if node.id == self.schema else default_color
         header = f"""<tr><td cellpadding="6" bgcolor="{header_color}" align="center" colspan="1" port="{PK}"> <font color="white">    {node.name}    </font></td> </tr>"""
         field_content = ''.join(fields_parts) if fields_parts else ''
         return f"""<<table border="1" cellborder="0" cellpadding="0" bgcolor="white"> {header} {field_content}   </table>>"""
@@ -67,43 +74,56 @@ class Renderer:
             raise ValueError(f'Unknown link type: {link.type}')
 
     def render_module_schema_content(self, nodes: list[SchemaNode]) -> str:
-        def render_node(node: SchemaNode) -> str:
+        def render_node(node: SchemaNode, color: Optional[str]=None) -> str:
             return f'''
                 "{node.id}" [
-                    label = {self.render_schema_label(node)}
+                    label = {self.render_schema_label(node, color)}
                     shape = "plain"
                     margin="0.5,0.1"
                 ];'''
-        def render_module_schema(mod: ModuleNode) -> str:
-            color: Optional[str] = None
 
+        def render_module_schema(mod: ModuleNode, inherit_color: Optional[str]=None, show_cluster:bool=True) -> str:
+            color: Optional[str] = inherit_color
+
+            # recursively vist module from short to long:  'a', 'a.b', 'a.b.c'
+            # color_flag: {'a', 'a.b.c'}
+            # at first 'a', match 'a' -> color, remove 'a' from color_flag
+            # at 'a.b', no match
+            # at 'a.b.c', match 'a.b.c' -> color, remove 'a.b.c' from color_flag
             for k in module_color_flag:
-                if mod.fullname.startswith(k):
+                if mod.fullname.startswith(k):  
                     module_color_flag.remove(k)
                     color = self.module_color[k]
                     break
 
-            inner_nodes = [ render_node(node) for node in mod.schema_nodes ]
+            inner_nodes = [ render_node(node, color) for node in mod.schema_nodes ]
             inner_nodes_str = '\n'.join(inner_nodes)
-            child_str = '\n'.join(render_module_schema(m) for m in mod.modules)
-            return f'''
-                subgraph cluster_module_{mod.fullname.replace('.', '_')} {{
-                    tooltip="{mod.fullname}"
-                    color = "#666"
-                    style="rounded"
-                    label = "  {mod.name}"
-                    labeljust = "l"
-                    {(f'pencolor = "{color}"' if color else 'pencolor="#ccc"')}
-                    {(f'penwidth = 3' if color else 'penwidth=""')}
+            child_str = '\n'.join(render_module_schema(mod=m, inherit_color=color, show_cluster=show_cluster) for m in mod.modules)
+
+            if show_cluster:
+                return f'''
+                    subgraph cluster_module_{mod.fullname.replace('.', '_')} {{
+                        tooltip="{mod.fullname}"
+                        color = "#666"
+                        style="rounded"
+                        label = "  {mod.name}"
+                        labeljust = "l"
+                        {(f'pencolor = "{color}"' if color else 'pencolor="#ccc"')}
+                        {(f'penwidth = 3' if color else 'penwidth=""')}
+                        {inner_nodes_str}
+                        {child_str}
+                    }}'''
+            else:
+                return f'''
                     {inner_nodes_str}
                     {child_str}
-                }}'''
-        if self.show_module:
-            module_schemas = build_module_schema_tree(nodes)
-            module_color_flag = set(self.module_color.keys())
-            return '\n'.join(render_module_schema(m) for m in module_schemas)
-        else:
-            return '\n'.join(render_node(n) for n in nodes)
+                '''
+
+        # if self.show_module:
+        module_schemas = build_module_schema_tree(nodes)
+        module_color_flag = set(self.module_color.keys())
+        return '\n'.join(render_module_schema(mod=m, show_cluster=self.show_module) for m in module_schemas)
+
     
     def render_module_route_content(self, routes: list[Route]) -> str:
         def render_route(route: Route) -> str:
@@ -115,29 +135,32 @@ class Renderer:
                     shape = "record"
                 ];'''
 
-        def render_module_route(mod: ModuleRoute) -> str:
+        def render_module_route(mod: ModuleRoute, show_cluster: bool=True) -> str:
             # Inner route nodes, same style as flat route_str
             inner_nodes = [
                 render_route(r) for r in mod.routes
             ]
             inner_nodes_str = '\n'.join(inner_nodes)
-            child_str = '\n'.join(render_module_route(m) for m in mod.modules)
-            return f'''
-                subgraph cluster_route_module_{mod.fullname.replace('.', '_')} {{
-                    tooltip="{mod.fullname}"
-                    color = "#666"
-                    style="rounded"
-                    label = "  {mod.name}"
-                    labeljust = "l"
+            child_str = '\n'.join(render_module_route(m, show_cluster=show_cluster) for m in mod.modules)
+            if show_cluster:
+                return f'''
+                    subgraph cluster_route_module_{mod.fullname.replace('.', '_')} {{
+                        tooltip="{mod.fullname}"
+                        color = "#666"
+                        style="rounded"
+                        label = "  {mod.name}"
+                        labeljust = "l"
+                        {inner_nodes_str}
+                        {child_str}
+                    }}'''
+            else:
+                return f'''
                     {inner_nodes_str}
                     {child_str}
-                }}'''
-        if self.show_module:
-            module_routes = build_module_route_tree(routes)
-            module_routes_str = '\n'.join(render_module_route(m) for m in module_routes)
-            return module_routes_str
-        else:
-            return '\n'.join(render_route(r) for r in routes)
+                '''
+        module_routes = build_module_route_tree(routes)
+        module_routes_str = '\n'.join(render_module_route(m, show_cluster=self.show_module) for m in module_routes)
+        return module_routes_str
 
 
     def render_dot(self, tags: list[Tag], routes: list[Route], nodes: list[SchemaNode], links: list[Link], spline_line=False) -> str:

fastapi_voyager/type_helper.py

@@ -1,4 +1,5 @@
 import inspect
+import logging
 import os
 from pydantic import BaseModel
 from typing import get_origin, get_args, Union, Annotated, Any, Type, Generic, Optional
@@ -6,6 +7,8 @@ from fastapi_voyager.type import FieldInfo
 from types import UnionType
 import pydantic_resolve.constant as const
 
+logger = logging.getLogger(__name__)
+
 # Python <3.12 compatibility: TypeAliasType exists only from 3.12 (PEP 695)
 try:  # pragma: no cover - import guard
     from typing import TypeAliasType  # type: ignore
@@ -228,12 +231,11 @@ def get_source(kls):
         return "failed to get source"
 
 
-def safe_issubclass(kls, classinfo):
+def safe_issubclass(kls, target_kls):
     try:
-        return issubclass(kls, classinfo)
+        return issubclass(kls, target_kls)
     except TypeError:
-        # may raise error for corner case such as ForwardRef
-        print(str(kls), 'is not a target class')  
+        logger.debug(f'{kls.__module__}:{kls.__qualname__} is not subclass of {target_kls.__module__}:{target_kls.__qualname__}')  
         return False
 
 

fastapi_voyager/version.py

@@ -1,2 +1,2 @@
 __all__ = ["__version__"]
-__version__ = "0.11.10"
+__version__ = "0.11.11"

{fastapi_voyager-0.11.10.dist-info → fastapi_voyager-0.11.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-voyager
-Version: 0.11.10
+Version: 0.11.11
 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
@@ -52,8 +52,11 @@ uv add fastapi-voyager
 voyager -m path.to.your.app.module --server
 ```
 
-> *sub_app* is not supported yet.
+> [Sub-Application mounts](https://fastapi.tiangolo.com/advanced/sub-applications/) are not supported yet, but you can specify the name of the FastAPI application used with `--app`. Only a single application (default: 'app') can be selected, but in a scenario where `api` is attached through `app.mount("/api", api)`, you can select `api` like this:
 
+```shell
+voyager -m path.to.your.app.module --server --app api
+```
 
 ## Mount into project
 
@@ -141,6 +144,8 @@ voyager -m tests.demo --module_color=tests.demo:red --module_color=tests.service
 voyager -m tests.demo -o my_visualization.dot
 
 voyager --version
+
+voyager --help
 ```
 
 The tool will generate a DOT file that you can render using Graphviz:
@@ -166,8 +171,6 @@ or you can open router_viz.dot with vscode extension `graphviz interactive previ
 - [ ] user can generate nodes/edges manually and connect to generated ones
     - [ ] eg: add owner
     - [ ] add extra info for schema
-- [ ] display standard ER diagram `hard`
-    - [ ] display potential invalid links
 - [ ] optimize static resource (allow manually config url)
 - [ ] improve search dialog
     - [ ] add route/tag list
@@ -178,11 +181,9 @@ or you can open router_viz.dot with vscode extension `graphviz interactive previ
 ### in analysis
 - [ ] click field to highlight links
 - [ ] animation effect for edges
-- [ ] customrized right click panel
-    - [ ] show own dependencies
-- [ ] sort field name
-- [ ] set max limit for fields
-- [ ] logging information
+- [ ] display standard ER diagram spec. `hard but important`
+    - [ ] display potential invalid links
+    - [ ] highlight relationship belongs to ER diagram
 
 ### plan:
 #### <0.9:
@@ -279,15 +280,28 @@ or you can open router_viz.dot with vscode extension `graphviz interactive previ
     - [x] replace issubclass with safe_issubclass to prevent exception.
 - 0.11.10
     - [x] fix bug during updating forward refs
+- 0.11.11
+    - [x] replace print with logging and add `--log-level` in cli, by default info
+    - [x] fill node title color with module color
+    - [x] optimize cluster render logic
+
+### 0.12
+- 0.12.1
+    - [ ] sort tag / route names in left panel
+    - [ ] sort field name in nodes
+    - [ ] set max limit for fields in nodes
+    - [ ] upgrade network algorithm (optional)
+    - [ ] refactor render.py
 
-#### 0.12
-- [ ] add tests
-- [ ] integration with pydantic-resolve
-    - [ ] show hint for resolve, post fields
-    - [ ] display loader as edges
+#### 0.13
+- 0.12.0
+    - [ ] integration with pydantic-resolve
+        - [ ] show hint for resolve, post fields
+        - [ ] display loader as edges
+    - [ ] add tests
 
 #### 0.13
-- [ ] config release pipeline
+placeholder
 
 
 ## About pydantic-resolve

{fastapi_voyager-0.11.10.dist-info → fastapi_voyager-0.11.11.dist-info}/RECORD

@@ -1,12 +1,12 @@
 fastapi_voyager/__init__.py,sha256=tZy0Nkj8kTaMgbvHy-mGxVcFGVX0Km-36dnzsAIG2uk,230
-fastapi_voyager/cli.py,sha256=kQb4g6JEGZR99e5r8LyFFEeb_-uT-n_gp_sDoYG3R7k,11118
-fastapi_voyager/filter.py,sha256=GY2J9Vfsf_wbFwC-0t74-Lf-OlO77PnhEXD_rmgkfSw,11574
+fastapi_voyager/cli.py,sha256=xK8DT-m2qP38FK2dGhLP-sHEuS29SBw6ACrnX9w85P0,10521
+fastapi_voyager/filter.py,sha256=9Y-NepveIiCLOI-5eXk6DNK9H3dr5_h4xUbWYHkbo7M,11552
 fastapi_voyager/module.py,sha256=Z2QHNmiLk6ZAJlm2nSmO875Q33TweSg8UxZSzIpU9zY,3499
-fastapi_voyager/render.py,sha256=vdwqIync2wsP8gMPY0v_XjRhdPBtbKyRT8yTBa_Ep3Y,8744
+fastapi_voyager/render.py,sha256=8hVsEDQi2-aP3QKN6KI3RnNz0uG-FuDr_k4D7QNsdQQ,9823
 fastapi_voyager/server.py,sha256=G48St-leUcEwshIhTYVotxuFWXDAvzjthOCK9AKh9dI,6497
 fastapi_voyager/type.py,sha256=VmcTB1G-LOT70EWCzi4LU_FUkSGWUIBJX15T_J5HnOo,1764
-fastapi_voyager/type_helper.py,sha256=CxlUIDlM9fo2MP9UDPNkgFOYTeycBAVk3WRYanBMy6I,9448
-fastapi_voyager/version.py,sha256=-MakJnXzJx3P6EPKM_MRAeT0qupzHiUMfwjS2gq2lvY,50
+fastapi_voyager/type_helper.py,sha256=TqtYP2_54aar_iQjD0XhjJPXYhfi6icnPPrxkj0a4sk,9523
+fastapi_voyager/version.py,sha256=PokgCRzjnyxlFdVF1p-f93rdL31U6_AVnSKLvGGed9Y,50
 fastapi_voyager/voyager.py,sha256=nioo56oFDeZ8nwwPWDtaQbkpe4pVssFoBVHCWFhs0K4,13549
 fastapi_voyager/web/graph-ui.js,sha256=DTedkpZNbtufexONVkJ8mOwF_-VnvxoReYHtox6IKR4,5842
 fastapi_voyager/web/graphviz.svg.css,sha256=zDCjjpT0Idufu5YOiZI76PL70-avP3vTyzGPh9M85Do,1563
@@ -26,8 +26,8 @@ fastapi_voyager/web/icon/favicon-16x16.png,sha256=JC07jEzfIYxBIoQn_FHXvyHuxESdhW
 fastapi_voyager/web/icon/favicon-32x32.png,sha256=C7v1h58cfWOsiLp9yOIZtlx-dLasBcq3NqpHVGRmpt4,1859
 fastapi_voyager/web/icon/favicon.ico,sha256=tZolYIXkkBcFiYl1A8ksaXN2VjGamzcSdes838dLvNc,15406
 fastapi_voyager/web/icon/site.webmanifest,sha256=ep4Hzh9zhmiZF2At3Fp1dQrYQuYF_3ZPZxc1KcGBvwQ,263
-fastapi_voyager-0.11.10.dist-info/METADATA,sha256=X_RI_ODfUGnK0XWGptR1coXHtV4ojNMQiyyNJiBfzjk,10713
-fastapi_voyager-0.11.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-fastapi_voyager-0.11.10.dist-info/entry_points.txt,sha256=pEIKoUnIDXEtdMBq8EmXm70m16vELIu1VPz9-TBUFWM,53
-fastapi_voyager-0.11.10.dist-info/licenses/LICENSE,sha256=lNVRR3y_bFVoFKuK2JM8N4sFaj3m-7j29kvL3olFi5Y,1067
-fastapi_voyager-0.11.10.dist-info/RECORD,,
+fastapi_voyager-0.11.11.dist-info/METADATA,sha256=uufha8zMMchzxEm6ZWW5r4VUF26sKl2DQ9G14HefXgw,11451
+fastapi_voyager-0.11.11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fastapi_voyager-0.11.11.dist-info/entry_points.txt,sha256=pEIKoUnIDXEtdMBq8EmXm70m16vELIu1VPz9-TBUFWM,53
+fastapi_voyager-0.11.11.dist-info/licenses/LICENSE,sha256=lNVRR3y_bFVoFKuK2JM8N4sFaj3m-7j29kvL3olFi5Y,1067
+fastapi_voyager-0.11.11.dist-info/RECORD,,