fastapi-voyager 0.11.10__tar.gz → 0.11.11__tar.gz

{fastapi_voyager-0.11.10 → fastapi_voyager-0.11.11}/PKG-INFO

@@ -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 → fastapi_voyager-0.11.11}/README.md

@@ -23,8 +23,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
 
@@ -112,6 +115,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:
@@ -137,8 +142,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
@@ -149,11 +152,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:
@@ -250,15 +251,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 → fastapi_voyager-0.11.11}/src/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-0.11.10 → fastapi_voyager-0.11.11}/src/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-0.11.10 → fastapi_voyager-0.11.11}/src/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-0.11.10 → fastapi_voyager-0.11.11}/src/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-0.11.10 → fastapi_voyager-0.11.11}/src/fastapi_voyager/version.py

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

{fastapi_voyager-0.11.10 → fastapi_voyager-0.11.11}/tests/programatic.py

@@ -5,8 +5,8 @@ app.mount(
     '/voyager', 
     create_voyager(
         app, 
-        module_color={"tests.service": "purple"}, 
+        module_color={"tests.service": "purple", "tests.demo": "#ccaa00", "tests": "green"}, 
         module_prefix="tests.service", 
         swagger_url="/docs",
-        initial_page_policy='first',
+        initial_page_policy='full',
         online_repo_url="https://github.com/allmonday/fastapi-voyager/blob/main"))

{fastapi_voyager-0.11.10 → fastapi_voyager-0.11.11}/tests/service/schema.py

@@ -1,6 +1,5 @@
-from fastapi_voyager.voyager import Voyager
 from pydantic import BaseModel
-from pydantic_resolve import ensure_subset
+from typing import Literal, Dict
 
 class Sprint(BaseModel):
     id: int
@@ -8,6 +7,8 @@ class Sprint(BaseModel):
 
 class Story(BaseModel):
     id: int
+    type: Literal['feature', 'bugfix']
+    dct: Dict
     sprint_id: int
     title: str
     description: str