fastapi-voyager 0.6.1__tar.gz → 0.7.1__tar.gz

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-voyager
-Version: 0.6.1
+Version: 0.7.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
@@ -146,7 +146,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
@@ -162,37 +162,31 @@ features
 - [x] alt+click to show field details
 - [x] display source code of routes (including response_model)
 - [x] handle excluded field 
-- [ ] add tooltips
-- [ ] route
-    - [ ] group routes by module hierarchy
+- [x] add tooltips
+- [x] route
+    - [x] group routes by module hierarchy
     - [ ] add response_model in route
-- [ ] support dataclass
+- [ ] support dataclass (pending)
 - [ ] click field to highlight links
 - [ ] user can generate nodes/edges manually and connect to generated ones
     - [ ] add owner
 - [ ] ui optimization
     - [ ] fixed left/right bar show field information
-- [ ] display standard ER diagram
+- [ ] display standard ER diagram `difficult`
     - [ ] 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`
+
+bugs & non feature:
+- [x] fix duplicated link from class and parent class, it also break clicking highlight
 - [ ] add tests
 - [ ] refactor
     - [ ] abstract render module
-- [ ] export voyager core data into json (for better debugging)
-    - [ ] add api to rebuild core data from json, and render it
-- [ ] fix Generic case
-
-```python
-    class Paged(BaseModel, Generic[T]):
-    total: int
-    items: List[T]
-```
-
-bugs:
-- [ ] fix duplicated link from class and parent class, it also break clicking highlight
 
 ## Using with pydantic-resolve
 
@@ -205,3 +199,11 @@ TODO: ...
 
 - https://apis.guru/graphql-voyager/, for inspiration.
 - https://github.com/tintinweb/vscode-interactive-graphviz, for web visualization.
+
+
+## Changelog
+
+- 0.7.1:
+    - support brief mode, you can use `--module_prefix tests.service` to show links between routes and filtered schemas, to make the graph less complicated.
+- 0.6.2: 
+    - fix generic related issue

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/README.md

@@ -119,7 +119,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
@@ -135,37 +135,31 @@ features
 - [x] alt+click to show field details
 - [x] display source code of routes (including response_model)
 - [x] handle excluded field 
-- [ ] add tooltips
-- [ ] route
-    - [ ] group routes by module hierarchy
+- [x] add tooltips
+- [x] route
+    - [x] group routes by module hierarchy
     - [ ] add response_model in route
-- [ ] support dataclass
+- [ ] support dataclass (pending)
 - [ ] click field to highlight links
 - [ ] user can generate nodes/edges manually and connect to generated ones
     - [ ] add owner
 - [ ] ui optimization
     - [ ] fixed left/right bar show field information
-- [ ] display standard ER diagram
+- [ ] display standard ER diagram `difficult`
     - [ ] 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`
+
+bugs & non feature:
+- [x] fix duplicated link from class and parent class, it also break clicking highlight
 - [ ] add tests
 - [ ] refactor
     - [ ] abstract render module
-- [ ] export voyager core data into json (for better debugging)
-    - [ ] add api to rebuild core data from json, and render it
-- [ ] fix Generic case
-
-```python
-    class Paged(BaseModel, Generic[T]):
-    total: int
-    items: List[T]
-```
-
-bugs:
-- [ ] fix duplicated link from class and parent class, it also break clicking highlight
 
 ## Using with pydantic-resolve
 
@@ -178,3 +172,11 @@ TODO: ...
 
 - https://apis.guru/graphql-voyager/, for inspiration.
 - https://github.com/tintinweb/vscode-interactive-graphviz, for web visualization.
+
+
+## Changelog
+
+- 0.7.1:
+    - support brief mode, you can use `--module_prefix tests.service` to show links between routes and filtered schemas, to make the graph less complicated.
+- 0.6.2: 
+    - fix generic related issue

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/src/fastapi_voyager/cli.py

@@ -175,6 +175,12 @@ Examples:
         default="127.0.0.1",
         help="Host/IP for the preview server when --server is used (default: 127.0.0.1). Use 0.0.0.0 to listen on all interfaces."
     )
+    parser.add_argument(
+        "--module_prefix",
+        type=str,
+        default=None,
+        help="Prefix routes with module name when rendering brief view (only valid with --server)"
+    )
     
     parser.add_argument(
         "--version", "-v",
@@ -233,6 +239,9 @@ Examples:
             if not any(mc.startswith(key + ":") for mc in existing):
                 args.module_color = (args.module_color or []) + [d]
 
+    if args.module_prefix and not args.server:
+        parser.error("--module_prefix can only be used together with --server")
+
     # Validate required target if not demo
     if not args.demo and not (args.module_name or args.module):
         parser.error("You must provide a module file, -m module name, or use --demo")
@@ -272,7 +281,11 @@ 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, module_color=module_color)
+            app_server = viz_server.create_app_with_fastapi(
+                app,
+                module_color=module_color,
+                module_prefix=args.module_prefix,
+            )
             print(f"Starting preview server at http://{args.host}:{args.port} ... (Ctrl+C to stop)")
             uvicorn.run(app_server, host=args.host, port=args.port)
         else:

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/src/fastapi_voyager/filter.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
+from collections import deque
 from typing import Tuple
-from fastapi_voyager.type import Tag, Route, SchemaNode, Link
+from fastapi_voyager.type import Tag, Route, SchemaNode, Link, PK
 
 
 def filter_graph(
@@ -103,3 +104,85 @@ def filter_graph(
     _routes = [r for r in routes if r.id in included_ids]
 
     return _tags, _routes, _nodes, _links
+
+
+def filter_subgraph(
+    *,
+    tags: list[Tag],
+    routes: list[Route],
+    links: list[Link],
+    nodes: list[SchemaNode],
+    module_prefix: str
+) -> Tuple[list[Tag], list[Route], list[SchemaNode], list[Link]]:
+    """Collapse schema graph so routes link directly to nodes whose module matches ``module_prefix``.
+
+    The routine keeps tag→route links untouched, prunes schema nodes whose module does not start
+    with ``module_prefix``, and merges the remaining schema relationships so each route connects
+    directly to the surviving schema nodes. Traversal stops once a qualifying node is reached and
+    guards against cycles in the schema graph.
+    """
+
+    if not module_prefix:
+        # empty prefix keeps existing graph structure, so simply reuse incoming data
+        return tags, routes, nodes, [lk for lk in links if lk.type in ("tag_route", "route_to_schema")]
+
+    route_links = [lk for lk in links if lk.type == "route_to_schema"]
+    schema_links = [lk for lk in links if lk.type in {"schema", "parent", "subset"}]
+    tag_route_links = [lk for lk in links if lk.type == "tag_route"]
+
+    node_lookup: dict[str, SchemaNode] = {node.id: node for node in nodes}
+
+    filtered_nodes = [node for node in nodes if node_lookup[node.id].module.startswith(module_prefix)]
+    filtered_node_ids = {node.id for node in filtered_nodes}
+
+    adjacency: dict[str, list[str]] = {}
+    for link in schema_links:
+        if link.source_origin not in node_lookup or link.target_origin not in node_lookup:
+            continue
+        adjacency.setdefault(link.source_origin, [])
+        if link.target_origin not in adjacency[link.source_origin]:
+            adjacency[link.source_origin].append(link.target_origin)
+
+    merged_links: list[Link] = []
+    seen_pairs: set[tuple[str, str]] = set()
+
+    for link in route_links:
+        route_id = link.source_origin
+        start_node_id = link.target_origin
+        if route_id is None or start_node_id is None:
+            continue
+        if start_node_id not in node_lookup:
+            continue
+
+        visited: set[str] = set()
+        queue: deque[str] = deque([start_node_id])
+
+        while queue:
+            current = queue.popleft()
+            if current in visited:
+                continue
+            visited.add(current)
+
+            if current in filtered_node_ids:
+                key = (route_id, current)
+                if key not in seen_pairs:
+                    seen_pairs.add(key)
+                    merged_links.append(
+                        Link(
+                            source=link.source,
+                            source_origin=route_id,
+                            target=f"{current}::{PK}",
+                            target_origin=current,
+                            type="route_to_schema",
+                        )
+                    )
+                # stop traversing past a qualifying node
+                continue
+
+            for next_node in adjacency.get(current, () ):
+                if next_node not in visited:
+                    queue.append(next_node)
+
+    filtered_links = tag_route_links + merged_links
+
+    return tags, routes, filtered_nodes, filtered_links

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/src/fastapi_voyager/server.py

@@ -32,10 +32,12 @@ class Payload(BaseModel):
 	route_name: Optional[str] = None
 	show_fields: str = 'object'
 	show_meta: bool = False
+	brief: bool = False
 
 def create_route(
 	target_app: FastAPI,
 	module_color: dict[str, str] | None = None,
+	module_prefix: Optional[str] = None,
 ):
 	router = APIRouter(tags=['fastapi-voyager'])
 
@@ -73,7 +75,10 @@ def create_route(
 			load_meta=False,
 		)
 		voyager.analysis(target_app)
-		return voyager.render_dot()
+		if payload.brief:
+			return voyager.render_brief_dot(module_prefix=module_prefix)
+		else:
+			return voyager.render_dot()
 
 	@router.post("/dot-core-data", response_model=CoreData)
 	def get_filtered_dot_core_data(payload: Payload) -> str:
@@ -117,8 +122,9 @@ def create_app_with_fastapi(
 	target_app: FastAPI,
 	module_color: dict[str, str] | None = None,
 	gzip_minimum_size: int | None = 500,
+	module_prefix: Optional[str] = None,
 ) -> FastAPI:
-	router = create_route(target_app, module_color=module_color)
+	router = create_route(target_app, module_color=module_color, module_prefix=module_prefix)
 
 	app = FastAPI(title="fastapi-voyager demo server")
 	if gzip_minimum_size is not None and gzip_minimum_size >= 0:

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/src/fastapi_voyager/type_helper.py

@@ -1,7 +1,7 @@
 import inspect
 import os
 from pydantic import BaseModel
-from typing import get_origin, get_args, Union, Annotated, Any, Type
+from typing import get_origin, get_args, Union, Annotated, Any, Type, Generic
 from fastapi_voyager.type import FieldInfo
 from types import UnionType
 import pydantic_resolve.constant as const
@@ -142,7 +142,7 @@ def get_type_name(anno):
 
 
 def is_inheritance_of_pydantic_base(cls):
-    return safe_issubclass(cls, BaseModel) and cls is not BaseModel
+    return safe_issubclass(cls, BaseModel) and cls is not BaseModel and not is_generic_container(cls)
 
 
 def get_bases_fields(schemas: list[type[BaseModel]]) -> set[str]:
@@ -256,6 +256,27 @@ def update_forward_refs(kls):
         if safe_issubclass(shelled_type, BaseModel):
             update_pydantic_forward_refs(shelled_type)
 
+
+def is_generic_container(cls):
+    """
+    T = TypeVar('T')
+    class DataModel(BaseModel, Generic[T]):
+        data: T
+        id: int
+
+    type DataModelPageStory = DataModel[PageStory]
+
+    is_generic_container(DataModel) -> True
+    is_generic_container(DataModel[PageStory]) -> False
+
+    DataModel.__parameters__ == (T,)
+    DataModelPageStory.__parameters__ == (,)
+    """
+    try:
+        return (hasattr(cls, '__bases__') and Generic in cls.__bases__ and (hasattr(cls, '__parameters__') and bool(cls.__parameters__)))
+    except (TypeError, AttributeError):
+        return False
+
 if __name__ == "__main__":
     from tests.demo_anno import PageSprint, PageOverall
 

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/src/fastapi_voyager/version.py

@@ -1,2 +1,2 @@
 __all__ = ["__version__"]
-__version__ = "0.6.1"
+__version__ = "0.7.1"

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/src/fastapi_voyager/voyager.py

@@ -12,7 +12,7 @@ from fastapi_voyager.type_helper import (
 )
 from pydantic import BaseModel
 from fastapi_voyager.type import Route, SchemaNode, Link, Tag, LinkType, FieldType, PK, CoreData
-from fastapi_voyager.filter import filter_graph
+from fastapi_voyager.filter import filter_graph, filter_subgraph
 from fastapi_voyager.render import Renderer
 import pydantic_resolve.constant as const
 
@@ -271,4 +271,16 @@ class Voyager:
             node_set=self.node_set,
         )
         renderer = Renderer(show_fields=self.show_fields, module_color=self.module_color, schema=self.schema)
+        return renderer.render_dot(_tags, _routes, _nodes, _links)
+    
+    def render_brief_dot(self, module_prefix: str | None = None):
+        print(module_prefix)
+        _tags, _routes, _nodes, _links = filter_subgraph(
+            module_prefix=module_prefix,
+            tags=self.tags,
+            routes=self.routes,
+            nodes=self.nodes,
+            links=self.links,
+        )
+        renderer = Renderer(show_fields=self.show_fields, module_color=self.module_color, schema=None)
         return renderer.render_dot(_tags, _routes, _nodes, _links)

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/src/fastapi_voyager/web/index.html

@@ -109,6 +109,14 @@
             </div>
           </div>
 
+          <div class="col-auto">
+            <q-checkbox
+              v-model="state.brief"
+              label="Brief"
+              dense
+            />
+          </div>
+          
           <div class="col-auto">
             <q-btn-dropdown
               class="q-ml-md"

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/src/fastapi_voyager/web/vue-main.js

@@ -22,6 +22,7 @@ const app = createApp({
         { label: "Object fields", value: "object" },
         { label: "All fields", value: "all" },
       ],
+      brief: false,
       generating: false,
       rawTags: [], // [{ name, routes: [{ id, name }] }]
       rawSchemas: [], // [{ name, fullname }]
@@ -132,6 +133,7 @@ const app = createApp({
           schema_name: state.schemaFullname || null,
           route_name: state.routeId || null,
           show_fields: state.showFields,
+          brief: state.brief,
         };
 
         const res = await fetch("dot", {
@@ -179,6 +181,7 @@ const app = createApp({
           schema_name: state.schemaFullname || null,
           route_name: state.routeId || null,
           show_fields: state.showFields,
+          brief: state.brief,
         };
         const res = await fetch("dot-core-data", {
           method: "POST",
@@ -238,6 +241,7 @@ const app = createApp({
       state.routeId = "";
       state.schemaFullname = null;
       state.showFields = "object";
+      state.brief = false;
       await loadInitial();
     }
 

{fastapi_voyager-0.6.1 → fastapi_voyager-0.7.1}/tests/demo.py

@@ -69,6 +69,8 @@ class DataModel(BaseModel, Generic[T]):
     data: T
     id: int
 
-@app.get("/page_test_1/", tags=['for-page'], response_model=DataModel[PageStory])
+type DataModelPageStory = DataModel[PageStory]
+
+@app.get("/page_test_1/", tags=['for-page'], response_model=DataModelPageStory)
 def get_page_test_1():
     return {} # no implementation

fastapi_voyager-0.7.1/tests/test_filter.py

@@ -0,0 +1,134 @@
+from fastapi_voyager.filter import filter_subgraph
+from fastapi_voyager.type import Tag, Route, SchemaNode, Link, PK
+
+
+def _make_tag_route_link(tag: Tag, route: Route) -> Link:
+    return Link(
+        source=tag.id,
+        source_origin=tag.id,
+        target=route.id,
+        target_origin=route.id,
+        type="tag_route",
+    )
+
+
+def test_filter_subgraph_filters_nodes_and_links():
+    tag = Tag(id="tag1", name="Tag 1", routes=[])
+    route = Route(id="route1", name="route1", module="api.routes")
+    tag.routes.append(route)
+
+    node_a = SchemaNode(id="pkg.ModelA", name="ModelA", module="pkg.moduleA")
+    node_b = SchemaNode(id="pkg.ModelB", name="ModelB", module="target.moduleB")
+
+    links = [
+        _make_tag_route_link(tag, route),
+        Link(
+            source=route.id,
+            source_origin=route.id,
+            target=f"{node_a.id}::{PK}",
+            target_origin=node_a.id,
+            type="route_to_schema",
+        ),
+        Link(
+            source=f"{node_a.id}::ffield",
+            source_origin=node_a.id,
+            target=f"{node_b.id}::{PK}",
+            target_origin=node_b.id,
+            type="schema",
+        ),
+    ]
+
+    tags = [tag]
+    routes = [route]
+    nodes = [node_a, node_b]
+
+    _, _, filtered_nodes, filtered_links = filter_subgraph(
+        tags=tags,
+        routes=routes,
+        links=links,
+        nodes=nodes,
+        module_prefix="target",
+    )
+
+    assert filtered_nodes == [node_b]
+    assert any(
+        lk.type == "route_to_schema" and lk.source_origin == route.id and lk.target_origin == node_b.id
+        for lk in filtered_links
+    )
+    assert len(filtered_links) == 2  # tag -> route and merged route -> filtered node
+
+
+
+def test_filter_subgraph_handles_cycles_and_multiple_matches():
+    tag = Tag(id="tag-main", name="Tag", routes=[])
+    route = Route(id="route-main", name="route", module="api.routes")
+    tag.routes.append(route)
+
+    node_root = SchemaNode(id="pkg.Root", name="Root", module="pkg.root")
+    node_mid = SchemaNode(id="pkg.Mid", name="Mid", module="pkg.mid")
+    node_target1 = SchemaNode(id="pkg.Target1", name="Target1", module="target.mod.alpha")
+    node_target2 = SchemaNode(id="pkg.Target2", name="Target2", module="target.mod.beta")
+
+    links = [
+        _make_tag_route_link(tag, route),
+        Link(
+            source=route.id,
+            source_origin=route.id,
+            target=f"{node_root.id}::{PK}",
+            target_origin=node_root.id,
+            type="route_to_schema",
+        ),
+        Link(
+            source=f"{node_root.id}::ffield",
+            source_origin=node_root.id,
+            target=f"{node_mid.id}::{PK}",
+            target_origin=node_mid.id,
+            type="schema",
+        ),
+        Link(
+            source=f"{node_mid.id}::{PK}",
+            source_origin=node_mid.id,
+            target=f"{node_target1.id}::{PK}",
+            target_origin=node_target1.id,
+            type="parent",
+        ),
+        Link(
+            source=f"{node_mid.id}::ffield",
+            source_origin=node_mid.id,
+            target=f"{node_target2.id}::{PK}",
+            target_origin=node_target2.id,
+            type="subset",
+        ),
+        Link(
+            source=f"{node_target1.id}::ffield",
+            source_origin=node_target1.id,
+            target=f"{node_root.id}::{PK}",
+            target_origin=node_root.id,
+            type="schema",
+        ),
+    ]
+
+    nodes = [node_root, node_mid, node_target1, node_target2]
+
+    _, _, filtered_nodes, filtered_links = filter_subgraph(
+        tags=[tag],
+        routes=[route],
+        links=links,
+        nodes=nodes,
+        module_prefix="target.mod",
+    )
+
+    assert filtered_nodes == [node_target1, node_target2]
+
+    route_to_schema_targets = {
+        (lk.source_origin, lk.target_origin)
+        for lk in filtered_links
+        if lk.type == "route_to_schema"
+    }
+    assert route_to_schema_targets == {
+        (route.id, node_target1.id),
+        (route.id, node_target2.id),
+    }
+
+    assert all(lk.type in {"tag_route", "route_to_schema"} for lk in filtered_links)
+    assert len(filtered_links) == 3  # 1 tag_route + 2 merged links

fastapi_voyager-0.7.1/tests/test_generic.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel
+from typing import Generic, TypeVar
+from fastapi_voyager.type_helper import is_generic_container
+
+class PageStory(BaseModel):
+    id: int
+    title: str
+
+T = TypeVar('T')
+class DataModel(BaseModel, Generic[T]):
+    data: T
+    id: int
+
+type DataModelPageStory = DataModel[PageStory]
+
+def test_is_generic_container():
+    print(DataModelPageStory.__value__.__bases__)
+    print(DataModelPageStory.__value__.model_fields.items())
+    assert is_generic_container(DataModel) is True
+    assert is_generic_container(DataModelPageStory) is False