fastapi-voyager 0.12.12__py3-none-any.whl → 0.13.0__py3-none-any.whl

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/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/version.py

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

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/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/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/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.dist-info → fastapi_voyager-0.13.0.dist-info}/METADATA

@@ -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.dist-info → fastapi_voyager-0.13.0.dist-info}/RECORD

@@ -1,21 +1,22 @@
 fastapi_voyager/__init__.py,sha256=kqwzThE1YhmQ_7jPKGlnWvqRGC-hFrRqq_lKhKaleYU,229
 fastapi_voyager/cli.py,sha256=td3yIIigEomhSdDO-Xkh-CgpEwCafwlwnpvxnT9QsBo,10488
+fastapi_voyager/er_diagram.py,sha256=GoTuriRTBk0Th_-ireuLHdzncjbk3WbIns8FVzeJz28,4064
 fastapi_voyager/filter.py,sha256=AN_HIu8-DtKisIq5mFt7CnqRHtxKewedNGyyaI82hSY,11529
 fastapi_voyager/module.py,sha256=h9YR3BpS-CAcJW9WCdVkF4opqwY32w9T67g9GfdLytk,3425
 fastapi_voyager/render.py,sha256=O_HR8ypOrFhjejkBpKIH_8foB78DgzH0hvO-CWeYt0w,9976
-fastapi_voyager/server.py,sha256=wwCFl1eeq_jn8nfIwcy7s8Sh6MB55SN8u9AsJRnkFWQ,7979
+fastapi_voyager/server.py,sha256=UZi-VdsurjDnqDgf3l5LfgWfZ4OxzilC_A_Ju6x9jQc,8592
 fastapi_voyager/type.py,sha256=7EL1zaIwKVRGpLig7fqaOrZGN5k0Rm31C9COfck3CSs,1750
 fastapi_voyager/type_helper.py,sha256=UTCFWluFeGdGkJX3wiE_bZ2EgZsu4JkmqHjsJVdG81Q,9953
-fastapi_voyager/version.py,sha256=uMVhHNPllcfXfpMIZdSROm4RSeWFftaJbfJVxfSYOMo,50
-fastapi_voyager/voyager.py,sha256=qJZvkLh5W_18X5B4pJ8XYbytx2Wvcz-0OnYoHWw8XlA,14046
+fastapi_voyager/version.py,sha256=jHHU_F0-L0N4sHMgRz3qTQ0PPdki_7FNU9kR-UybYwM,49
+fastapi_voyager/voyager.py,sha256=iWt-_QsoKavhb9ZawhU3W8gv3vTwn8PWTevg8BooyV8,13923
 fastapi_voyager/web/graph-ui.js,sha256=hTsZO1Ly1JuoRg0kZWQ62jeLiD2kbnzACfbSPd0F95U,6634
 fastapi_voyager/web/graphviz.svg.css,sha256=zDCjjpT0Idufu5YOiZI76PL70-avP3vTyzGPh9M85Do,1563
 fastapi_voyager/web/graphviz.svg.js,sha256=wZwz_lBztoXmujEN21P0w-HMpdmbqPwTQQ6Ebxd9rGo,18569
-fastapi_voyager/web/index.html,sha256=SNa6Vt3juCbRztA3ZH1PpJ0kW5fFSY1Mb0vVock2SOY,18774
+fastapi_voyager/web/index.html,sha256=_VaTvHNnuu_KcG2lLYB_bk7MGkG-Ok0-WgAAdFFGB2s,19336
 fastapi_voyager/web/quasar.min.css,sha256=F5jQe7X2XT54VlvAaa2V3GsBFdVD-vxDZeaPLf6U9CU,203145
 fastapi_voyager/web/quasar.min.js,sha256=h0ftyPMW_CRiyzeVfQqiup0vrVt4_QWojpqmpnpn07E,502974
-fastapi_voyager/web/store.js,sha256=rC9dMRv9sYuVHa5SJWaDI5cxgBZQ6bXk5F2M2e6KtmY,1958
-fastapi_voyager/web/vue-main.js,sha256=DFSje-Axno70B9NmmNAYhMsJU7YXZypz5hFdt3xcVK4,15061
+fastapi_voyager/web/store.js,sha256=wMApI0p3C9rBAEi4cfgU__bYwBm2cGO-cwIKdOvQaEk,2065
+fastapi_voyager/web/vue-main.js,sha256=BqFfjKRj1b2_nmR0Jmd2pL59Zk6qesrTNjRPpDRYMc4,16942
 fastapi_voyager/web/component/demo.js,sha256=bQb16Un4XZ3Mf8qL6gvyrXe_mmA3V3mSIRMQAWg2MNk,352
 fastapi_voyager/web/component/render-graph.js,sha256=e8Xgh2Kl-nYU0P1gstEmAepCgFnk2J6UdxW8TlMafGs,2322
 fastapi_voyager/web/component/route-code-display.js,sha256=8NJPPjNRUC21gjpY8XYEQs4RBbhX1pCiqEhJp39ku6k,3678
@@ -27,8 +28,8 @@ fastapi_voyager/web/icon/favicon-16x16.png,sha256=JC07jEzfIYxBIoQn_FHXvyHuxESdhW
 fastapi_voyager/web/icon/favicon-32x32.png,sha256=C7v1h58cfWOsiLp9yOIZtlx-dLasBcq3NqpHVGRmpt4,1859
 fastapi_voyager/web/icon/favicon.ico,sha256=tZolYIXkkBcFiYl1A8ksaXN2VjGamzcSdes838dLvNc,15406
 fastapi_voyager/web/icon/site.webmanifest,sha256=ep4Hzh9zhmiZF2At3Fp1dQrYQuYF_3ZPZxc1KcGBvwQ,263
-fastapi_voyager-0.12.12.dist-info/METADATA,sha256=8bnLo4QwIIFzKc2esih1Vw2pQ9SwGxIi_FY3E3emp_I,6523
-fastapi_voyager-0.12.12.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-fastapi_voyager-0.12.12.dist-info/entry_points.txt,sha256=pEIKoUnIDXEtdMBq8EmXm70m16vELIu1VPz9-TBUFWM,53
-fastapi_voyager-0.12.12.dist-info/licenses/LICENSE,sha256=lNVRR3y_bFVoFKuK2JM8N4sFaj3m-7j29kvL3olFi5Y,1067
-fastapi_voyager-0.12.12.dist-info/RECORD,,
+fastapi_voyager-0.13.0.dist-info/METADATA,sha256=uKfxGwFJQZC7LY3Es7RuWhccR5OBPm8s1m7kmrjtokI,6521
+fastapi_voyager-0.13.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fastapi_voyager-0.13.0.dist-info/entry_points.txt,sha256=pEIKoUnIDXEtdMBq8EmXm70m16vELIu1VPz9-TBUFWM,53
+fastapi_voyager-0.13.0.dist-info/licenses/LICENSE,sha256=lNVRR3y_bFVoFKuK2JM8N4sFaj3m-7j29kvL3olFi5Y,1067
+fastapi_voyager-0.13.0.dist-info/RECORD,,