fastapi-voyager 0.8.2__tar.gz → 0.9.1__tar.gz

{fastapi_voyager-0.8.2 → fastapi_voyager-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-voyager
-Version: 0.8.2
+Version: 0.9.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
@@ -30,6 +30,10 @@ Description-Content-Type: text/markdown
 
 <p align="center"><img src="./voyager.jpg" alt="" /></p>
 
+
+[![IMAGE ALT TEXT](http://img.youtube.com/vi/PGlbQq1M-n8/0.jpg)](https://www.youtube.com/watch?v=PGlbQq1M-n8 "FastAPI Voyager")
+
+
 > This repo is still in early stage, currently it supports pydantic v2 only, previous name: fastapi-router-viz
 
 Inspect your API interactively
@@ -105,10 +109,10 @@ click a node to highlight it's upperstream and downstream nodes. figure out the
 
 ```python
 from fastapi import FastAPI
-from fastapi_voyager.server import create_app_with_fastapi
+from fastapi_voyager import create_voyager
 from tests.demo import app
 
-app.mount('/voyager', create_app_with_fastapi(
+app.mount('/voyager', create_voyager(
     app, 
     module_color={"tests.service": "red"}, 
     module_prefix="tests.service"))
@@ -164,7 +168,7 @@ or you can open router_viz.dot with vscode extension `graphviz interactive previ
 
 ## Plan before v1.0
 
-features:
+### features:
 - [x] group schemas by module hierarchy
 - [x] module-based coloring via Analytics(module_color={...})
 - [x] view in web browser
@@ -183,38 +187,62 @@ features:
 - [x] add tooltips
 - [x] route
     - [x] group routes by module hierarchy
-    - [ ] add response_model in route
-- [ ] support dataclass (pending)
-- [ ] click field to highlight links
+    - [x] add response_model in route
+- [x] fixed left bar show tag/ route
+- [x] export voyager core data into json (for better debugging)
+    - [x] add api to rebuild core data from json, and render it
+- [x] fix Generic case  `test_generic.py`
+- [x] show tips for routes not return pydantic type.
+- [x] fix duplicated link from class and parent class, it also break clicking highlight
+- [x] refactor: abstract render module
+
+### backlog
 - [ ] user can generate nodes/edges manually and connect to generated ones
     - [ ] add owner
     - [ ] add extra info for schema
-- [ ] ui optimization
-    - [ ] fixed left/right bar show field information
-    - [x] fixed left bar show tag/ route
-- [ ] display standard ER diagram `difference`
+- [ ] fixed left/right bar show field information
+- [ ] display standard ER diagram `hard`
     - [ ] display potential invalid links
-- [ ] integration with pydantic-resolve
-    - [ ] show difference between resolve, post fields
-    - [x] strikethrough for excluded fields
-    - [ ] display loader as edges
-- [x] export voyager core data into json (for better debugging)
-    - [x] add api to rebuild core data from json, and render it
-- [x] fix Generic case  `test_generic.py`
-- [ ] show tips for routes not return pydantic type.
-- [ ] add http method for route
 
 bugs & non feature:
-- [x] fix duplicated link from class and parent class, it also break clicking highlight
 - [ ] add tests
-- [x] refactor
-    - [x] abstract render module
+- [ ] support dataclass (pending)
+
+### in analysis
+- [ ] click field to highlight links
+- [ ] animation effect for edges
+- [ ] customrized right click panel
+    - [ ] show own dependencies
+
+### plan:
+
+#### 0.9
+- [x] refactor: server.py
+    - [x] rename create_app_with_fastapi -> create_voyager
+    - [x] add doc for parameters
+- [x] improve initialization time cost
+    - [x] query route / schema info through realtime api
+    - [x] adjust fe
+
+#### 0.10
+- [ ] logging information
+- [ ] open route in swagger
+    - config docs path
+- [ ] add http method for route
+- [ ] enable/disable module cluster  (may save space)
+
+#### 0.11
+- [ ] integration with pydantic-resolve
+    - [ ] show hint for resolve, post fields
+    - [ ] display loader as edges
+
 
 ## Using with pydantic-resolve
 
+WIP: ...
+
 pydantic-resolve's @ensure_subset decorator is helpful to pick fields from `source class` in safe.
 
-TODO: ...
 
 
 ## Credits
@@ -225,7 +253,13 @@ TODO: ...
 
 ## Changelog
 
+- 0.9:
+    - 0.9.1:
+        - api change: from `create_app_with_fastapi` to `create_voyager`, and expose as `from fastapi_voyager import create_voyager`
+        - optimization: lazy load vscode link and source code, speed up the initialization.
 - 0.8:
+    - 0.8.3
+        - upgrade theme
     - 0.8.2
         - fix silly typo.
     - 0.8.1

{fastapi_voyager-0.8.2 → fastapi_voyager-0.9.1}/README.md

@@ -3,6 +3,10 @@
 
 <p align="center"><img src="./voyager.jpg" alt="" /></p>
 
+
+[![IMAGE ALT TEXT](http://img.youtube.com/vi/PGlbQq1M-n8/0.jpg)](https://www.youtube.com/watch?v=PGlbQq1M-n8 "FastAPI Voyager")
+
+
 > This repo is still in early stage, currently it supports pydantic v2 only, previous name: fastapi-router-viz
 
 Inspect your API interactively
@@ -78,10 +82,10 @@ click a node to highlight it's upperstream and downstream nodes. figure out the
 
 ```python
 from fastapi import FastAPI
-from fastapi_voyager.server import create_app_with_fastapi
+from fastapi_voyager import create_voyager
 from tests.demo import app
 
-app.mount('/voyager', create_app_with_fastapi(
+app.mount('/voyager', create_voyager(
     app, 
     module_color={"tests.service": "red"}, 
     module_prefix="tests.service"))
@@ -137,7 +141,7 @@ or you can open router_viz.dot with vscode extension `graphviz interactive previ
 
 ## Plan before v1.0
 
-features:
+### features:
 - [x] group schemas by module hierarchy
 - [x] module-based coloring via Analytics(module_color={...})
 - [x] view in web browser
@@ -156,38 +160,62 @@ features:
 - [x] add tooltips
 - [x] route
     - [x] group routes by module hierarchy
-    - [ ] add response_model in route
-- [ ] support dataclass (pending)
-- [ ] click field to highlight links
+    - [x] add response_model in route
+- [x] fixed left bar show tag/ route
+- [x] export voyager core data into json (for better debugging)
+    - [x] add api to rebuild core data from json, and render it
+- [x] fix Generic case  `test_generic.py`
+- [x] show tips for routes not return pydantic type.
+- [x] fix duplicated link from class and parent class, it also break clicking highlight
+- [x] refactor: abstract render module
+
+### backlog
 - [ ] user can generate nodes/edges manually and connect to generated ones
     - [ ] add owner
     - [ ] add extra info for schema
-- [ ] ui optimization
-    - [ ] fixed left/right bar show field information
-    - [x] fixed left bar show tag/ route
-- [ ] display standard ER diagram `difference`
+- [ ] fixed left/right bar show field information
+- [ ] display standard ER diagram `hard`
     - [ ] display potential invalid links
-- [ ] integration with pydantic-resolve
-    - [ ] show difference between resolve, post fields
-    - [x] strikethrough for excluded fields
-    - [ ] display loader as edges
-- [x] export voyager core data into json (for better debugging)
-    - [x] add api to rebuild core data from json, and render it
-- [x] fix Generic case  `test_generic.py`
-- [ ] show tips for routes not return pydantic type.
-- [ ] add http method for route
 
 bugs & non feature:
-- [x] fix duplicated link from class and parent class, it also break clicking highlight
 - [ ] add tests
-- [x] refactor
-    - [x] abstract render module
+- [ ] support dataclass (pending)
+
+### in analysis
+- [ ] click field to highlight links
+- [ ] animation effect for edges
+- [ ] customrized right click panel
+    - [ ] show own dependencies
+
+### plan:
+
+#### 0.9
+- [x] refactor: server.py
+    - [x] rename create_app_with_fastapi -> create_voyager
+    - [x] add doc for parameters
+- [x] improve initialization time cost
+    - [x] query route / schema info through realtime api
+    - [x] adjust fe
+
+#### 0.10
+- [ ] logging information
+- [ ] open route in swagger
+    - config docs path
+- [ ] add http method for route
+- [ ] enable/disable module cluster  (may save space)
+
+#### 0.11
+- [ ] integration with pydantic-resolve
+    - [ ] show hint for resolve, post fields
+    - [ ] display loader as edges
+
 
 ## Using with pydantic-resolve
 
+WIP: ...
+
 pydantic-resolve's @ensure_subset decorator is helpful to pick fields from `source class` in safe.
 
-TODO: ...
 
 
 ## Credits
@@ -198,7 +226,13 @@ TODO: ...
 
 ## Changelog
 
+- 0.9:
+    - 0.9.1:
+        - api change: from `create_app_with_fastapi` to `create_voyager`, and expose as `from fastapi_voyager import create_voyager`
+        - optimization: lazy load vscode link and source code, speed up the initialization.
 - 0.8:
+    - 0.8.3
+        - upgrade theme
     - 0.8.2
         - fix silly typo.
     - 0.8.1

{fastapi_voyager-0.8.2 → fastapi_voyager-0.9.1}/src/fastapi_voyager/__init__.py

@@ -3,3 +3,7 @@
 Utilities to introspect a FastAPI application and visualize its routing tree.
 """
 from .version import __version__  # noqa: F401
+
+from .server import create_voyager
+
+__all__ = ["__version__", "create_voyager"]

{fastapi_voyager-0.8.2 → fastapi_voyager-0.9.1}/src/fastapi_voyager/cli.py

@@ -281,7 +281,7 @@ Examples:
             except ImportError:
                 print("Error: uvicorn is required to run the server. Install via 'pip install uvicorn' or 'uv add uvicorn'.")
                 sys.exit(1)
-            app_server = viz_server.create_app_with_fastapi(
+            app_server = viz_server.create_voyager(
                 app,
                 module_color=module_color,
                 module_prefix=args.module_prefix,

{fastapi_voyager-0.8.2 → fastapi_voyager-0.9.1}/src/fastapi_voyager/server.py

@@ -6,23 +6,18 @@ from pydantic import BaseModel
 from fastapi.responses import HTMLResponse, PlainTextResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
 from fastapi_voyager.voyager import Voyager
-from fastapi_voyager.type import Tag, FieldInfo, CoreData
+from fastapi_voyager.type import Tag, FieldInfo, CoreData, SchemaNode
 from fastapi_voyager.render import Renderer
+from fastapi_voyager.type_helper import get_source, get_vscode_link
 
 
 WEB_DIR = Path(__file__).parent / "web"
 WEB_DIR.mkdir(exist_ok=True)
 
-class SchemaType(BaseModel):
-	name: str
-	fullname: str
-	source_code: str
-	vscode_link: str
-	fields: list[FieldInfo]
 
 class OptionParam(BaseModel):
 	tags: list[Tag]
-	schemas: list[SchemaType]
+	schemas: list[SchemaNode]
 	dot: str
 
 class Payload(BaseModel):
@@ -40,26 +35,22 @@ def create_route(
 	module_color: dict[str, str] | None = None,
 	module_prefix: Optional[str] = None,
 ):
+	"""
+	module_color: dict mapping module name to color string, e.g. {'models': 'lightblue'}
+	module_prefix: prefix string to define schemas show in brief mode
+	"""
 	router = APIRouter(tags=['fastapi-voyager'])
 
 	@router.get("/dot", response_model=OptionParam)
 	def get_dot() -> str:
-		voyager = Voyager(module_color=module_color, load_meta=True)
+		voyager = Voyager(module_color=module_color)
 		voyager.analysis(target_app)
 		dot = voyager.render_dot()
 
 		# include tags and their routes
 		tags = voyager.tags
 
-		schemas = [
-			SchemaType(
-				name=s.name,
-				fullname=s.id,
-				fields=s.fields,
-				source_code=s.source_code,
-				vscode_link=s.vscode_link
-			) for s in voyager.nodes
-		]
+		schemas = voyager.nodes[:]
 		schemas.sort(key=lambda s: s.name)
 
 		return OptionParam(tags=tags, schemas=schemas, dot=dot)
@@ -74,7 +65,6 @@ def create_route(
 			show_fields=payload.show_fields,
 			module_color=module_color,
 			route_name=payload.route_name,
-			load_meta=False,
 			hide_primitive_route=payload.hide_primitive_route,
 		)
 		voyager.analysis(target_app)
@@ -92,7 +82,6 @@ def create_route(
 			show_fields=payload.show_fields,
 			module_color=module_color,
 			route_name=payload.route_name,
-			load_meta=False,
 		)
 		voyager.analysis(target_app)
 		return voyager.dump_core_data()
@@ -117,11 +106,90 @@ def create_route(
 		</body>
 		</html>
 		"""
+	
+	class SourcePayload(BaseModel):
+		schema_name: str
 
+	@router.post("/source")
+	def get_object_by_module_name(payload: SourcePayload):
+		"""
+		input: __module__ + __name__, eg: tests.demo.PageStories
+		output: source code of the object
+		"""
+		try:
+			components = payload.schema_name.split('.')
+			if len(components) < 2:
+				return JSONResponse(
+					status_code=400, 
+					content={"error": "Invalid schema name format. Expected format: module.ClassName"}
+				)
+			
+			module_name = '.'.join(components[:-1])
+			class_name = components[-1]
+			
+			mod = __import__(module_name, fromlist=[class_name])
+			obj = getattr(mod, class_name)
+			source_code = get_source(obj)
+			
+			return JSONResponse(content={"source_code": source_code})
+		except ImportError as e:
+			return JSONResponse(
+				status_code=404,
+				content={"error": f"Module not found: {e}"}
+			)
+		except AttributeError as e:
+			return JSONResponse(
+				status_code=404,
+				content={"error": f"Class not found: {e}"}
+			)
+		except Exception as e:
+			return JSONResponse(
+				status_code=500,
+				content={"error": f"Internal error: {str(e)}"}
+			)
+
+	@router.post("/vscode-link")
+	def get_vscode_link_by_module_name(payload: SourcePayload):
+		"""
+		input: __module__ + __name__, eg: tests.demo.PageStories
+		output: source path of the object
+		"""
+		try:
+			components = payload.schema_name.split('.')
+			if len(components) < 2:
+				return JSONResponse(
+					status_code=400, 
+					content={"error": "Invalid schema name format. Expected format: module.ClassName"}
+				)
+			
+			module_name = '.'.join(components[:-1])
+			class_name = components[-1]
+			
+			mod = __import__(module_name, fromlist=[class_name])
+			obj = getattr(mod, class_name)
+			link = get_vscode_link(obj)
+			
+			return JSONResponse(content={"link": link})
+		except ImportError as e:
+			return JSONResponse(
+				status_code=404,
+				content={"error": f"Module not found: {e}"}
+			)
+		except AttributeError as e:
+			return JSONResponse(
+				status_code=404,
+				content={"error": f"Class not found: {e}"}
+			)
+		except Exception as e:
+			return JSONResponse(
+				status_code=500,
+				content={"error": f"Internal error: {str(e)}"}
+			)
+        
 	return router
 
 
-def create_app_with_fastapi(
+def create_voyager(
 	target_app: FastAPI,
 	module_color: dict[str, str] | None = None,
 	gzip_minimum_size: int | None = 500,

{fastapi_voyager-0.8.2 → fastapi_voyager-0.9.1}/src/fastapi_voyager/type.py

@@ -22,8 +22,6 @@ class Tag(NodeBase):
 @dataclass
 class Route(NodeBase):
     module: str
-    source_code: str = ''
-    vscode_link: str = ''  # optional vscode deep link
     response_schema: str = ''
     is_primitive: bool = True
 
@@ -37,8 +35,6 @@ class ModuleRoute:
 @dataclass
 class SchemaNode(NodeBase):
     module: str
-    source_code: str = ''  # optional for tests / backward compatibility
-    vscode_link: str = ''  # optional vscode deep link
     fields: list[FieldInfo] = field(default_factory=list)
 
 @dataclass

{fastapi_voyager-0.8.2 → fastapi_voyager-0.9.1}/src/fastapi_voyager/version.py

@@ -1,2 +1,2 @@
 __all__ = ["__version__"]
-__version__ = "0.8.2"
+__version__ = "0.9.1"

{fastapi_voyager-0.8.2 → fastapi_voyager-0.9.1}/src/fastapi_voyager/voyager.py

@@ -29,7 +29,6 @@ class Voyager:
             module_color: dict[str, str] | None = None,
             route_name: str | None = None,
             hide_primitive_route: bool = False,
-            load_meta: bool = False
         ):
 
         self.routes: list[Route] = []
@@ -50,7 +49,6 @@ class Voyager:
         self.show_fields = show_fields if show_fields in ('single','object','all') else 'object'
         self.module_color = module_color or {}
         self.route_name = route_name
-        self.load_meta = load_meta
         self.hide_primitive_route = hide_primitive_route
     
 
@@ -85,7 +83,7 @@ class Voyager:
                 self.tags.append(tag_obj)
 
             # add route and create links
-            route_id = f'{route.endpoint.__name__}_{route.path.replace("/", "_")}'
+            route_id = full_class_name(route.endpoint)
             route_name = route.endpoint.__name__
             route_module = route.endpoint.__module__
 
@@ -110,8 +108,6 @@ class Voyager:
                 id=route_id,
                 name=route_name,
                 module=route_module,
-                vscode_link=get_vscode_link(route.endpoint) if self.load_meta else '',
-                source_code=inspect.getsource(route.endpoint) if self.load_meta else '',
                 response_schema=get_type_name(route.response_model),
                 is_primitive=is_primitive_response
             )
@@ -154,8 +150,6 @@ class Voyager:
                 id=full_name, 
                 module=schema.__module__,
                 name=schema.__name__,
-                source_code=get_source(schema) if self.load_meta else '',
-                vscode_link=get_vscode_link(schema) if self.load_meta else '',
                 fields=get_pydantic_fields(schema, bases_fields)
             )
         return full_name

fastapi_voyager-0.9.1/src/fastapi_voyager/web/component/route-code-display.js

@@ -0,0 +1,135 @@
+const { defineComponent, ref, watch, onMounted } = window.Vue;
+
+// Component: RouteCodeDisplay
+// Props:
+//   routeId: route id key in routeItems
+//   modelValue: dialog visibility
+//   routes: object map { id: { id, name, source_code } }
+export default defineComponent({
+  name: "RouteCodeDisplay",
+  props: {
+    routeId: { type: String, required: true },
+    modelValue: { type: Boolean, default: false },
+    routes: { type: Object, default: () => ({}) },
+  },
+  emits: ["close"],
+  setup(props, { emit }) {
+    const loading = ref(false);
+    const code = ref("");
+    const error = ref("");
+    const link = ref("");
+
+    function close() {
+      emit("close");
+    }
+
+    function highlightLater() {
+      requestAnimationFrame(() => {
+        try {
+          if (window.hljs) {
+            const block = document.querySelector(
+              ".frv-route-code-display pre code.language-python"
+            );
+            if (block) {
+              window.hljs.highlightElement(block);
+            }
+          }
+        } catch (e) {
+          console.warn("highlight failed", e);
+        }
+      });
+    }
+
+    async function load() {
+      if (!props.routeId) {
+        code.value = "";
+        return;
+      }
+
+      loading.value = true;
+      error.value = null;
+      code.value = "";
+      link.value = "";
+
+      // try to fetch from server: POST /source with { schema_name: routeId }
+      const payload = { schema_name: props.routeId };
+      try {
+        const resp = await fetch(`source`, {
+          method: "POST",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify(payload),
+        });
+
+        const data = await resp.json().catch(() => ({}));
+        if (resp.ok) {
+          code.value = data.source_code || "// no source code available";
+        } else {
+          error.value = (data && data.error) || "Failed to load source";
+        }
+      } catch (e) {
+        error.value = e && e.message ? e.message : "Failed to load source";
+      } finally {
+        loading.value = false;
+      }
+
+      try {
+        const resp = await fetch(`vscode-link`, {
+          method: "POST",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify(payload),
+        });
+
+        const data = await resp.json().catch(() => ({}));
+        if (resp.ok) {
+          link.value = data.link || "// no source code available";
+        } else {
+          error.value += (data && data.error) || "Failed to load vscode link";
+        }
+      } catch (e) {
+      } finally {
+        loading.value = false;
+      }
+
+      if (!error.value) {
+        highlightLater();
+      }
+    }
+
+    watch(
+      () => props.modelValue,
+      (v) => {
+        if (v) load();
+      }
+    );
+    watch(
+      () => props.routeId,
+      () => {
+        if (props.modelValue) load();
+      }
+    );
+
+    onMounted(() => {
+      if (props.modelValue) load();
+    });
+
+    return { loading, code, error, close, link };
+  },
+  template: `
+  <div class="frv-route-code-display" style="border:1px solid #ccc; position:relative; width:50vw; max-width:50vw; height:100%; background:#fff;">
+    <q-btn dense flat round icon="close" @click="close" aria-label="Close" style="position:absolute; top:6px; right:6px; z-index:10; background:rgba(255,255,255,0.85)" />
+    <div v-if="link" class="q-ml-md q-mt-md" style="padding-top:4px;">
+      <a :href="link" target="_blank" rel="noopener" style="font-size:12px; color:#3b82f6;">Open in VSCode</a>
+    </div>
+    <div style="padding:40px 16px 16px 16px; height:100%; box-sizing:border-box; overflow:auto;">
+      <div v-if="loading" style="font-family:Menlo, monospace; font-size:12px;">Loading source...</div>
+      <div v-else-if="error" style="color:#c10015; font-family:Menlo, monospace; font-size:12px;">{{ error }}</div>
+      <pre v-else style="margin:0;"><code class="language-python">{{ code }}</code></pre>
+    </div>
+  </div>`,
+});