fastapi-voyager 0.15.3__tar.gz → 0.15.5__tar.gz

fastapi_voyager-0.15.5/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: fastapi-voyager
+Version: 0.15.5
+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.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: jinja2>=3.0.0
+Requires-Dist: pydantic-resolve>=2.4.3
+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)
+
+
+# FastAPI Voyager
+
+Visualize your FastAPI endpoints and explore them interactively.
+
+Its vision is to make code easier to read and understand, serving as an ideal documentation tool.
+
+> This repo is still in early stage, it supports Pydantic v2 only.
+
+- **Live Demo**: https://www.newsyeah.fun/voyager/
+- **Example Source**: [composition-oriented-development-pattern](https://github.com/allmonday/composition-oriented-development-pattern)
+
+<img width="1597" height="933" alt="fastapi-voyager overview" src="https://github.com/user-attachments/assets/020bf5b2-6c69-44bf-ba1f-39389d388d27" />
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Features](#features)
+- [Command Line Usage](#command-line-usage)
+- [About pydantic-resolve](#about-pydantic-resolve)
+- [Development](#development)
+- [Dependencies](#dependencies)
+- [Credits](#credits)
+
+## Quick Start
+
+With simple configuration, fastapi-voyager can be embedded into FastAPI:
+
+```python
+from fastapi import FastAPI
+from fastapi_voyager import create_voyager
+
+app = FastAPI()
+
+app.mount('/voyager',
+          create_voyager(
+            app,
+            module_color={'src.services': 'tomato'},
+            module_prefix='src.services',
+            swagger_url="/docs",
+            ga_id="G-XXXXXXXXVL",
+            initial_page_policy='first',
+            online_repo_url='https://github.com/allmonday/composition-oriented-development-pattern/blob/master',
+            enable_pydantic_resolve_meta=True))
+```
+
+Visit `http://localhost:8000/voyager` to explore your API visually.
+
+[View full example](https://github.com/allmonday/composition-oriented-development-pattern/blob/master/src/main.py#L48)
+
+## Installation
+
+### Install via pip
+
+```bash
+pip install fastapi-voyager
+```
+
+### Install via uv
+
+```bash
+uv add fastapi-voyager
+```
+
+### Run with CLI
+
+```bash
+voyager -m path.to.your.app.module --server
+```
+
+For sub-application scenarios (e.g., `app.mount("/api", api)`), specify the app name:
+
+```bash
+voyager -m path.to.your.app.module --server --app api
+```
+
+> **Note**: [Sub-Application mounts](https://fastapi.tiangolo.com/advanced/sub-applications/) are not supported yet, but you can specify the name of the FastAPI application with `--app`. Only a single application (default: `app`) can be selected.
+
+## Features
+
+fastapi-voyager is designed for scenarios using FastAPI as internal API integration endpoints. It helps visualize dependencies and serves as an architecture tool to identify implementation issues such as wrong relationships, overfetching, and more.
+
+**Best Practice**: When building view models following the ER model pattern, fastapi-voyager can fully realize its potential - quickly identifying which APIs use specific entities and vice versa.
+
+### Highlight Nodes and Links
+
+Click a node to highlight its upstream and downstream nodes. Figure out the related models of one page, or how many pages are related with one model.
+
+<img width="1100" height="700" alt="highlight nodes and dependencies" src="https://github.com/user-attachments/assets/3e0369ea-5fa4-469a-82c1-ed57d407e53d" />
+
+### View Source Code
+
+Double-click a node or route to show source code or open the file in VSCode.
+
+<img width="1297" height="940" alt="view source code" src="https://github.com/user-attachments/assets/c8bb2e7d-b727-42a6-8c9e-64dce297d2d8" />
+
+### Quick Search
+
+Search schemas by name and display their upstream and downstream dependencies. Use `Shift + Click` on any node to quickly search for it.
+
+<img width="1587" height="873" alt="quick search functionality" src="https://github.com/user-attachments/assets/ee4716f3-233d-418f-bc0e-3b214d1498f7" />
+
+### Display ER Diagram
+
+ER diagram is a feature from pydantic-resolve which provides a solid expression for business descriptions. You can visualize application-level entity relationship diagrams.
+
+```python
+from pydantic_resolve import ErDiagram, Entity, Relationship
+
+diagram = ErDiagram(
+    configs=[
+        Entity(
+            kls=Team,
+            relationships=[
+                Relationship(field='id', target_kls=list[Sprint], loader=sprint_loader.team_to_sprint_loader),
+                Relationship(field='id', target_kls=list[User], loader=user_loader.team_to_user_loader)
+            ]
+        ),
+        Entity(
+            kls=Sprint,
+            relationships=[
+                Relationship(field='id', target_kls=list[Story], loader=story_loader.sprint_to_story_loader)
+            ]
+        ),
+        Entity(
+            kls=Story,
+            relationships=[
+                Relationship(field='id', target_kls=list[Task], loader=task_loader.story_to_task_loader),
+                Relationship(field='owner_id', target_kls=User, loader=user_loader.user_batch_loader)
+            ]
+        ),
+        Entity(
+            kls=Task,
+            relationships=[
+                Relationship(field='owner_id', target_kls=User, loader=user_loader.user_batch_loader)
+            ]
+        )
+    ]
+)
+
+# Display in voyager
+app.mount('/voyager',
+          create_voyager(
+            app,
+            er_diagram=diagram
+          ))
+```
+
+<img width="1276" height="613" alt="ER diagram visualization" src="https://github.com/user-attachments/assets/ea0091bb-ee11-4f71-8be3-7129d956c910" />
+
+### Show Pydantic Resolve Meta Info
+
+Set `enable_pydantic_resolve_meta=True` in `create_voyager`, then toggle the "pydantic resolve meta" button to visualize resolve/post/expose/collect operations.
+
+<img width="1604" height="535" alt="pydantic resolve meta information" src="https://github.com/user-attachments/assets/d1639555-af41-4a08-9970-4b8ef314596a" />
+
+## Command Line Usage
+
+### Start Server
+
+```bash
+# Open in browser (default port 8000)
+voyager -m tests.demo --server
+
+# Custom port
+voyager -m tests.demo --server --port=8002
+
+# Specify app name
+voyager -m tests.demo --server --app my_app
+```
+
+### Generate DOT File
+
+```bash
+# Generate .dot file
+voyager -m tests.demo
+
+# Specify app
+voyager -m tests.demo --app my_app
+
+# Filter by schema
+voyager -m tests.demo --schema Task
+
+# Show all fields
+voyager -m tests.demo --show_fields all
+
+# Custom module colors
+voyager -m tests.demo --module_color=tests.demo:red --module_color=tests.service:tomato
+
+# Output to file
+voyager -m tests.demo -o my_visualization.dot
+
+# Version and help
+voyager --version
+voyager --help
+```
+
+## About pydantic-resolve
+
+pydantic-resolve is a lightweight tool designed to build complex, nested data in a simple, declarative way. In v2, it introduced an important feature: **ER Diagram**, and fastapi-voyager has supported this feature, allowing for a clearer understanding of business relationships.
+
+The ~~`@ensure_subset` decorator~~ `DefineSubset` metaclass helps safely pick fields from the 'source class' while **indicating the reference** from the current class to the base class.
+
+Developers can use fastapi-voyager without needing to know anything about pydantic-resolve, but I still highly recommend everyone to give it a try.
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Fork and clone the repository
+git clone https://github.com/your-username/fastapi-voyager.git
+cd fastapi-voyager
+
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv venv
+source .venv/bin/activate
+uv pip install ".[dev]"
+
+# Run development server
+uvicorn tests.programatic:app --reload
+```
+
+Visit `http://localhost:8000/voyager` to see changes.
+
+### Setup Git Hooks (Optional)
+
+Enable automatic code formatting before commits:
+
+```bash
+./setup-hooks.sh
+# or manually:
+git config core.hooksPath .githooks
+```
+
+This will run Prettier automatically before each commit. See [`.githooks/README.md`](./.githooks/README.md) for details.
+
+### Project Structure
+
+**Frontend:**
+- `src/fastapi_voyager/web/vue-main.js` - Main JavaScript entry
+
+**Backend:**
+- `voyager.py` - Main entry point
+- `render.py` - Generate DOT files
+- `server.py` - Server mode
+
+## Roadmap
+
+- [Ideas](./docs/idea.md)
+- [Changelog & Roadmap](./docs/changelog.md)
+
+## Dependencies
+
+- [FastAPI](https://fastapi.tiangolo.com/)
+- [pydantic-resolve](https://github.com/allmonday/pydantic-resolve)
+- [Quasar Framework](https://quasar.dev/)
+
+## Credits
+
+- [graphql-voyager](https://apis.guru/graphql-voyager/) - Thanks for inspiration
+- [vscode-interactive-graphviz](https://github.com/tintinweb/vscode-interactive-graphviz) - Thanks for web visualization
+
+## License
+
+MIT License

fastapi_voyager-0.15.5/README.md

@@ -0,0 +1,274 @@
+[![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)
+
+
+# FastAPI Voyager
+
+Visualize your FastAPI endpoints and explore them interactively.
+
+Its vision is to make code easier to read and understand, serving as an ideal documentation tool.
+
+> This repo is still in early stage, it supports Pydantic v2 only.
+
+- **Live Demo**: https://www.newsyeah.fun/voyager/
+- **Example Source**: [composition-oriented-development-pattern](https://github.com/allmonday/composition-oriented-development-pattern)
+
+<img width="1597" height="933" alt="fastapi-voyager overview" src="https://github.com/user-attachments/assets/020bf5b2-6c69-44bf-ba1f-39389d388d27" />
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Features](#features)
+- [Command Line Usage](#command-line-usage)
+- [About pydantic-resolve](#about-pydantic-resolve)
+- [Development](#development)
+- [Dependencies](#dependencies)
+- [Credits](#credits)
+
+## Quick Start
+
+With simple configuration, fastapi-voyager can be embedded into FastAPI:
+
+```python
+from fastapi import FastAPI
+from fastapi_voyager import create_voyager
+
+app = FastAPI()
+
+app.mount('/voyager',
+          create_voyager(
+            app,
+            module_color={'src.services': 'tomato'},
+            module_prefix='src.services',
+            swagger_url="/docs",
+            ga_id="G-XXXXXXXXVL",
+            initial_page_policy='first',
+            online_repo_url='https://github.com/allmonday/composition-oriented-development-pattern/blob/master',
+            enable_pydantic_resolve_meta=True))
+```
+
+Visit `http://localhost:8000/voyager` to explore your API visually.
+
+[View full example](https://github.com/allmonday/composition-oriented-development-pattern/blob/master/src/main.py#L48)
+
+## Installation
+
+### Install via pip
+
+```bash
+pip install fastapi-voyager
+```
+
+### Install via uv
+
+```bash
+uv add fastapi-voyager
+```
+
+### Run with CLI
+
+```bash
+voyager -m path.to.your.app.module --server
+```
+
+For sub-application scenarios (e.g., `app.mount("/api", api)`), specify the app name:
+
+```bash
+voyager -m path.to.your.app.module --server --app api
+```
+
+> **Note**: [Sub-Application mounts](https://fastapi.tiangolo.com/advanced/sub-applications/) are not supported yet, but you can specify the name of the FastAPI application with `--app`. Only a single application (default: `app`) can be selected.
+
+## Features
+
+fastapi-voyager is designed for scenarios using FastAPI as internal API integration endpoints. It helps visualize dependencies and serves as an architecture tool to identify implementation issues such as wrong relationships, overfetching, and more.
+
+**Best Practice**: When building view models following the ER model pattern, fastapi-voyager can fully realize its potential - quickly identifying which APIs use specific entities and vice versa.
+
+### Highlight Nodes and Links
+
+Click a node to highlight its upstream and downstream nodes. Figure out the related models of one page, or how many pages are related with one model.
+
+<img width="1100" height="700" alt="highlight nodes and dependencies" src="https://github.com/user-attachments/assets/3e0369ea-5fa4-469a-82c1-ed57d407e53d" />
+
+### View Source Code
+
+Double-click a node or route to show source code or open the file in VSCode.
+
+<img width="1297" height="940" alt="view source code" src="https://github.com/user-attachments/assets/c8bb2e7d-b727-42a6-8c9e-64dce297d2d8" />
+
+### Quick Search
+
+Search schemas by name and display their upstream and downstream dependencies. Use `Shift + Click` on any node to quickly search for it.
+
+<img width="1587" height="873" alt="quick search functionality" src="https://github.com/user-attachments/assets/ee4716f3-233d-418f-bc0e-3b214d1498f7" />
+
+### Display ER Diagram
+
+ER diagram is a feature from pydantic-resolve which provides a solid expression for business descriptions. You can visualize application-level entity relationship diagrams.
+
+```python
+from pydantic_resolve import ErDiagram, Entity, Relationship
+
+diagram = ErDiagram(
+    configs=[
+        Entity(
+            kls=Team,
+            relationships=[
+                Relationship(field='id', target_kls=list[Sprint], loader=sprint_loader.team_to_sprint_loader),
+                Relationship(field='id', target_kls=list[User], loader=user_loader.team_to_user_loader)
+            ]
+        ),
+        Entity(
+            kls=Sprint,
+            relationships=[
+                Relationship(field='id', target_kls=list[Story], loader=story_loader.sprint_to_story_loader)
+            ]
+        ),
+        Entity(
+            kls=Story,
+            relationships=[
+                Relationship(field='id', target_kls=list[Task], loader=task_loader.story_to_task_loader),
+                Relationship(field='owner_id', target_kls=User, loader=user_loader.user_batch_loader)
+            ]
+        ),
+        Entity(
+            kls=Task,
+            relationships=[
+                Relationship(field='owner_id', target_kls=User, loader=user_loader.user_batch_loader)
+            ]
+        )
+    ]
+)
+
+# Display in voyager
+app.mount('/voyager',
+          create_voyager(
+            app,
+            er_diagram=diagram
+          ))
+```
+
+<img width="1276" height="613" alt="ER diagram visualization" src="https://github.com/user-attachments/assets/ea0091bb-ee11-4f71-8be3-7129d956c910" />
+
+### Show Pydantic Resolve Meta Info
+
+Set `enable_pydantic_resolve_meta=True` in `create_voyager`, then toggle the "pydantic resolve meta" button to visualize resolve/post/expose/collect operations.
+
+<img width="1604" height="535" alt="pydantic resolve meta information" src="https://github.com/user-attachments/assets/d1639555-af41-4a08-9970-4b8ef314596a" />
+
+## Command Line Usage
+
+### Start Server
+
+```bash
+# Open in browser (default port 8000)
+voyager -m tests.demo --server
+
+# Custom port
+voyager -m tests.demo --server --port=8002
+
+# Specify app name
+voyager -m tests.demo --server --app my_app
+```
+
+### Generate DOT File
+
+```bash
+# Generate .dot file
+voyager -m tests.demo
+
+# Specify app
+voyager -m tests.demo --app my_app
+
+# Filter by schema
+voyager -m tests.demo --schema Task
+
+# Show all fields
+voyager -m tests.demo --show_fields all
+
+# Custom module colors
+voyager -m tests.demo --module_color=tests.demo:red --module_color=tests.service:tomato
+
+# Output to file
+voyager -m tests.demo -o my_visualization.dot
+
+# Version and help
+voyager --version
+voyager --help
+```
+
+## About pydantic-resolve
+
+pydantic-resolve is a lightweight tool designed to build complex, nested data in a simple, declarative way. In v2, it introduced an important feature: **ER Diagram**, and fastapi-voyager has supported this feature, allowing for a clearer understanding of business relationships.
+
+The ~~`@ensure_subset` decorator~~ `DefineSubset` metaclass helps safely pick fields from the 'source class' while **indicating the reference** from the current class to the base class.
+
+Developers can use fastapi-voyager without needing to know anything about pydantic-resolve, but I still highly recommend everyone to give it a try.
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Fork and clone the repository
+git clone https://github.com/your-username/fastapi-voyager.git
+cd fastapi-voyager
+
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv venv
+source .venv/bin/activate
+uv pip install ".[dev]"
+
+# Run development server
+uvicorn tests.programatic:app --reload
+```
+
+Visit `http://localhost:8000/voyager` to see changes.
+
+### Setup Git Hooks (Optional)
+
+Enable automatic code formatting before commits:
+
+```bash
+./setup-hooks.sh
+# or manually:
+git config core.hooksPath .githooks
+```
+
+This will run Prettier automatically before each commit. See [`.githooks/README.md`](./.githooks/README.md) for details.
+
+### Project Structure
+
+**Frontend:**
+- `src/fastapi_voyager/web/vue-main.js` - Main JavaScript entry
+
+**Backend:**
+- `voyager.py` - Main entry point
+- `render.py` - Generate DOT files
+- `server.py` - Server mode
+
+## Roadmap
+
+- [Ideas](./docs/idea.md)
+- [Changelog & Roadmap](./docs/changelog.md)
+
+## Dependencies
+
+- [FastAPI](https://fastapi.tiangolo.com/)
+- [pydantic-resolve](https://github.com/allmonday/pydantic-resolve)
+- [Quasar Framework](https://quasar.dev/)
+
+## Credits
+
+- [graphql-voyager](https://apis.guru/graphql-voyager/) - Thanks for inspiration
+- [vscode-interactive-graphviz](https://github.com/tintinweb/vscode-interactive-graphviz) - Thanks for web visualization
+
+## License
+
+MIT License

{fastapi_voyager-0.15.3 → fastapi_voyager-0.15.5}/docs/changelog.md

@@ -167,8 +167,19 @@
     - [x] refactor vue-main.js, move methods to store
     - [x] optimize search flow
 - 0.15.4
-    - [ ] add tests
+    - [x] static files cache buster 
+    - [x] store voyager/erd toggle value in url query string
+    - [x] set highlight style
+- 0.15.5
+    - [x] fix loadInitial bug
+
+## 0.16, enhance er diagram
+- 0.16.0
+    - [ ] show loader name
+    - [ ] show relationship list when double click entity in er diagram
+    - [ ] highlight entity in use case
 
 ## 1.0, release 
+    - [ ] add tests
 
 

{fastapi_voyager-0.15.3 → fastapi_voyager-0.15.5}/src/fastapi_voyager/server.py

@@ -19,6 +19,7 @@ WEB_DIR = Path(__file__).parent / "web"
 WEB_DIR.mkdir(exist_ok=True)
 
 GA_PLACEHOLDER = "<!-- GA_SNIPPET -->"
+VERSION_PLACEHOLDER = "<!-- VERSION_PLACEHOLDER -->"
 
 def _build_ga_snippet(ga_id: str | None) -> str:
 	if not ga_id:
@@ -197,7 +198,9 @@ def create_voyager(
 		index_file = WEB_DIR / "index.html"
 		if index_file.exists():
 			content = index_file.read_text(encoding="utf-8")
-			return content.replace(GA_PLACEHOLDER, _build_ga_snippet(ga_id))
+			content = content.replace(GA_PLACEHOLDER, _build_ga_snippet(ga_id))
+			content = content.replace(VERSION_PLACEHOLDER, f"?v={__version__}")
+			return content
 		# fallback simple page if index.html missing
 		return """
 		<!doctype html>

{fastapi_voyager-0.15.3 → fastapi_voyager-0.15.5}/src/fastapi_voyager/version.py

@@ -1,2 +1,2 @@
 __all__ = ["__version__"]
-__version__ = "0.15.3"
+__version__ = "0.15.5"

{fastapi_voyager-0.15.3 → fastapi_voyager-0.15.5}/src/fastapi_voyager/web/graph-ui.js

@@ -69,10 +69,45 @@ export class GraphUI {
   }
 
   highlightSchemaBanner(node) {
+    // Get all polygons in the node
     const polygons = node.querySelectorAll("polygon")
-    const ele = polygons[2] // select the second polygon
-    if (ele) {
-      ele.setAttribute("stroke-width", "3.5")
+
+    // The first polygon is typically the outer frame of the entire node
+    const outerFrame = polygons[0]
+    // The second polygon is typically the title background
+    const titleBg = polygons[1]
+
+    if (outerFrame) {
+      // Save original attributes for potential restoration
+      if (!outerFrame.hasAttribute("data-original-stroke")) {
+        outerFrame.setAttribute("data-original-stroke", outerFrame.getAttribute("stroke") || "")
+        outerFrame.setAttribute(
+          "data-original-stroke-width",
+          outerFrame.getAttribute("stroke-width") || "1"
+        )
+        outerFrame.setAttribute("data-original-fill", outerFrame.getAttribute("fill") || "")
+      }
+
+      // Apply bold purple border to the outer frame
+      outerFrame.setAttribute("stroke", "#822dba")
+      outerFrame.setAttribute("stroke-width", "3.0")
+    }
+
+    if (titleBg) {
+      // Save original attributes
+      if (!titleBg.hasAttribute("data-original-stroke")) {
+        titleBg.setAttribute("data-original-stroke", titleBg.getAttribute("stroke") || "")
+        titleBg.setAttribute(
+          "data-original-stroke-width",
+          titleBg.getAttribute("stroke-width") || "1"
+        )
+        titleBg.setAttribute("data-original-fill", titleBg.getAttribute("fill") || "")
+      }
+
+      // Apply purple background to title
+      titleBg.setAttribute("fill", "#822dba")
+      // Also update the stroke to match
+      titleBg.setAttribute("stroke", "#822dba")
     }
   }