fastapi-voyager 0.4.1__py3-none-any.whl

fastapi_voyager/web/vue-main.js

@@ -0,0 +1,213 @@
+import SchemaFieldFilter from "./component/schema-field-filter.js";
+import SchemaCodeDisplay from "./component/schema-code-display.js";
+import RouteCodeDisplay from "./component/route-code-display.js";
+import { GraphUI } from "./graph-ui.js";
+const { createApp, reactive, onMounted, watch, ref } = window.Vue;
+
+const app = createApp({
+  setup() {
+    const state = reactive({
+      // options and selections
+      tag: null,
+      tagOptions: [], // array of strings
+      routeId: null,
+      routeOptions: [], // [{ label, value }]
+      schemaFullname: null,
+      schemaOptions: [], // [{ label, value }]
+      routeItems: {}, // { id: { label, value } }
+      showFields: "object",
+      fieldOptions: [
+        { label: "No fields", value: "single" },
+        { label: "Object fields", value: "object" },
+        { label: "All fields", value: "all" },
+      ],
+      generating: false,
+      rawTags: [], // [{ name, routes: [{ id, name }] }]
+      rawSchemas: [], // [{ name, fullname }]
+      rawSchemasFull: [], // full objects with source_code & fields
+  initializing: true,
+    });
+    const showDetail = ref(false);
+    const showSchemaFieldFilter = ref(false);
+  const showSchemaCode = ref(false);
+  const showRouteCode = ref(false);
+    const schemaName = ref(""); // used by detail dialog
+    const schemaFieldFilterSchema = ref(null); // external schemaName for schema-field-filter
+  const schemaCodeName = ref("");
+  const routeCodeId = ref("");
+    function openDetail() {
+      showDetail.value = true;
+    }
+    function closeDetail() {
+      showDetail.value = false;
+    }
+
+    function applyRoutesForTag(tagName) {
+      const tag = state.rawTags.find((t) => t.name === tagName);
+      state.routeOptions = [];
+      if (tag && Array.isArray(tag.routes)) {
+        state.routeOptions.push(
+          ...tag.routes.map((r) => ({ label: r.name, value: r.id }))
+        );
+      }
+      state.routeId = "";
+    }
+
+    function onFilterTags(val, update) {
+      const normalized = (val || "").toLowerCase();
+      update(() => {
+        if (!normalized) {
+          state.tagOptions = state.rawTags.map((t) => t.name);
+          return;
+        }
+        state.tagOptions = state.rawTags
+          .map((t) => t.name)
+          .filter((n) => n.toLowerCase().includes(normalized));
+      });
+    }
+
+    function onFilterSchemas(val, update) {
+      const normalized = (val || "").toLowerCase();
+      update(() => {
+        const makeLabel = (s) => `${s.name} (${s.fullname})`;
+        let list = state.rawSchemas.map((s) => ({
+          label: makeLabel(s),
+          value: s.fullname,
+        }));
+        if (normalized) {
+          list = list.filter((opt) =>
+            opt.label.toLowerCase().includes(normalized)
+          );
+        }
+        state.schemaOptions = list;
+      });
+    }
+
+    async function loadInitial() {
+      state.initializing = true;
+      try {
+        const res = await fetch("/dot");
+        const data = await res.json();
+        state.rawTags = Array.isArray(data.tags) ? data.tags : [];
+        state.rawSchemasFull = Array.isArray(data.schemas) ? data.schemas : [];
+        state.rawSchemas = state.rawSchemasFull.map((s) => ({
+          name: s.name,
+          fullname: s.fullname,
+        }));
+        state.routeItems = data.tags.map((t) => t.routes).flat().reduce((acc, r) => {
+          acc[r.id] = r;
+          return acc;
+        }, {});
+
+        state.tagOptions = state.rawTags.map((t) => t.name);
+        state.schemaOptions = state.rawSchemas.map((s) => ({
+          label: `${s.name} (${s.fullname})`,
+          value: s.fullname,
+        }));
+        // default route options placeholder
+        state.routeOptions = [];
+      } catch (e) {
+        console.error("Initial load failed", e);
+      } finally {
+        state.initializing = false;
+      }
+    }
+
+    async function onGenerate() {
+      state.generating = true;
+      try {
+        const payload = {
+          tags: state.tag ? [state.tag] : null,
+          schema_name: state.schemaFullname || null,
+          route_name: state.routeId || null,
+          show_fields: state.showFields,
+        };
+
+        const res = await fetch("/dot", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(payload),
+        });
+        const dotText = await res.text();
+
+        // create graph instance once
+        const graphUI = new GraphUI("#graph", {
+          onSchemaClick: (name) => {
+            if (state.rawSchemas.find((s) => s.fullname === name)) {
+              schemaFieldFilterSchema.value = name;
+              showSchemaFieldFilter.value = true;
+            }
+          },
+          onSchemaAltClick: (name) => {
+            // priority: schema full name; else route id
+            if (state.rawSchemas.find((s) => s.fullname === name)) {
+              schemaCodeName.value = name;
+              showSchemaCode.value = true;
+              return;
+            }
+            if (name in state.routeItems) {
+              routeCodeId.value = name;
+              showRouteCode.value = true;
+              return;
+            }
+          },
+        });
+
+        await graphUI.render(dotText);
+      } catch (e) {
+        console.error("Generate failed", e);
+      } finally {
+        state.generating = false;
+      }
+    }
+
+    function showDialog() {
+      schemaFieldFilterSchema.value = null;
+      showSchemaFieldFilter.value = true;
+    }
+
+    async function onReset() {
+      state.tag = null;
+      state.routeId = "";
+      state.schemaFullname = null;
+      state.showFields = "object";
+      await loadInitial();
+    }
+
+    // react to tag changes to rebuild routes
+    watch(
+      () => state.tag,
+      (val) => {
+        applyRoutesForTag(val);
+      }
+    );
+
+    onMounted(async () => {
+      await loadInitial();
+    });
+
+    return {
+      state,
+      onFilterTags,
+      onFilterSchemas,
+      onGenerate,
+      onReset,
+      showDetail,
+      openDetail,
+      closeDetail,
+      schemaName,
+      showSchemaFieldFilter,
+      schemaFieldFilterSchema,
+      showDialog,
+      showSchemaCode,
+      showRouteCode,
+      schemaCodeName,
+      routeCodeId,
+    };
+  },
+});
+app.use(window.Quasar);
+app.component("schema-field-filter", SchemaFieldFilter);
+app.component("schema-code-display", SchemaCodeDisplay);
+app.component("route-code-display", RouteCodeDisplay);
+app.mount("#q-app");

fastapi_voyager-0.4.1.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: fastapi-voyager
+Version: 0.4.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
+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)
+
+> This repo is still in early stage, currently it support pydantic v2 only, previous name: fastapi-router-viz
+
+Inspect your API interactively
+
+<img width="1480" height="648" alt="image" src="https://github.com/user-attachments/assets/a6ccc9f1-cf06-493a-b99b-eb07767564bd" />
+
+## Installation
+
+```bash
+pip install fastapi-voyager
+# or
+uv add fastapi-voyager
+```
+
+
+## Dependencies
+
+- FastAPI
+- [pydantic-resolve](https://github.com/allmonday/pydantic-resolve)
+
+
+## Feature
+
+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 through visualization during the design phase.
+
+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
+
+
+
+```shell
+git clone https://github.com/allmonday/fastapi-voyager.git
+cd fastapi-voyager
+
+voyager -m tests.demo 
+           --server --port=8001 
+           --module_color=tests.service:blue 
+           --module_color=tests.demo:tomato
+```
+
+pick tag, rotue (optional) and click `generate`.
+
+<img width="1919" height="898" alt="image" style="border: 1px solid #aaa" src="https://github.com/user-attachments/assets/05e321d0-49f3-4af6-a7c7-f4c9c6b1dbfd" />
+
+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="1485" height="616" alt="image" style="border: 1px solid #aaa" src="https://github.com/user-attachments/assets/70c4095f-86c7-45da-a6f0-fd41ac645813" />
+
+
+`shift` click a node to check related nodes.
+
+pick a field to narrow the result.
+
+<img width="1917" height="800" alt="image" style="border: 1px solid #aaa" src="https://github.com/user-attachments/assets/e770dc70-f293-49e1-bcd7-d8dffa15d9ea" />
+
+`alt` click a node to show source code or open file in vscode.
+
+<img width="497" height="402" alt="image" style="border: 1px solid #aaa" src="https://github.com/user-attachments/assets/ac81711a-d9c2-4fb1-8b3a-0f4bd1f02572" />
+
+more in video:
+
+[![IMAGE ALT TEXT](http://img.youtube.com/vi/msYsB9Cc3CA/0.jpg)](https://www.youtube.com/watch?v=msYsB9Cc3CA "Unity Snake Game")
+
+
+## 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
+```
+
+The tool will generate a DOT file that you can render using Graphviz:
+
+```bash
+# Install graphviz
+brew install graphviz  # macOS
+apt-get install graphviz  # Ubuntu/Debian
+
+# Render the graph
+dot -Tpng router_viz.dot -o router_viz.png
+
+# Or view online at: https://dreampuf.github.io/GraphvizOnline/
+```
+
+or you can open router_viz.dot with vscode extension `graphviz interactive preview`
+
+
+## Plan
+
+features:
+- [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 
+- [ ] user can generate nodes/edges manually and connect to generated ones
+- [ ] support dataclass
+- [ ] group routes by module hierarchy
+- [ ] integration with pydantic-resolve
+    - [ ] show difference between resolve, post fields
+    - [x] strikethrough for excluded fields
+    - [ ] display loader as edges
+- [ ] test cases
+
+bugs:
+- [ ] fix duplicated link from class and parent class, it also break clicking highlight
+
+
+## Credits
+
+- https://apis.guru/graphql-voyager/, for inspiration.
+- https://github.com/tintinweb/vscode-interactive-graphviz, for web visualization.

fastapi_voyager-0.4.1.dist-info/RECORD

@@ -0,0 +1,24 @@
+fastapi_voyager/__init__.py,sha256=E5WTV_sYs2LK8I6jzA7AuvFU5a8_vjnDseC3DMha0iQ,149
+fastapi_voyager/cli.py,sha256=FuXllJtlsm33FX6VmDdAFWzzQ5TIraUizBDgvBj3vmY,10489
+fastapi_voyager/filter.py,sha256=uZrVVMhHG5E7j1wdsiB02RAyoDdF1q8A4J04oCboYAU,4644
+fastapi_voyager/graph.py,sha256=H2qpEkLqjE2AceOOQIHPuhK_YvgSUBLvi78dBCLYAGc,14489
+fastapi_voyager/module.py,sha256=ppiJ46rdyA4yQnQA5IQqsMOHGgWdz5orJ0bEQydHsEk,1885
+fastapi_voyager/server.py,sha256=UFj6c0Yx4Rmy56eFXv65n1VdmJeiBX43KsDm6D65U28,2943
+fastapi_voyager/type.py,sha256=k8V45obOzS6HQD8RqaBh4xKBQRUsV-mA_UdMZu51KR0,1005
+fastapi_voyager/type_helper.py,sha256=VLQNivjFi7Wx7_v4vgRvY0uCD2IcqBpvEV3C74MVXK8,7450
+fastapi_voyager/version.py,sha256=YFh850u830ExUciTkvvBKNAw5-kOUreAy1p-gcJGJ70,48
+fastapi_voyager/web/graph-ui.js,sha256=eEjDnJVMvk35LdRoxcqX_fZxLFS9_bUrGAZL6K2O5C0,4176
+fastapi_voyager/web/graphviz.svg.css,sha256=zDCjjpT0Idufu5YOiZI76PL70-avP3vTyzGPh9M85Do,1563
+fastapi_voyager/web/graphviz.svg.js,sha256=lvAdbjHc-lMSk4GQp-iqYA2PCFX4RKnW7dFaoe0LUHs,16005
+fastapi_voyager/web/index.html,sha256=-AAK0hxtW58urx_T13o7OHKTlEAk9ZyMKz-2MDPj0S8,7864
+fastapi_voyager/web/quasar.min.css,sha256=F5jQe7X2XT54VlvAaa2V3GsBFdVD-vxDZeaPLf6U9CU,203145
+fastapi_voyager/web/quasar.min.js,sha256=h0ftyPMW_CRiyzeVfQqiup0vrVt4_QWojpqmpnpn07E,502974
+fastapi_voyager/web/vue-main.js,sha256=PpvaoDquNgOAsqWgIO75bWRcEVl_vuos_vM1Qo5jlww,6406
+fastapi_voyager/web/component/route-code-display.js,sha256=NECC1OGcPCdDfbghtRJEnmFM6HmH5J3win2ibapWPeA,2649
+fastapi_voyager/web/component/schema-code-display.js,sha256=oOusgTvCaWGnoKb-NBwu0SXqJJf2PTUtp3lUczokTBM,5515
+fastapi_voyager/web/component/schema-field-filter.js,sha256=9WBjO6JJl2yf6OiiXoddMgvL32qTDu0PM-RxkkJ7t5M,6267
+fastapi_voyager-0.4.1.dist-info/METADATA,sha256=nl6TQBqmoIj4l9dF5XRZW1wv9edEvYLlDSUMuUr5D2A,5839
+fastapi_voyager-0.4.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fastapi_voyager-0.4.1.dist-info/entry_points.txt,sha256=pEIKoUnIDXEtdMBq8EmXm70m16vELIu1VPz9-TBUFWM,53
+fastapi_voyager-0.4.1.dist-info/licenses/LICENSE,sha256=lNVRR3y_bFVoFKuK2JM8N4sFaj3m-7j29kvL3olFi5Y,1067
+fastapi_voyager-0.4.1.dist-info/RECORD,,

fastapi_voyager-0.4.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_voyager-0.4.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+voyager = fastapi_voyager.cli:main

fastapi_voyager-0.4.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tangkikodo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.