fastapi-voyager 0.12.12__tar.gz → 0.13.0__tar.gz

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-voyager
-Version: 0.12.12
+Version: 0.13.0
 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
@@ -19,7 +19,7 @@ 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
+Requires-Dist: pydantic-resolve>=2.2.3
 Provides-Extra: dev
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/docs/changelog.md

@@ -136,8 +136,8 @@
     - [x] disable `show module cluster` by default
 
 ## 0.13
-- 0.13.2
-    - [ ] if er diagram is provided, show it first.
+- 0.13.0
+    - [x] if er diagram is provided, show it first.
 - 0.13.1
     - [ ] integration with pydantic-resolve
         - [ ] show hint for resolve, post fields

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/pyproject.toml

@@ -9,7 +9,7 @@ requires-python = ">=3.10"
 keywords = ["fastapi", "visualization", "routing", "openapi"]
 dependencies = [
   "fastapi>=0.110",
-  "pydantic-resolve>=1.13.2"
+  "pydantic-resolve>=2.2.3"
 ]
 classifiers = [
   "Programming Language :: Python :: 3",

fastapi_voyager-0.13.0/src/fastapi_voyager/er_diagram.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from fastapi_voyager.type import PK, FieldType, Link, LinkType, SchemaNode
+from fastapi_voyager.type_helper import (
+    update_forward_refs,
+    full_class_name,
+    get_core_types,
+    get_type_name
+)
+from fastapi_voyager.render import Renderer
+from fastapi_voyager.type import FieldInfo
+from pydantic import BaseModel
+from pydantic_resolve import ErDiagram, Entity
+
+class VoyagerErDiagram:
+    def __init__(self, 
+                 er_diagram: ErDiagram, 
+                 show_fields: FieldType = 'single',
+                 show_module: bool = False):
+        self.er_diagram = er_diagram
+        self.nodes: list[SchemaNode] = []
+        self.node_set: dict[str, SchemaNode] = {}
+
+        self.links: list[Link] = []
+        self.link_set: set[tuple[str, str]] = set()
+
+        self.fk_set: dict[str, set[str]] = {}
+
+        self.show_field = show_fields
+        self.show_module = show_module
+    
+    def generate_node_head(self, link_name: str):
+        return f'{link_name}::{PK}'
+
+    def analysis_entity(self, entity: Entity):
+        schema = entity.kls
+        update_forward_refs(schema)
+        self.add_to_node_set(schema, fk_set=self.fk_set.get(full_class_name(schema)))
+
+        for relationship in entity.relationships:
+            annos = get_core_types(relationship.target_kls)
+            for anno in annos:
+                self.add_to_node_set(anno, fk_set=self.fk_set.get(full_class_name(anno)))
+                source_name = f'{full_class_name(schema)}::f{relationship.field}'
+                self.add_to_link_set(
+                    source=source_name,
+                    source_origin=full_class_name(schema),
+                    target=self.generate_node_head(full_class_name(anno)),
+                    target_origin=full_class_name(anno),
+                    type='schema')
+
+    def add_to_node_set(self, schema, fk_set: set[str] | None = None) -> str:
+        """
+        1. calc full_path, add to node_set
+        2. if duplicated, do nothing, else insert
+        2. return the full_path
+        """
+        full_name = full_class_name(schema)
+
+        if full_name not in self.node_set:
+            # skip meta info for normal queries
+            self.node_set[full_name] = SchemaNode(
+                id=full_name, 
+                module=schema.__module__,
+                name=schema.__name__,
+                fields=get_fields(schema, fk_set)
+            )
+        return full_name
+
+    def add_to_link_set(
+            self, 
+            source: str, 
+            source_origin: str,
+            target: str, 
+            target_origin: str,
+            type: LinkType
+        ) -> bool:
+        """
+        1. add link to link_set
+        2. if duplicated, do nothing, else insert
+        """
+        pair = (source, target)
+        if result := pair not in self.link_set:
+            self.link_set.add(pair)
+            self.links.append(Link(
+                source=source,
+                source_origin=source_origin,
+                target=target,
+                target_origin=target_origin,
+                type=type
+            ))
+        return result
+
+
+    def render_dot(self):
+        self.fk_set = {
+            full_class_name(entity.kls): set([rel.field for rel in entity.relationships])
+                for entity in self.er_diagram.configs
+        }
+
+        for entity in self.er_diagram.configs:
+            self.analysis_entity(entity)
+        renderer = Renderer(show_fields=self.show_field, show_module=self.show_module)
+        return renderer.render_dot([], [], list(self.node_set.values()), self.links)
+
+
+def get_fields(schema: type[BaseModel], fk_set: set[str] | None = None) -> list[FieldInfo]:
+
+    fields: list[FieldInfo] = []
+    for k, v in schema.model_fields.items():
+        anno = v.annotation
+        fields.append(FieldInfo(
+            is_object=k in fk_set if fk_set is not None else False,
+            name=k,
+            from_base=False,
+            type_name=get_type_name(anno),
+            is_exclude=bool(v.exclude)
+        ))
+    return fields

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/src/fastapi_voyager/server.py

@@ -12,6 +12,8 @@ from fastapi_voyager.type import CoreData, SchemaNode, Tag
 from fastapi_voyager.type_helper import get_source, get_vscode_link
 from fastapi_voyager.version import __version__
 from fastapi_voyager.voyager import Voyager
+from pydantic_resolve import ErDiagram
+from fastapi_voyager.er_diagram import VoyagerErDiagram
 
 WEB_DIR = Path(__file__).parent / "web"
 WEB_DIR.mkdir(exist_ok=True)
@@ -44,6 +46,7 @@ class OptionParam(BaseModel):
 	version: str
 	initial_page_policy: INITIAL_PAGE_POLICY
 	swagger_url: str | None = None
+	has_er_diagram: bool = False
 
 class Payload(BaseModel):
 	tags: list[str] | None = None
@@ -67,6 +70,12 @@ class SchemaSearchPayload(BaseModel):  # leave tag, route out
 	hide_primitive_route: bool = False
 	show_module: bool = True
 
+
+# ---------- er diagram ----------
+class ErDiagramPayload(BaseModel):
+	show_fields: str = 'object'
+	show_module: bool = True
+
 def create_voyager(
 	target_app: FastAPI,
 	module_color: dict[str, str] | None = None,
@@ -76,9 +85,19 @@ def create_voyager(
 	online_repo_url: str | None = None,
 	initial_page_policy: INITIAL_PAGE_POLICY = 'first',
 	ga_id: str | None = None,
+	er_diagram: ErDiagram | None = None,
 ) -> FastAPI:
 	router = APIRouter(tags=['fastapi-voyager'])
 
+	@router.post("/er-diagram", response_class=PlainTextResponse)
+	def get_er_diagram(payload: ErDiagramPayload) -> str:
+		if er_diagram:
+			return VoyagerErDiagram(
+				er_diagram,
+				show_fields=payload.show_fields,
+				show_module=payload.show_module ).render_dot()
+		return ''
+
 	@router.get("/dot", response_model=OptionParam)
 	def get_dot() -> str:
 		voyager = Voyager(module_color=module_color)
@@ -101,7 +120,9 @@ def create_voyager(
 			enable_brief_mode=bool(module_prefix),
 			version=__version__,
 			swagger_url=swagger_url,
-			initial_page_policy=initial_page_policy)
+			initial_page_policy=initial_page_policy,
+			has_er_diagram=er_diagram is not None)
+
 
 	@router.post("/dot-search", response_model=SearchResultOptionParam)
 	def get_search_dot(payload: SchemaSearchPayload):

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/src/fastapi_voyager/version.py

@@ -1,2 +1,2 @@
 __all__ = ["__version__"]
-__version__ = "0.12.12"
+__version__ = "0.13.0"

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/src/fastapi_voyager/voyager.py

@@ -62,11 +62,6 @@ class Voyager:
             if isinstance(route, routing.APIRoute):
                 yield route
 
-    def analysis_route(self, route: routing.APIRoute):
-        ...
-    
-    def analysis_tags(self, tag: str):
-        ...
 
     def analysis(self, app: FastAPI):
         """

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/src/fastapi_voyager/web/index.html

@@ -181,6 +181,18 @@
                 label="Select field (optional)"
               ></q-select>
             </div>
+            <div class="col-auto" v-if="store.state.config.has_er_diagram">
+              <q-btn-toggle
+                class="q-ml-lg"
+                v-model="store.state.mode"
+                push
+                toggle-color="primary"
+                :options="[
+                  {label: 'Voyager', value: 'voyager'},
+                  {label: 'ER diagram', value: 'er-diagram'},
+                ]"
+              />
+            </div>
             <div class="col-auto">
               <q-btn
                 dense
@@ -259,7 +271,7 @@
           <q-splitter
             v-model="store.state.leftPanel.width"
             unit="px"
-            :limits="[200, 800]"
+            :limits="store.state.mode === 'voyager' ? [200, 800] : [0, 0]"
             class="adjust-fit"
           >
             <template #before>
@@ -272,6 +284,7 @@
                 minHeight: 0,
                 height: '100%'
               }"
+                v-show="store.state.mode === 'voyager'"
               >
                 <q-scroll-area class="fit">
                   <q-list dense separator>
@@ -339,7 +352,7 @@
               <div style="position: relative; width: 100%; height: 100%;">
                 <div id="graph" class="adjust-fit"></div>
                 <div style="position: absolute; left: 8px; top: 8px; z-index: 10; background: rgba(255,255,255,0.85); border-radius: 4px; padding: 2px 8px;">
-                  <div class="q-mt-sm" v-if="store.state.modeControl.briefModeEnabled && store.state.search.mode === false">
+                  <div class="q-mt-sm" v-if="store.state.modeControl.briefModeEnabled && store.state.search.mode === false && store.state.mode === 'voyager'">
                     <q-toggle
                       v-if="store.state.modeControl.briefModeEnabled"
                       dense
@@ -349,7 +362,7 @@
                       title="skip middle classes, config module_prefix to enable it"
                     />
                   </div>
-                  <div class="q-mt-sm" v-if="store.state.modeControl.briefModeEnabled && store.state.search.mode === false">
+                  <div class="q-mt-sm" v-if="store.state.search.mode === false && store.state.mode === 'voyager'">
                     <q-toggle
                       v-model="store.state.filter.hidePrimitiveRoute"
                       @update:model-value="(val) => toggleHidePrimitiveRoute(val)"

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/src/fastapi_voyager/web/store.js

@@ -7,8 +7,11 @@ const state = reactive({
 
     version: '',
     config: {
-        initial_page_policy: 'first'
+        initial_page_policy: 'first',
+        has_er_diagram: false,
     },
+
+    mode: 'voyager', // voyager / er-diagram
     
     previousTagRoute: {  // for shift + click, store previous tag/route, and populate back when needed
         hasValue: false,
@@ -34,6 +37,7 @@ const state = reactive({
     // tags and routes
     leftPanel: {  
         width: 300,
+        previousWidth: 300,
         tags: null,
         tag: null,
         _tag: null,
@@ -98,6 +102,7 @@ const state = reactive({
 
 })
 
+
 const mutations = {
     increment() {
         state.item.count += 1

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/src/fastapi_voyager/web/vue-main.js

@@ -11,6 +11,40 @@ const app = createApp({
   setup() {
     let graphUI = null;
     const allSchemaOptions = ref([]);
+    const erDiagramLoading = ref(false);
+    const erDiagramCache = ref("");
+
+    function initGraphUI() {
+      if (graphUI) {
+        return;
+      }
+      graphUI = new GraphUI("#graph", {
+        onSchemaShiftClick: (id) => {
+          if (store.state.graph.schemaKeys.has(id)) {
+            store.state.previousTagRoute.tag = store.state.leftPanel.tag;
+            store.state.previousTagRoute.routeId = store.state.leftPanel.routeId;
+            store.state.previousTagRoute.hasValue = true;
+            store.state.search.mode = true;
+            store.state.search.schemaName = id;
+            onSearch();
+          }
+        },
+        onSchemaClick: (id) => {
+          resetDetailPanels();
+          if (store.state.graph.schemaKeys.has(id)) {
+            store.state.schemaDetail.schemaCodeName = id;
+            store.state.rightDrawer.drawer = true;
+          }
+          if (id in store.state.graph.routeItems) {
+            store.state.routeDetail.routeCodeId = id;
+            store.state.routeDetail.show = true;
+          }
+        },
+        resetCb: () => {
+          resetDetailPanels();
+        },
+      });
+    }
 
     function rebuildSchemaOptions() {
       const dict = store.state.graph.schemaMap || {};
@@ -209,6 +243,7 @@ const app = createApp({
           data.enable_brief_mode || false;
         store.state.version = data.version || "";
         store.state.swagger.url = data.swagger_url || null;
+        store.state.config.has_er_diagram = data.has_er_diagram || false;
 
         rebuildSchemaOptions();
 
@@ -251,6 +286,17 @@ const app = createApp({
     }
 
     async function onGenerate(resetZoom = true) {
+      switch (store.state.mode) {
+        case "voyager":
+          await renderVoyager(resetZoom);
+          break;
+        case "er-diagram":
+          await renderErDiagram(resetZoom);
+          break;
+      }
+    }
+
+    async function renderVoyager(resetZoom = true) {
       const activeSchema = store.state.search.mode
         ? store.state.search.schemaName
         : null;
@@ -269,6 +315,7 @@ const app = createApp({
           hide_primitive_route: store.state.filter.hidePrimitiveRoute,
           show_module: store.state.filter.showModule,
         };
+        initGraphUI();
         const res = await fetch("dot", {
           method: "POST",
           headers: { "Content-Type": "application/json" },
@@ -276,39 +323,6 @@ const app = createApp({
         });
         const dotText = await res.text();
 
-        // create graph instance once
-        if (!graphUI) {
-          graphUI = new GraphUI("#graph", {
-            onSchemaShiftClick: (id) => {
-              if (store.state.graph.schemaKeys.has(id)) {
-
-                console.log(store.state.leftPanel)
-                store.state.previousTagRoute.tag = store.state.leftPanel.tag;
-                store.state.previousTagRoute.routeId = store.state.leftPanel.routeId;
-                store.state.previousTagRoute.hasValue = true;
-
-                store.state.search.mode = true;
-                store.state.search.schemaName = id;
-                onSearch();
-              }
-            },
-            onSchemaClick: (id) => {
-              console.log("schema clicked:", id);
-              resetDetailPanels();
-              if (store.state.graph.schemaKeys.has(id)) {
-                store.state.schemaDetail.schemaCodeName = id;
-                store.state.rightDrawer.drawer = true;
-              }
-              if (id in store.state.graph.routeItems) {
-                store.state.routeDetail.routeCodeId = id;
-                store.state.routeDetail.show = true;
-              }
-            },
-            resetCb: () => {
-              resetDetailPanels();
-            },
-          });
-        }
         await graphUI.render(dotText, resetZoom);
       } catch (e) {
         console.error("Generate failed", e);
@@ -331,6 +345,46 @@ const app = createApp({
         onGenerate()
     }
 
+    async function renderErDiagram(resetZoom = true) {
+      initGraphUI();
+      erDiagramLoading.value = true;
+      const payload = {
+        show_fields: store.state.filter.showFields,
+        show_module: store.state.filter.showModule,
+      };
+      try {
+        const res = await fetch("er-diagram", { 
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(payload),
+         });
+        if (!res.ok) {
+          throw new Error(`failed with status ${res.status}`);
+        }
+        const dot = await res.text();
+        erDiagramCache.value = dot;
+        await graphUI.render(dot, resetZoom);
+      } catch (err) {
+        console.error(err)
+      } finally {
+        erDiagramLoading.value = false;
+      }
+    }
+
+    async function onModeChange(val) {
+      if (val === "er-diagram") {
+        if (store.state.leftPanel.width > 0) {
+          store.state.leftPanel.previousWidth = store.state.leftPanel.width;
+        }
+        store.state.leftPanel.width = 0;
+        await renderErDiagram();
+      } else {
+        const fallbackWidth = store.state.leftPanel.previousWidth || 300;
+        store.state.leftPanel.width = fallbackWidth;
+        await onGenerate();
+      }
+    }
+
     function toggleTag(tagName, expanded = null) {
       if (expanded === true || store.state.search.mode === true) {
         store.state.leftPanel._tag = tagName;
@@ -421,6 +475,22 @@ const app = createApp({
       { deep: false }
     );
 
+    watch(
+      () => store.state.leftPanel.width,
+      (val) => {
+        if (store.state.mode === "voyager" && typeof val === "number" && val > 0) {
+          store.state.leftPanel.previousWidth = val;
+        }
+      }
+    );
+
+    watch(
+      () => store.state.mode,
+      (mode) => {
+        onModeChange(mode);
+      }
+    );
+
     watch(
       () => store.state.search.schemaName,
       (schemaId) => {
@@ -453,6 +523,8 @@ const app = createApp({
       toggleShowField,
       startDragDrawer,
       toggleShowModule,
+      onModeChange,
+      renderErDiagram,
     };
   },
 });

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/tests/demo.py

@@ -5,8 +5,12 @@ from fastapi import FastAPI
 from pydantic import BaseModel, Field
 from pydantic_resolve import Resolver, ensure_subset
 
+
 from tests.service.schema.schema import Member, Sprint, Story, Task
-from tests.service.schema.extra import A, B 
+from tests.service.schema.extra import A
+from tests.service.schema.base_entity import BaseEntity
+
+diagram = BaseEntity.get_diagram()
 
 app = FastAPI(title="Demo API", description="A demo FastAPI application for router visualization")
 

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/tests/programatic.py

@@ -1,11 +1,12 @@
 from fastapi_voyager import create_voyager
 # from tests.demo_anno import app
-from tests.demo import app
+from tests.demo import app, diagram
 
 app.mount(
     '/voyager', 
     create_voyager(
         app, 
+        er_diagram=diagram,
         module_color={"tests.service": "purple"}, 
         module_prefix="tests.service", 
         swagger_url="/docs",

fastapi_voyager-0.13.0/tests/service/schema/base_entity.py

@@ -0,0 +1,3 @@
+from pydantic_resolve import base_entity
+
+BaseEntity = base_entity()

fastapi_voyager-0.13.0/tests/service/schema/schema.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+from typing import Literal
+from pydantic import BaseModel
+from pydantic_resolve import Relationship
+from .base_entity import BaseEntity
+
+
+
+class Member(BaseModel):
+    id: int
+    first_name: str
+    last_name: str
+
+class Task(BaseModel, BaseEntity):
+    __pydantic_resolve_relationships__ = [
+        Relationship(field='owner_id', target_kls=Member),
+        Relationship(field='story_id', target_kls='Story'),
+    ]
+    id: int
+    story_id: int
+    description: str
+    owner_id: int
+
+class Story(BaseModel, BaseEntity):
+    __pydantic_resolve_relationships__ = [
+        Relationship(field='id', target_kls=list[Task]),
+    ]
+    id: int
+    type: Literal['feature', 'bugfix']
+    dct: dict
+    sprint_id: int
+    title: str
+    description: str
+
+class Sprint(BaseModel, BaseEntity):
+    __pydantic_resolve_relationships__ = [
+        Relationship(field='id', target_kls=list[Story]) 
+    ]
+    id: int
+    name: str

{fastapi_voyager-0.12.12 → fastapi_voyager-0.13.0}/uv.lock

@@ -103,7 +103,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "fastapi", specifier = ">=0.110" },
-    { name = "pydantic-resolve", specifier = ">=1.13.2" },
+    { name = "pydantic-resolve", specifier = ">=2.2.3" },
     { name = "pytest", marker = "extra == 'dev'" },
     { name = "ruff", marker = "extra == 'dev'" },
     { name = "uvicorn", marker = "extra == 'dev'" },
@@ -259,14 +259,14 @@ wheels = [
 
 [[package]]
 name = "pydantic-resolve"
-version = "1.13.2"
+version = "2.2.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiodataloader" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/e5/8d/755cbd972c2113360b03f452a486694b17b04333d1a6af8d3083bb2631d9/pydantic_resolve-1.13.2.tar.gz", hash = "sha256:48d3ba00c766fa8bd7c86ff0e77a6fb149f9819a124bff8783835628ce35106a", size = 24512, upload-time = "2025-09-04T12:14:52.413Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/6d/9f/56e1960a479c63b572146826806bf0c408e9e094402a56cb5743627e76ea/pydantic_resolve-2.2.3.tar.gz", hash = "sha256:969ca1541930dd0395a31b8bd8939cc18ea6503f73a9ac96a2394ad423445e35", size = 33144, upload-time = "2025-12-07T12:37:38.841Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d3/11/96461b82307ace63faeefb3651401aba7cb8515448ff2ac7ce19fa54ae8b/pydantic_resolve-1.13.2-py3-none-any.whl", hash = "sha256:305ee2ab1d96ea1ae55678ffb2c554cc5d6029e38a6f7104d93f74a2b94c9c00", size = 26504, upload-time = "2025-09-04T12:14:49.939Z" },
+    { url = "https://files.pythonhosted.org/packages/09/b5/10204c33c2b3f9555ca21d6ded56baf7b9b0bb4733687cb3e0bde42e5f19/pydantic_resolve-2.2.3-py3-none-any.whl", hash = "sha256:05aaf82f4e403dd0cef4e45bb42d59719ccf903b029102730a32a80fa47e6ac2", size = 35149, upload-time = "2025-12-07T12:37:37.146Z" },
 ]
 
 [[package]]

fastapi_voyager-0.12.12/tests/service/schema/schema.py

@@ -1,28 +0,0 @@
-from typing import Literal
-
-from pydantic import BaseModel
-
-
-class Sprint(BaseModel):
-    id: int
-    name: str
-
-class Story(BaseModel):
-    id: int
-    type: Literal['feature', 'bugfix']
-    dct: dict
-    sprint_id: int
-    title: str
-    description: str
-
-class Task(BaseModel):
-    id: int
-    story_id: int
-    description: str
-    owner_id: int
-
-class Member(BaseModel):
-    id: int
-    first_name: str
-    last_name: str
-