fastapi-voyager 0.15.5__py3-none-any.whl → 0.16.0a1__py3-none-any.whl

fastapi_voyager/voyager.py

@@ -1,6 +1,5 @@
 
 import pydantic_resolve.constant as const
-from fastapi import FastAPI, routing
 from pydantic import BaseModel
 
 from fastapi_voyager.filter import (
@@ -8,6 +7,7 @@ from fastapi_voyager.filter import (
     filter_subgraph_by_module_prefix,
     filter_subgraph_from_tag_to_schema_by_module_prefix,
 )
+from fastapi_voyager.introspectors import AppIntrospector, RouteInfo
 from fastapi_voyager.render import Renderer
 from fastapi_voyager.type import PK, CoreData, FieldType, Link, LinkType, Route, SchemaNode, Tag
 from fastapi_voyager.type_helper import (
@@ -57,99 +57,127 @@ class Voyager:
         self.hide_primitive_route = hide_primitive_route
         self.show_module = show_module
         self.show_pydantic_resolve_meta = show_pydantic_resolve_meta
-    
 
-    def _get_available_route(self, app: FastAPI):
-        for route in app.routes:
-            if isinstance(route, routing.APIRoute):
-                yield route
+    def _get_introspector(self, app) -> AppIntrospector:
+        """
+        Get the appropriate introspector for the given app.
+
+        Automatically detects the framework type and returns the matching introspector.
 
+        Args:
+            app: A web application instance or AppIntrospector
 
-    def analysis(self, app: FastAPI):
+        Returns:
+            An AppIntrospector instance
+
+        Raises:
+            TypeError: If the app type is not supported
         """
+        from fastapi_voyager.introspectors import get_introspector
+
+        return get_introspector(app)
+
+    def analysis(self, app):
+        """
+        Analyze routes and schemas from a web application.
+
+        This method automatically detects the framework type and uses the appropriate
+        introspector. Supported frameworks:
+        - FastAPI (built-in)
+        - Any framework with a custom AppIntrospector implementation
+
+        Args:
+            app: A web application instance (FastAPI, Django Ninja API, etc.)
+                  or an AppIntrospector instance for custom frameworks.
+
         1. get routes which return pydantic schema
             1.1 collect tags and routes, add links tag-> route
             1.2 collect response_model and links route -> response_model
 
         2. iterate schemas, construct the schema/model nodes and their links
         """
+        introspector = self._get_introspector(app)
         schemas: list[type[BaseModel]] = []
 
         # First, group all routes by tag
-        routes_by_tag: dict[str, list] = {}
-        for route in self._get_available_route(app):
-            tags = getattr(route, 'tags', None)
-
+        routes_by_tag: dict[str, list[RouteInfo]] = {}
+        for route_info in introspector.get_routes():
             # using multiple tags is harmful, it's not recommended and will not be supported
-            route_tag = tags[0] if tags else '__default__'  
-            routes_by_tag.setdefault(route_tag, []).append(route)
+            route_tag = route_info.tags[0] if route_info.tags else '__default__'
+            routes_by_tag.setdefault(route_tag, []).append(route_info)
 
         # Then filter by include_tags if provided
         if self.include_tags:
-            filtered_routes_by_tag = {tag: routes for tag, routes in routes_by_tag.items() 
-                                    if tag in self.include_tags}
+            filtered_routes_by_tag = {
+                tag: routes
+                for tag, routes in routes_by_tag.items()
+                if tag in self.include_tags
+            }
         else:
             filtered_routes_by_tag = routes_by_tag
 
         # Process filtered routes
-        for route_tag, routes in filtered_routes_by_tag.items():
-
+        for route_tag, route_infos in filtered_routes_by_tag.items():
             tag_id = f'tag__{route_tag}'
             tag_obj = Tag(id=tag_id, name=route_tag, routes=[])
             self.tags.append(tag_obj)
 
-            for route in routes:
-                # add route and create links
-                route_id = full_class_name(route.endpoint)
-                route_name = route.endpoint.__name__
-                route_module = route.endpoint.__module__
-
+            for route_info in route_infos:
                 # filter by route_name (route.id) if provided
-                if self.route_name is not None and route_id != self.route_name:
+                if self.route_name is not None and route_info.id != self.route_name:
                     continue
 
-                is_primitive_response = is_non_pydantic_type(route.response_model)
+                is_primitive_response = is_non_pydantic_type(route_info.response_model)
                 # filter primitive route if needed
                 if self.hide_primitive_route and is_primitive_response:
                     continue
 
-                self.links.append(Link(
-                    source=tag_id,
-                    source_origin=tag_id,
-                    target=route_id,
-                    target_origin=route_id,
-                    type='tag_route'
-                ))
+                self.links.append(
+                    Link(
+                        source=tag_id,
+                        source_origin=tag_id,
+                        target=route_info.id,
+                        target_origin=route_info.id,
+                        type='tag_route',
+                    )
+                )
+
+                # Get unique_id from extra data if available
+                unique_id = route_info.operation_id
+                if route_info.extra and 'unique_id' in route_info.extra:
+                    unique_id = unique_id or route_info.extra['unique_id']
 
                 route_obj = Route(
-                    id=route_id,
-                    name=route_name,
-                    module=route_module,
-                    unique_id=route.operation_id or route.unique_id,
-                    response_schema=get_type_name(route.response_model),
-                    is_primitive=is_primitive_response
+                    id=route_info.id,
+                    name=route_info.name,
+                    module=route_info.module,
+                    unique_id=unique_id,
+                    response_schema=get_type_name(route_info.response_model),
+                    is_primitive=is_primitive_response,
                 )
                 self.routes.append(route_obj)
                 tag_obj.routes.append(route_obj)
 
                 # add response_models and create links from route -> response_model
-                for schema in get_core_types(route.response_model):
+                for schema in get_core_types(route_info.response_model):
                     if schema and issubclass(schema, BaseModel):
                         is_primitive_response = False
                         target_name = full_class_name(schema)
-                        self.links.append(Link(
-                            source=route_id,
-                            source_origin=route_id,
-                            target=self.generate_node_head(target_name),
-                            target_origin=target_name,
-                            type='route_to_schema'
-                        ))
+                        self.links.append(
+                            Link(
+                                source=route_info.id,
+                                source_origin=route_info.id,
+                                target=self.generate_node_head(target_name),
+                                target_origin=target_name,
+                                type='route_to_schema',
+                            )
+                        )
 
                         schemas.append(schema)
 
         for s in schemas:
             self.analysis_schemas(s)
-        
+
         self.nodes = list(self.node_set.values())
 
 

fastapi_voyager/web/graph-ui.js

@@ -1,4 +1,15 @@
 export class GraphUI {
+  // ====================
+  // Constants
+  // ====================
+
+  static HIGHLIGHT_COLOR = "#822dba"
+  static HIGHLIGHT_STROKE_WIDTH = "3.0"
+
+  // ====================
+  // Constructor
+  // ====================
+
   constructor(selector = "#graph", options = {}) {
     this.selector = selector
     this.options = options // e.g. { onSchemaClick: (name) => {} }
@@ -9,6 +20,10 @@ export class GraphUI {
     this._init()
   }
 
+  // ====================
+  // Highlight Methods
+  // ====================
+
   _highlight(mode = "bidirectional") {
     let highlightedNodes = $()
     for (const selection of this.currentSelection) {
@@ -68,49 +83,79 @@ export class GraphUI {
     return $result
   }
 
+  // ====================
+  // Schema Banner Methods
+  // ====================
+
   highlightSchemaBanner(node) {
-    // Get all polygons in the node
     const polygons = node.querySelectorAll("polygon")
-
-    // 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")
+      this._saveOriginalAttributes(outerFrame)
+      outerFrame.setAttribute("stroke", GraphUI.HIGHLIGHT_COLOR)
+      outerFrame.setAttribute("stroke-width", GraphUI.HIGHLIGHT_STROKE_WIDTH)
     }
 
     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") || "")
-      }
+      this._saveOriginalAttributes(titleBg)
+      titleBg.setAttribute("fill", GraphUI.HIGHLIGHT_COLOR)
+      titleBg.setAttribute("stroke", GraphUI.HIGHLIGHT_COLOR)
+    }
+  }
 
-      // Apply purple background to title
-      titleBg.setAttribute("fill", "#822dba")
-      // Also update the stroke to match
-      titleBg.setAttribute("stroke", "#822dba")
+  clearSchemaBanners() {
+    if (this.gv) {
+      this.gv.highlight()
+    }
+
+    const allPolygons = document.querySelectorAll("polygon[data-original-stroke]")
+    allPolygons.forEach((polygon) => {
+      polygon.removeAttribute("data-original-stroke")
+      polygon.removeAttribute("data-original-stroke-width")
+      polygon.removeAttribute("data-original-fill")
+    })
+  }
+
+  _saveOriginalAttributes(element) {
+    if (!element.hasAttribute("data-original-stroke")) {
+      element.setAttribute("data-original-stroke", element.getAttribute("stroke") || "")
+      element.setAttribute(
+        "data-original-stroke-width",
+        element.getAttribute("stroke-width") || "1"
+      )
+      element.setAttribute("data-original-fill", element.getAttribute("fill") || "")
     }
   }
 
+  _applyNodeHighlight(node) {
+    const set = $()
+    set.push(node)
+    const obj = { set, direction: "bidirectional" }
+
+    this.clearSchemaBanners()
+    this.currentSelection = [obj]
+    this._highlight()
+
+    return obj
+  }
+
+  _triggerCallback(callbackName, schemaName) {
+    const callback = this.options[callbackName]
+    if (callback && schemaName) {
+      try {
+        callback(schemaName)
+      } catch (e) {
+        console.warn(`${callbackName} callback failed`, e)
+      }
+    }
+  }
+
+  // ====================
+  // Initialization & Events
+  // ====================
+
   _init() {
     const self = this
     $(this.selector).graphviz({
@@ -127,80 +172,64 @@ export class GraphUI {
 
         nodes.on("dblclick.graphui", function (event) {
           event.stopPropagation()
+
+          self._applyNodeHighlight(this)
+
           try {
             self.highlightSchemaBanner(this)
           } catch (e) {
             console.log(e)
           }
-          const set = $()
-          set.push(this)
-          const schemaName = event.currentTarget.dataset.name
-          if (schemaName) {
-            try {
-              self.options.onSchemaClick(schemaName)
-            } catch (e) {
-              console.warn("onSchemaClick callback failed", e)
-            }
-          }
+
+          self._triggerCallback("onSchemaClick", event.currentTarget.dataset.name)
         })
 
         edges.on("click.graphui", function (event) {
+          const [upStreamNode, downStreamNode] = event.currentTarget.dataset.name.split("->")
+          const nodes = self.gv.nodesByName()
+
           const up = $()
           const down = $()
           const edge = $()
-          const [upStreamNode, downStreamNode] = event.currentTarget.dataset.name.split("->")
-          const nodes = self.gv.nodesByName()
+
           up.push(nodes[upStreamNode])
           down.push(nodes[downStreamNode])
           edge.push(this)
-          const upObj = { set: up, direction: "upstream" }
-          const downObj = { set: down, direction: "downstream" }
-          const edgeOjb = { set: edge, direction: "single" }
-          self.currentSelection = [upObj, downObj, edgeOjb]
+
+          self.currentSelection = [
+            { set: up, direction: "upstream" },
+            { set: down, direction: "downstream" },
+            { set: edge, direction: "single" },
+          ]
 
           self._highlightEdgeNodes()
         })
 
         nodes.on("click.graphui", function (event) {
-          const set = $()
-          set.push(this)
-          const obj = { set, direction: "bidirectional" }
-
-          const schemaName = event.currentTarget.dataset.name
-          console.log("shift click detected")
-          if (event.shiftKey && self.options.onSchemaShiftClick) {
-            if (schemaName) {
-              try {
-                self.options.onSchemaShiftClick(schemaName)
-              } catch (e) {
-                console.warn("onSchemaShiftClick callback failed", e)
-              }
-            }
+          if (event.shiftKey) {
+            self._triggerCallback("onSchemaShiftClick", event.currentTarget.dataset.name)
           } else {
-            self.currentSelection = [obj]
-            self._highlight()
+            self._applyNodeHighlight(this)
           }
         })
 
         $(document)
           .off("click.graphui")
           .on("click.graphui", function (evt) {
-            // if outside container, do nothing
             const graphContainer = $(self.selector)[0]
             if (!graphContainer || !evt.target || !graphContainer.contains(evt.target)) {
               return
             }
 
-            let isNode = false
             const $everything = self.gv.$nodes.add(self.gv.$edges).add(self.gv.$clusters)
             const node = evt.target.parentNode
-            $everything.each(function () {
-              if (this === node) {
-                isNode = true
-              }
+            const isNode = $everything.is(function () {
+              return this === node
             })
+
             if (!isNode && self.gv) {
-              self.gv.highlight()
+              self.clearSchemaBanners()
+
               if (self.options.resetCb) {
                 self.options.resetCb()
               }
@@ -210,6 +239,10 @@ export class GraphUI {
     })
   }
 
+  // ====================
+  // Render Method
+  // ====================
+
   async render(dotSrc, resetZoom = true) {
     const height = this.options.height || "100%"
     return new Promise((resolve, reject) => {

fastapi_voyager/web/graphviz.svg.js

@@ -17,6 +17,13 @@
 
   GraphvizSvg.GVPT_2_PX = 32.5 // used to ease removal of extra space
 
+  // SVG element selectors for color manipulation
+  // NOTE: If you need to add more element types for highlighting/dimming,
+  // update SHAPE_ELEMENTS and the code will automatically handle them
+  GraphvizSvg.SHAPE_ELEMENTS = "polygon, ellipse, path, polyline"
+  GraphvizSvg.TEXT_ELEMENTS = "text"
+  GraphvizSvg.ALL_COLOR_ELEMENTS = GraphvizSvg.SHAPE_ELEMENTS + ", " + GraphvizSvg.TEXT_ELEMENTS
+
   GraphvizSvg.DEFAULTS = {
     url: null,
     svg: null,
@@ -178,8 +185,8 @@
       this.setInteractiveCursor($el, type === "edge")
     }
 
-    // save the colors of the paths, ellipses and polygons
-    $el.find("polygon, ellipse, path").each(function () {
+    // Save the colors of shape elements (polygon, ellipse, path, polyline)
+    $el.find(GraphvizSvg.SHAPE_ELEMENTS).each(function () {
       var $this = $(this)
       if ($this.attr("data-graphviz-hitbox") === "true") {
         return
@@ -196,6 +203,20 @@
       }
     })
 
+    // Save the colors of text elements
+    $el.find(GraphvizSvg.TEXT_ELEMENTS).each(function () {
+      var $this = $(this)
+      // text elements might not have explicit fill attribute, use black as default
+      var fill = $this.attr("fill")
+      if (!fill || fill === "none") {
+        fill = "#000000" // default black color for text
+      }
+      $this.data("graphviz.svg.color", {
+        fill: fill,
+        stroke: $this.attr("stroke"),
+      })
+    })
+
     // save the node name and check if theres a comment above; save it
     var $title = $el.children("title")
     if ($title[0]) {
@@ -404,6 +425,57 @@
     return retval
   }
 
+  // Helper function to apply color transformation to elements
+  GraphvizSvg.prototype._applyColorToElements = function (
+    $elements,
+    colorTransformer,
+    bgColor,
+    setStrokeWidth
+  ) {
+    var that = this
+    $elements.each(function () {
+      var $this = $(this)
+      if ($this.attr("data-graphviz-hitbox") === "true") {
+        return
+      }
+      var color = $this.data("graphviz.svg.color")
+      if (color) {
+        if (color.fill && color.fill != "none") {
+          $this.attr("fill", colorTransformer(color.fill, bgColor))
+        }
+        if (color.stroke && color.stroke != "none") {
+          $this.attr("stroke", colorTransformer(color.stroke, bgColor))
+        }
+        if (setStrokeWidth !== undefined) {
+          $this.attr("stroke-width", setStrokeWidth)
+        }
+      }
+    })
+  }
+
+  // Helper function to restore original colors
+  GraphvizSvg.prototype._restoreElementColors = function ($elements, setStrokeWidth) {
+    var that = this
+    $elements.each(function () {
+      var $this = $(this)
+      if ($this.attr("data-graphviz-hitbox") === "true") {
+        return
+      }
+      var color = $this.data("graphviz.svg.color")
+      if (color) {
+        if (color.fill && color.fill != "none") {
+          $this.attr("fill", color.fill)
+        }
+        if (color.stroke && color.stroke != "none") {
+          $this.attr("stroke", color.stroke)
+        }
+        if (setStrokeWidth !== undefined) {
+          $this.attr("stroke-width", setStrokeWidth)
+        }
+      }
+    })
+  }
+
   GraphvizSvg.prototype.findEdge = function (nodeName, testEdge, $retval) {
     var retval = []
     for (var name in this._edgesByName) {
@@ -439,37 +511,14 @@
 
   GraphvizSvg.prototype.colorElement = function ($el, getColor) {
     var bg = this.$element.css("background")
-    $el.find("polygon, ellipse, path").each(function () {
-      var $this = $(this)
-      if ($this.attr("data-graphviz-hitbox") === "true") {
-        return
-      }
-      var color = $this.data("graphviz.svg.color")
-      if (color.fill && color.fill != "none") {
-        $this.attr("fill", getColor(color.fill, bg)) // don't set  fill if it's a path
-      }
-      if (color.stroke && color.stroke != "none") {
-        $this.attr("stroke", getColor(color.stroke, bg))
-      }
-      $this.attr("stroke-width", 1.6)
-    })
+
+    // Apply color transformation to all elements (shapes + text)
+    this._applyColorToElements($el.find(GraphvizSvg.ALL_COLOR_ELEMENTS), getColor, bg)
   }
 
   GraphvizSvg.prototype.restoreElement = function ($el) {
-    $el.find("polygon, ellipse, path").each(function () {
-      var $this = $(this)
-      if ($this.attr("data-graphviz-hitbox") === "true") {
-        return
-      }
-      var color = $this.data("graphviz.svg.color")
-      if (color.fill && color.fill != "none") {
-        $this.attr("fill", color.fill) // don't set  fill if it's a path
-      }
-      if (color.stroke && color.stroke != "none") {
-        $this.attr("stroke", color.stroke)
-      }
-      $this.attr("stroke-width", 1)
-    })
+    // Restore original colors for all elements (shapes + text)
+    this._restoreElementColors($el.find(GraphvizSvg.ALL_COLOR_ELEMENTS), 1)
   }
 
   // methods users can actually call

fastapi_voyager/web/index.html

@@ -4,32 +4,29 @@
     <meta name="theme-color" content="#ffffff" />
     <link
       rel="stylesheet"
-      href="fastapi-voyager-static/graphviz.svg.css<!-- VERSION_PLACEHOLDER -->"
-    />
-    <link
-      rel="stylesheet"
-      href="fastapi-voyager-static/quasar.min.css<!-- VERSION_PLACEHOLDER -->"
+      href="<!-- STATIC_PATH -->/graphviz.svg.css<!-- VERSION_PLACEHOLDER -->"
     />
+    <link rel="stylesheet" href="<!-- STATIC_PATH -->/quasar.min.css<!-- VERSION_PLACEHOLDER -->" />
     <!-- App Icons / Favicons -->
     <link
       rel="apple-touch-icon"
       sizes="180x180"
-      href="fastapi-voyager-static/icon/apple-touch-icon.png"
+      href="<!-- STATIC_PATH -->/icon/apple-touch-icon.png"
     />
     <link
       rel="icon"
       type="image/png"
       sizes="32x32"
-      href="fastapi-voyager-static/icon/favicon-32x32.png"
+      href="<!-- STATIC_PATH -->/icon/favicon-32x32.png"
     />
     <link
       rel="icon"
       type="image/png"
       sizes="16x16"
-      href="fastapi-voyager-static/icon/favicon-16x16.png"
+      href="<!-- STATIC_PATH -->/icon/favicon-16x16.png"
     />
-    <link rel="icon" href="fastapi-voyager-static/icon/favicon.ico" sizes="any" />
-    <link rel="manifest" href="fastapi-voyager-static/icon/site.webmanifest" />
+    <link rel="icon" href="<!-- STATIC_PATH -->/icon/favicon.ico" sizes="any" />
+    <link rel="manifest" href="<!-- STATIC_PATH -->/icon/site.webmanifest" />
     <link
       href="https://fonts.googleapis.com/css?family=Roboto:100,300,400,500,700,900|Material+Icons"
       rel="stylesheet"
@@ -191,7 +188,7 @@
               style="font-size: 18px; font-weight: bold; display: flex; align-items: baseline"
             >
               <q-icon class="q-mr-sm" name="satellite_alt"></q-icon>
-              <span> FastAPI Voyager </span>
+              <span> {{ store.state.framework_name }} Voyager </span>
               <span
                 v-if="store.state.version"
                 style="font-size: 12px; margin-left: 8px; font-weight: normal"
@@ -580,7 +577,7 @@
       </q-dialog>
     </div>
     <script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
-    <script src="fastapi-voyager-static/quasar.min.js<!-- VERSION_PLACEHOLDER -->"></script>
+    <script src="<!-- STATIC_PATH -->/quasar.min.js<!-- VERSION_PLACEHOLDER -->"></script>
     <script
       src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.3/jquery.min.js"
       integrity="sha512-egJ/Y+22P9NQ9aIyVCh0VCOsfydyn8eNmqBy+y2CnJG+fpRIxXMS6jbWP8tVKp0jp+NO5n8WtMUAnNnGoJKi4w=="
@@ -602,7 +599,7 @@
     ></script>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-mousewheel/3.1.13/jquery.mousewheel.min.js"></script>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-color/2.1.2/jquery.color.min.js"></script>
-    <script src="fastapi-voyager-static/graphviz.svg.js<!-- VERSION_PLACEHOLDER -->"></script>
+    <script src="<!-- STATIC_PATH -->/graphviz.svg.js<!-- VERSION_PLACEHOLDER -->"></script>
     <!-- highlight.js minimal ES module load (python only) -->
     <link
       rel="stylesheet"
@@ -626,7 +623,7 @@
     </script>
     <script
       type="module"
-      src="fastapi-voyager-static/vue-main.js<!-- VERSION_PLACEHOLDER -->"
+      src="<!-- STATIC_PATH -->/vue-main.js<!-- VERSION_PLACEHOLDER -->"
     ></script>
 
     <!-- GA_SNIPPET -->

fastapi_voyager/web/store.js

@@ -2,6 +2,7 @@ const { reactive } = window.Vue
 
 const state = reactive({
   version: "",
+  framework_name: "",
   config: {
     initial_page_policy: "first",
     has_er_diagram: false,
@@ -305,6 +306,7 @@ const actions = {
       state.swagger.url = data.swagger_url || null
       state.config.has_er_diagram = data.has_er_diagram || false
       state.config.enable_pydantic_resolve_meta = data.enable_pydantic_resolve_meta || false
+      state.framework_name = data.framework_name || "API"
 
       this.rebuildSchemaOptions()