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

fastapi_voyager-0.12.1/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: fastapi-voyager
+Version: 0.12.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
+Author-email: Tangkikodo <allmonday@126.com>
+License: MIT
+License-File: LICENSE
+Keywords: fastapi,openapi,routing,visualization
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic-resolve>=1.13.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: uvicorn; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![pypi](https://img.shields.io/pypi/v/fastapi-voyager.svg)](https://pypi.python.org/pypi/fastapi-voyager)
+![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-voyager)
+[![PyPI Downloads](https://static.pepy.tech/badge/fastapi-voyager/month)](https://pepy.tech/projects/fastapi-voyager)
+
+
+> This repo is still in early stage, it supports pydantic v2 only
+
+Visualize your FastAPI endpoints, and explore them interactively.
+
+[visit online demo](https://www.newsyeah.fun/voyager/) of project: [composition oriented development pattern](https://github.com/allmonday/composition-oriented-development-pattern)
+
+<img width="1600" height="986" alt="image" src="https://github.com/user-attachments/assets/8829cda0-f42d-4c84-be2f-b019bb5fe7e1" />
+
+## Installation
+
+```bash
+pip install fastapi-voyager
+# or
+uv add fastapi-voyager
+```
+
+```shell
+voyager -m path.to.your.app.module --server
+```
+
+> [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
+
+```python
+from fastapi import FastAPI
+from fastapi_voyager import create_voyager
+from tests.demo import app
+
+app.mount('/voyager', create_voyager(
+    app, 
+    module_color={"tests.service": "red"}, 
+    module_prefix="tests.service"),
+    swagger_url="/docs")
+```
+
+## Features
+
+For scenarios of using FastAPI as internal API integration endpoints, `fastapi-voyager` helps to visualize the dependencies.
+
+It is also an architecture inspection tool that can identify issues in data relationships during design phase before turly implemtatioin.
+
+If the process of building the view model follows the ER model, the full potential of fastapi-voyager can be realized. It allows for quick identification of APIs  that use entities, as well as which entities are used by a specific API
+
+### highlight nodes and links
+click a node to highlight it's upperstream and downstream nodes. figure out the related models of one page, or homw many pages are related with one model.
+
+
+<img width="1100" height="700" alt="image" src="https://github.com/user-attachments/assets/3e0369ea-5fa4-469a-82c1-ed57d407e53d" />
+
+### focus on nodes
+
+Double click a node, and then toggle focus to hide irrelevant nodes.
+
+<img width="1061" height="937" alt="image" src="https://github.com/user-attachments/assets/79709b02-7571-43fc-abc9-17a287a97515" />
+
+### view source code
+
+double click a node or route to show source code or open file in vscode.
+
+<img width="1297" height="940" alt="image" src="https://github.com/user-attachments/assets/c8bb2e7d-b727-42a6-8c9e-64dce297d2d8" />
+
+<img width="1132" height="824" alt="image" src="https://github.com/user-attachments/assets/b706e879-e4fc-48dd-ace1-99bf97e3ed6a" />
+
+
+## Command Line Usage
+
+### open in browser
+
+```bash
+# open in browser
+voyager -m tests.demo --server  
+
+voyager -m tests.demo --server --port=8002
+```
+
+### generate the dot file
+```bash
+# generate .dot file
+voyager -m tests.demo  
+
+voyager -m tests.demo --app my_app
+
+voyager -m tests.demo --schema Task
+
+voyager -m tests.demo --show_fields all
+
+voyager -m tests.demo --module_color=tests.demo:red --module_color=tests.service:tomato
+
+voyager -m tests.demo -o my_visualization.dot
+
+voyager --version
+
+voyager --help
+```
+
+## About pydantic-resolve
+
+pydantic-resolve's `@ensure_subset` decorator helps safely pick fields from the 'source class' while **indicating the reference** from the current class to the base class.
+
+pydantic-resolve is a lightweight tool designed to build complex, nested data in a simple, declarative way. In version 2.0.0alpha, it will introduce an important feature: ER Diagram, and fastapi-voyager will support this feature, allowing for a clearer understanding of the business relationships between the data.
+
+Developers can use fastapi-voyager without needing to know anything about pydantic-resolve, but I still highly recommend everyone to give it a try.
+
+## Dependencies
+
+- FastAPI
+- [pydantic-resolve](https://github.com/allmonday/pydantic-resolve)
+- Quasar
+
+
+## Credits
+
+- https://apis.guru/graphql-voyager/, thanks for inspiration.
+- https://github.com/tintinweb/vscode-interactive-graphviz, thanks for web visualization.
+
+
+## How to develop & contribute?
+
+fork, clone.
+
+install uv.
+
+```shell
+uv venv
+source .venv/bin/activate
+uv pip install ".[dev]"
+uvicorn tests.programatic:app  --reload
+```
+
+open `localhost:8000/voyager`
+
+
+frontend: 
+- `src/web/vue-main.js`: main js
+
+backend: 
+- `voyager.py`: main entry
+- `render.py`: generate dot file
+- `server.py`: serve mode
+
+
+## Plan & Raodmap
+- [ideas](./docs/idea.md)
+- [changelog & roadmap](./docs/changelog.md)

fastapi_voyager-0.12.1/README.md

@@ -0,0 +1,154 @@
+[![pypi](https://img.shields.io/pypi/v/fastapi-voyager.svg)](https://pypi.python.org/pypi/fastapi-voyager)
+![Python Versions](https://img.shields.io/pypi/pyversions/fastapi-voyager)
+[![PyPI Downloads](https://static.pepy.tech/badge/fastapi-voyager/month)](https://pepy.tech/projects/fastapi-voyager)
+
+
+> This repo is still in early stage, it supports pydantic v2 only
+
+Visualize your FastAPI endpoints, and explore them interactively.
+
+[visit online demo](https://www.newsyeah.fun/voyager/) of project: [composition oriented development pattern](https://github.com/allmonday/composition-oriented-development-pattern)
+
+<img width="1600" height="986" alt="image" src="https://github.com/user-attachments/assets/8829cda0-f42d-4c84-be2f-b019bb5fe7e1" />
+
+## Installation
+
+```bash
+pip install fastapi-voyager
+# or
+uv add fastapi-voyager
+```
+
+```shell
+voyager -m path.to.your.app.module --server
+```
+
+> [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
+
+```python
+from fastapi import FastAPI
+from fastapi_voyager import create_voyager
+from tests.demo import app
+
+app.mount('/voyager', create_voyager(
+    app, 
+    module_color={"tests.service": "red"}, 
+    module_prefix="tests.service"),
+    swagger_url="/docs")
+```
+
+## Features
+
+For scenarios of using FastAPI as internal API integration endpoints, `fastapi-voyager` helps to visualize the dependencies.
+
+It is also an architecture inspection tool that can identify issues in data relationships during design phase before turly implemtatioin.
+
+If the process of building the view model follows the ER model, the full potential of fastapi-voyager can be realized. It allows for quick identification of APIs  that use entities, as well as which entities are used by a specific API
+
+### highlight nodes and links
+click a node to highlight it's upperstream and downstream nodes. figure out the related models of one page, or homw many pages are related with one model.
+
+
+<img width="1100" height="700" alt="image" src="https://github.com/user-attachments/assets/3e0369ea-5fa4-469a-82c1-ed57d407e53d" />
+
+### focus on nodes
+
+Double click a node, and then toggle focus to hide irrelevant nodes.
+
+<img width="1061" height="937" alt="image" src="https://github.com/user-attachments/assets/79709b02-7571-43fc-abc9-17a287a97515" />
+
+### view source code
+
+double click a node or route to show source code or open file in vscode.
+
+<img width="1297" height="940" alt="image" src="https://github.com/user-attachments/assets/c8bb2e7d-b727-42a6-8c9e-64dce297d2d8" />
+
+<img width="1132" height="824" alt="image" src="https://github.com/user-attachments/assets/b706e879-e4fc-48dd-ace1-99bf97e3ed6a" />
+
+
+## Command Line Usage
+
+### open in browser
+
+```bash
+# open in browser
+voyager -m tests.demo --server  
+
+voyager -m tests.demo --server --port=8002
+```
+
+### generate the dot file
+```bash
+# generate .dot file
+voyager -m tests.demo  
+
+voyager -m tests.demo --app my_app
+
+voyager -m tests.demo --schema Task
+
+voyager -m tests.demo --show_fields all
+
+voyager -m tests.demo --module_color=tests.demo:red --module_color=tests.service:tomato
+
+voyager -m tests.demo -o my_visualization.dot
+
+voyager --version
+
+voyager --help
+```
+
+## About pydantic-resolve
+
+pydantic-resolve's `@ensure_subset` decorator helps safely pick fields from the 'source class' while **indicating the reference** from the current class to the base class.
+
+pydantic-resolve is a lightweight tool designed to build complex, nested data in a simple, declarative way. In version 2.0.0alpha, it will introduce an important feature: ER Diagram, and fastapi-voyager will support this feature, allowing for a clearer understanding of the business relationships between the data.
+
+Developers can use fastapi-voyager without needing to know anything about pydantic-resolve, but I still highly recommend everyone to give it a try.
+
+## Dependencies
+
+- FastAPI
+- [pydantic-resolve](https://github.com/allmonday/pydantic-resolve)
+- Quasar
+
+
+## Credits
+
+- https://apis.guru/graphql-voyager/, thanks for inspiration.
+- https://github.com/tintinweb/vscode-interactive-graphviz, thanks for web visualization.
+
+
+## How to develop & contribute?
+
+fork, clone.
+
+install uv.
+
+```shell
+uv venv
+source .venv/bin/activate
+uv pip install ".[dev]"
+uvicorn tests.programatic:app  --reload
+```
+
+open `localhost:8000/voyager`
+
+
+frontend: 
+- `src/web/vue-main.js`: main js
+
+backend: 
+- `voyager.py`: main entry
+- `render.py`: generate dot file
+- `server.py`: serve mode
+
+
+## Plan & Raodmap
+- [ideas](./docs/idea.md)
+- [changelog & roadmap](./docs/changelog.md)

fastapi_voyager-0.12.1/docs/changelog.md

@@ -0,0 +1,122 @@
+# Changelog & roadmap
+
+## <0.9:
+- [x] group schemas by module hierarchy
+- [x] module-based coloring via Analytics(module_color={...})
+- [x] view in web browser
+    - [x] config params
+    - [x] make a explorer dashboard, provide list of routes, schemas, to make it easy to switch and search
+- [x] support programmatic usage
+- [x] better schema /router node appearance
+- [x] hide fields duplicated with parent's (show `parent fields` instead)
+- [x] refactor the frontend to vue, and tweak the build process
+- [x] find dependency based on picked schema and it's field.
+- [x] optimize static resource (cdn -> local)
+- [x] add configuration for highlight (optional)
+- [x] alt+click to show field details
+- [x] display source code of routes (including response_model)
+- [x] handle excluded field 
+- [x] add tooltips
+- [x] route
+    - [x] group routes by module hierarchy
+    - [x] add response_model in route
+- [x] fixed left bar show tag/ route
+- [x] export voyager core data into json (for better debugging)
+    - [x] add api to rebuild core data from json, and render it
+- [x] fix Generic case  `test_generic.py`
+- [x] show tips for routes not return pydantic type.
+- [x] fix duplicated link from class and parent class, it also break clicking highlight
+- [x] refactor: abstract render module
+
+## 0.9
+- [x] refactor: server.py
+    - [x] rename create_app_with_fastapi -> create_voyager
+    - [x] add doc for parameters
+- [x] improve initialization time cost
+    - [x] query route / schema info through realtime api
+    - [x] adjust fe
+- 0.9.3
+    - [x] adjust layout 
+        - [x] show field detail in right panel
+        - [x] show route info in bottom
+- 0.9.4
+    - [x] close schema sidebar when switch tag/route
+    - [x] schema detail panel show fields by default
+    - [x] adjust schema panel's height
+    - [x] show from base information in subset case
+- 0.9.5
+    - [x] route list should have a max height 
+
+## 0.10
+- 0.10.1
+    - [x] refactor voyager.py tag -> route structure
+    - [x] fix missing route (tag has only one route which return primitive value)
+    - [x] make right panel resizable by dragging
+    - [x] allow closing tag expansion item
+    - [x] hide brief mode if not configured
+    - [x] add focus button to only show related nodes under current route/tag graph in dialog
+- 0.10.2
+    - [x] fix graph height
+    - [x] show version in title
+- 0.10.3
+    - [x] fix focus in brief-mode
+    - [x] ui: adjust focus position
+    - [x] refactor naming
+    - [x] fix layout issue when rendering huge graph
+- 0.10.4
+    - [x] fix: when focus is on, should ensure changes from other params not broken.
+- 0.10.5
+    - [x] double click to show details, and highlight as tomato
+    
+
+## 0.11
+- 0.11.1
+    - [x] support opening route in swagger
+        - [x] config docs path
+    - [x] provide option to hide routes in brief mode (auto hide in full graph mode)
+- 0.11.2
+    - [x] enable/disable module cluster  (to save space)
+- 0.11.3
+    - [x] support online repo url
+- 0.11.4
+    - [x] add loading for field detail panel
+- 0.11.5
+    - [x] optimize open in swagger link
+    - [x] change jquery cdn
+- 0.11.6
+    - [x] flag of loading full graph in first render or not
+    - [x] optimize loading static resource 
+- 0.11.7
+    - [x] fix swagger link
+- 0.11.8
+    - [x] fix swagger link in another way
+- 0.11.9
+    - [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
+    - [x] sort tag / route names in left panel
+    - [x] display schema name on top of detail panel
+    - [x] optimize dbclick style
+    - [x] persist the tag/ route in url
+- 0.12.2
+    - [ ] search tag/ route
+    - [ ] refactor render.py
+    - [ ] reorg: move variable into reactive in vue-main.js
+
+## 0.13
+- 0.12.0
+    - [ ] integration with pydantic-resolve
+        - [ ] show hint for resolve, post fields
+        - [ ] display loader as edges
+    - [ ] add tests
+
+## 0.13
+todo
+

fastapi_voyager-0.12.1/docs/idea.md

@@ -0,0 +1,22 @@
+# Idea
+
+## backlog
+- [ ] user can generate nodes/edges manually and connect to generated ones
+    - [ ] eg: add owner
+    - [ ] add extra info for schema
+- [ ] optimize static resource (allow manually config url)
+- [ ] improve search dialog
+    - [ ] add route/tag list
+- [ ] type alias should not be kept as node instead of compiling to original type
+- [ ] how to correctly handle the generic type ?
+- [ ] support Google analysis config
+- [ ] sort field name in nodes (only table inside right panel), pending
+- [ ] set max limit for fields in nodes
+
+## in analysis
+- [ ] upgrade network algorithm (optional)
+- [ ] click field to highlight links
+- [ ] animation effect for edges
+- [ ] display standard ER diagram spec. `hard but important`
+    - [ ] display potential invalid links
+    - [ ] highlight relationship belongs to ER diagram

{fastapi_voyager-0.11.10 → fastapi_voyager-0.12.1}/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.12.1}/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: