fastapi-voyager 0.4.2__tar.gz → 0.4.4__tar.gz

{fastapi_voyager-0.4.2 → fastapi_voyager-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-voyager
-Version: 0.4.2
+Version: 0.4.4
 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
@@ -144,9 +144,9 @@ dot -Tpng router_viz.dot -o router_viz.png
 or you can open router_viz.dot with vscode extension `graphviz interactive preview`
 
 
-## Plan
+## 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,18 +162,30 @@ features:
 - [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
+- [ ] support dataclass
+- [ ] user can generate nodes/edges manually and connect to generated ones
+- [ ] refactor
+    - [ ] abstract render module
+- [ ] ui optimization
+    - [ ] fixed left/right bar show field information
+- [ ] display standard ER diagram
+    - [ ] display potential invalid links
 - [ ] integration with pydantic-resolve
     - [ ] show difference between resolve, post fields
     - [x] strikethrough for excluded fields
     - [ ] display loader as edges
-- [ ] test cases
+- [ ] add tests
 
 bugs:
 - [ ] fix duplicated link from class and parent class, it also break clicking highlight
 
+## Using with pydantic-resolve
+
+pydantic-resolve's @ensure_subset decorator is helpful to pick fields from `source class` in safe.
+
+TODO: ...
+
 
 ## Credits
 

{fastapi_voyager-0.4.2 → fastapi_voyager-0.4.4}/README.md

@@ -117,9 +117,9 @@ dot -Tpng router_viz.dot -o router_viz.png
 or you can open router_viz.dot with vscode extension `graphviz interactive preview`
 
 
-## Plan
+## 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,18 +135,30 @@ features:
 - [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
+- [ ] support dataclass
+- [ ] user can generate nodes/edges manually and connect to generated ones
+- [ ] refactor
+    - [ ] abstract render module
+- [ ] ui optimization
+    - [ ] fixed left/right bar show field information
+- [ ] display standard ER diagram
+    - [ ] display potential invalid links
 - [ ] integration with pydantic-resolve
     - [ ] show difference between resolve, post fields
     - [x] strikethrough for excluded fields
     - [ ] display loader as edges
-- [ ] test cases
+- [ ] add tests
 
 bugs:
 - [ ] fix duplicated link from class and parent class, it also break clicking highlight
 
+## Using with pydantic-resolve
+
+pydantic-resolve's @ensure_subset decorator is helpful to pick fields from `source class` in safe.
+
+TODO: ...
+
 
 ## Credits
 

{fastapi_voyager-0.4.2 → fastapi_voyager-0.4.4}/src/fastapi_voyager/graph.py

@@ -12,7 +12,7 @@ from fastapi_voyager.type_helper import (
     update_forward_refs
 )
 from pydantic import BaseModel
-from fastapi_voyager.type import Route, SchemaNode, Link, Tag, ModuleNode
+from fastapi_voyager.type import Route, SchemaNode, Link, Tag, ModuleNode, LinkType
 from fastapi_voyager.module import build_module_tree
 from fastapi_voyager.filter import filter_graph
 
@@ -112,7 +112,6 @@ class Analytics:
             # add response_models and create links from route -> response_model
             for schema in get_core_types(route.response_model):
                 if schema and issubclass(schema, BaseModel):
-                    update_forward_refs(schema)
                     target_name = full_class_name(schema)
                     self.links.append(Link(
                         source=route_id,
@@ -157,7 +156,8 @@ class Analytics:
             source_origin: str,
             target: str, 
             target_origin: str,
-            type: Literal['child', 'parent', 'subset']):
+            type: LinkType
+        ) -> bool:
         """
         1. add link to link_set
         2. if duplicated, do nothing, else insert
@@ -182,6 +182,7 @@ class Analytics:
         3. recursively run walk_schema
         """
         
+        update_forward_refs(schema)
         self.add_to_node_set(schema)
 
         # handle schema inside ensure_subset(schema)
@@ -262,17 +263,22 @@ class Analytics:
 
     def generate_dot(self):
 
+        def generate_link(link: Link):
+            if link.type == 'internal':
+                return f'''{handle_entry(link.source)}:e -> {handle_entry(link.target)}:w [ {get_link_attributes(link)} ];'''
+            else:
+                return f'''{handle_entry(link.source)} -> {handle_entry(link.target)} [ {get_link_attributes(link)} ];'''
+
+
         def get_link_attributes(link: Link):
-            if link.type == 'child':
-                return 'style = "dashed", label = "", minlen=3'
-            elif link.type == 'parent':
-                return 'style = "solid", dir="back", minlen=3, taillabel = "< inherit >", color = "purple", tailport="n"'
+            if link.type == 'parent':
+                return 'style = "solid, dashed", dir="back", minlen=3, taillabel = "< inherit >", color = "purple", tailport="n"'
             elif link.type == 'entry':
-                return 'style = "solid", label = "", minlen=3'
+                return 'style = "solid", label = "", minlen=3, tailport="e", headport="w"'
             elif link.type == 'subset':
-                return 'style = "solid", dir="back", minlen=3, taillabel = "< subset >", color = "orange", tailport="n"'
+                return 'style = "solid, dashed", dir="back", minlen=3, taillabel = "< subset >", color = "orange", tailport="n"'
 
-            return 'style = "solid", arrowtail="odiamond", dir="back", minlen=3'
+            return 'style = "solid", arrowtail="odot", dir="back", minlen=3'
 
         def render_module(mod: ModuleNode):
             color = self.module_color.get(mod.fullname)
@@ -296,7 +302,7 @@ class Analytics:
                 style="rounded"
                 label = "  {mod.name}"
                 labeljust = "l"
-                {(f'pencolor = "{color}"' if color else 'pencolor=""')}
+                {(f'pencolor = "{color}"' if color else 'pencolor="#ccc"')}
                 {(f'penwidth = 3' if color else 'penwidth=""')}
                 {inner_nodes_str}
                 {child_str}
@@ -340,9 +346,7 @@ class Analytics:
 
         modules_str = '\n'.join(render_module(m) for m in _modules)
 
-        links = [
-            f'''{handle_entry(link.source)} -> {handle_entry(link.target)} [ {get_link_attributes(link)} ];''' for link in _links
-        ]
+        links = [ generate_link(link) for link in _links ]
         link_str = '\n'.join(links)
 
         template = f'''
@@ -376,7 +380,7 @@ class Analytics:
                 color = "#aaa"
                 margin=18
                 style="dashed"
-                label = "  Route apis"
+                label = "  Routes"
                 labeljust = "l"
                 fontsize = "20"
                 {route_str}

{fastapi_voyager-0.4.2 → fastapi_voyager-0.4.4}/src/fastapi_voyager/type.py

@@ -1,6 +1,10 @@
 from dataclasses import dataclass, field
 from typing import Literal
 
+@dataclass
+class NodeBase:
+    id: str
+    name: str
 
 @dataclass
 class FieldInfo:
@@ -11,23 +15,17 @@ class FieldInfo:
     is_exclude: bool = False
 
 @dataclass
-class Tag:
-    id: str
-    name: str
+class Tag(NodeBase):
     routes: list['Route']  # route.id
 
 @dataclass
-class Route:
-    id: str
-    name: str
+class Route(NodeBase):
     source_code: str = ''
     vscode_link: str = ''  # optional vscode deep link
 
 @dataclass
-class SchemaNode:
-    id: str
+class SchemaNode(NodeBase):
     module: str
-    name: str
     source_code: str = ''  # optional for tests / backward compatibility
     vscode_link: str = ''  # optional vscode deep link
     fields: list[FieldInfo] = field(default_factory=list)
@@ -39,10 +37,21 @@ class ModuleNode:
     schema_nodes: list[SchemaNode]
     modules: list['ModuleNode']
 
+
+# type: 
+#    - entry: tag -> route, route -> response model
+#    - subset: schema -> schema (subset)
+#    - parent: schema -> schema (inheritance)
+#    - internal: schema -> schema (field reference)
+LinkType = Literal['internal', 'parent', 'entry', 'subset']
+
 @dataclass
 class Link:
+    # node + field level links
     source: str
-    source_origin: str  # internal relationship
     target: str
+
+    # node level links
+    source_origin: str
     target_origin: str
-    type: Literal['child', 'parent', 'entry', 'subset']
+    type: LinkType

{fastapi_voyager-0.4.2 → fastapi_voyager-0.4.4}/src/fastapi_voyager/type_helper.py

@@ -4,6 +4,7 @@ from pydantic import BaseModel
 from typing import get_origin, get_args, Union, Annotated, Any, Type
 from fastapi_voyager.type import FieldInfo
 from types import UnionType
+import pydantic_resolve.constant as const
 
 # Python <3.12 compatibility: TypeAliasType exists only from 3.12 (PEP 695)
 try:  # pragma: no cover - import guard
@@ -14,24 +15,10 @@ except Exception:  # pragma: no cover
     TypeAliasType = _DummyTypeAliasType  # type: ignore
 
 
-def _is_optional(annotation):
-    origin = get_origin(annotation)
-    args = get_args(annotation)
-    if origin is Union and type(None) in args:
-        return True
-    return False
-
-
-def _is_list(annotation):
+def is_list(annotation):
     return getattr(annotation, "__origin__", None) == list
 
 
-def shelling_type(type):
-    while _is_optional(type) or _is_list(type):
-        type = type.__args__[0]
-    return type
-
-
 def full_class_name(cls):
     return f"{cls.__module__}.{cls.__qualname__}"
 
@@ -41,12 +28,9 @@ def get_core_types(tp):
     - get the core type
     - always return a tuple of core types
     """
-    if tp is type(None):
-        return tuple()
-
-    # Unwrap PEP 695 type aliases (they wrap the actual annotation in __value__)
-    # Repeat in case of nested aliasing.
+    # Helpers
     def _unwrap_alias(t):
+        """Unwrap PEP 695 type aliases by following __value__ repeatedly."""
         while isinstance(t, TypeAliasType) or (
             t.__class__.__name__ == 'TypeAliasType' and hasattr(t, '__value__')
         ):
@@ -56,47 +40,54 @@ def get_core_types(tp):
                 break
         return t
 
-    tp = _unwrap_alias(tp)
+    def _enqueue(items, q):
+        for it in items:
+            if it is not type(None):  # skip None in unions
+                q.append(it)
 
-    # 1. Unwrap list layers
-    def _shell_list(_tp):
-        while _is_list(_tp):
-            args = getattr(_tp, "__args__", ())
-            if args:
-                _tp = args[0]
-            else:
-                break
-        return _tp
-    
-    tp = _shell_list(tp)
+    # Queue-based shelling to reach concrete core types
+    queue: list[object] = [tp]
+    result: list[object] = []
 
-    # Alias could wrap a list element, unwrap again
-    tp = _unwrap_alias(tp)
+    while queue:
+        cur = queue.pop(0)
+        if cur is type(None):
+            continue
 
-    if tp is type(None): # check again
-        return tuple()
+        cur = _unwrap_alias(cur)
 
-    while True:
-        orig = get_origin(tp)
+        # Handle Annotated[T, ...] as a shell
+        if get_origin(cur) is Annotated:
+            args = get_args(cur)
+            if args:
+                queue.append(args[0])
+            continue
 
+        # Handle Union / Optional / PEP 604 UnionType
+        orig = get_origin(cur)
         if orig in (Union, UnionType):
-            args = list(get_args(tp))
-            non_none = [a for a in args if a is not type(None)]  # noqa: E721
-            has_none = len(non_none) != len(args)
-            # Optional[T] case -> keep unwrapping (exactly one real type + None)
-            if has_none and len(non_none) == 1:
-                tp = non_none[0]
-                tp = _unwrap_alias(tp)
-                tp = _shell_list(tp)
-                continue
-            # General union: return all non-None members (order preserved)
-            if non_none:
-                return tuple(non_none)
-            return tuple()
-        break
-
-    # single concrete type
-    return (tp,)
+            args = get_args(cur)
+            # push all non-None members back for further shelling
+            _enqueue(args, queue)
+            continue
+
+        # Handle list shells
+        if is_list(cur):
+            args = getattr(cur, "__args__", ())
+            if args:
+                queue.append(args[0])
+            continue
+
+        # If still an alias-like wrapper, unwrap again and re-process
+        _cur2 = _unwrap_alias(cur)
+        if _cur2 is not cur:
+            queue.append(_cur2)
+            continue
+
+        # Otherwise treat as a concrete core type (could be a class, typing.Final, etc.)
+        result.append(cur)
+
+    return tuple(result)
 
 
 def get_type_name(anno):
@@ -149,8 +140,9 @@ def get_type_name(anno):
 
     return name_of(anno)
 
+
 def is_inheritance_of_pydantic_base(cls):
-        return issubclass(cls, BaseModel) and cls is not BaseModel
+    return issubclass(cls, BaseModel) and cls is not BaseModel
 
 
 def get_bases_fields(schemas: list[type[BaseModel]]) -> set[str]:
@@ -240,15 +232,31 @@ def safe_issubclass(kls, classinfo):
 
 
 def update_forward_refs(kls):
-    def update_pydantic_forward_refs(kls: Type[BaseModel]):
+    # TODO: refactor
+    def update_pydantic_forward_refs(kls2: Type[BaseModel]):
         """
         recursively update refs.
         """
-        kls.model_rebuild()
-        values = kls.model_fields.values()
+
+        kls2.model_rebuild()
+        setattr(kls2, const.PYDANTIC_FORWARD_REF_UPDATED, True)
+
+        values = kls2.model_fields.values()
         for field in values:
             update_forward_refs(field.annotation)
 
-    for shelled_types in get_core_types(kls):
-        if safe_issubclass(shelled_types, BaseModel):
-            update_pydantic_forward_refs(shelled_types)
+    if safe_issubclass(kls, BaseModel):
+        kls.model_rebuild()
+        setattr(kls, const.PYDANTIC_FORWARD_REF_UPDATED, True)
+        
+    for shelled_type in get_core_types(kls):
+        if getattr(shelled_type, const.PYDANTIC_FORWARD_REF_UPDATED, False):
+            continue
+        if safe_issubclass(shelled_type, BaseModel):
+            update_pydantic_forward_refs(shelled_type)
+
+if __name__ == "__main__":
+    from tests.demo_anno import PageSprint, PageOverall
+
+    update_forward_refs(PageOverall)
+    update_forward_refs(PageSprint)

{fastapi_voyager-0.4.2 → fastapi_voyager-0.4.4}/src/fastapi_voyager/version.py

@@ -1,2 +1,2 @@
 __all__ = ["__version__"]
-__version__ = "0.4.2"
+__version__ = "0.4.4"

{fastapi_voyager-0.4.2 → fastapi_voyager-0.4.4}/tests/demo_anno.py

@@ -12,6 +12,11 @@ app = FastAPI(title="Demo API", description="A demo FastAPI application for rout
 def get_sprint():
     return []
 
+class Tree(BaseModel):
+    id: int
+    name: str
+    children: list[Tree] = []
+
 class PageMember(serv.Member):
     fullname: str = ''
     def post_fullname(self):
@@ -62,4 +67,8 @@ class PageStories(BaseModel):
 
 @app.get("/page_info/", tags=['for-page'], response_model=PageStories)
 def get_page_stories():
+    return {} # no implementation
+
+@app.get("/rest-tree/", tags=['for-restapi'], response_model=Tree)
+def get_tree():
     return {} # no implementation

fastapi_voyager-0.4.4/tests/test_type_helper.py

@@ -0,0 +1,99 @@
+import sys
+import typing
+import pytest
+
+from fastapi_voyager.type_helper import get_core_types
+
+
+def test_optional_and_list_core_types():
+    class T: ...
+
+    # Optional[T] -> (T,)
+    opt = typing.Optional[T]
+    core = get_core_types(opt)
+    assert core == (T,)
+
+    # list[T] -> (T,)
+    lst = list[T]
+    core2 = get_core_types(lst)
+    assert core2 == (T,)
+
+
+def test_typing_union_core_types():
+    class A: ...
+    class B: ...
+
+    u = typing.Union[A, B]
+    core = get_core_types(u)
+    # order preserved
+    assert core == (A, B)
+
+
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="PEP 604 union (|) requires Python 3.10+")
+def test_uniontype_pep604_core_types():
+    class A: ...
+    class B: ...
+
+    u = A | B
+    core = get_core_types(u)
+    assert core == (A, B)
+
+
+def test_mixed_optional_list():
+    class T: ...
+
+    # Optional[list[T]] -> (T,) (list unwrapped after removing None)
+    anno = typing.Optional[list[T]]
+    core = get_core_types(anno)
+    assert core == (T,)
+
+
+def test_nested_union_flattening():
+    class A: ...
+    class B: ...
+    class C: ...
+
+    anno = typing.Union[A, typing.Union[B, C]]
+    core = get_core_types(anno)
+    # typing normalizes nested unions -> (A, B, C)
+    assert core == (A, B, C)
+
+
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="PEP 604 union (|) requires Python 3.10+")
+def test_uniontype_with_list_member():
+    class A: ...
+    class B: ...
+
+    anno = A | list[B]
+    anno2 = A | list[list[B]]
+    core = get_core_types(anno)
+    core2 = get_core_types(anno2)
+    assert core == (A, B)
+    assert core2 == (A, B)
+
+
+
+
+# Only Python 3.12+ supports the PEP 695 `type` statement producing TypeAliasType
+@pytest.mark.skipif(sys.version_info < (3, 12), reason="PEP 695 type aliases require Python 3.12+")
+def test_union_type_alias_and_list():
+    # Dynamically exec a type alias using the new syntax so test file stays valid on <3.12 (even though skipped)
+    ns: dict = {}
+    code = """
+class A: ...
+class B: ...
+
+type MyAlias = A | B
+"""
+    exec(code, ns, ns)
+    MyAlias = ns['MyAlias']
+    A = ns['A']
+    B = ns['B']
+
+    # list[MyAlias] should yield (A, B)
+    core = get_core_types(list[MyAlias])
+    assert set(core) == {A, B}
+
+    # Direct alias should also work
+    core2 = get_core_types(MyAlias)
+    assert set(core2) == {A, B}

fastapi_voyager-0.4.2/tests/test_type_alias.py

@@ -1,30 +0,0 @@
-import sys
-import pytest
-from typing import get_args, get_origin
-
-from fastapi_voyager.type_helper import get_core_types
-
-# Only Python 3.12+ supports the PEP 695 `type` statement producing TypeAliasType
-pytestmark = pytest.mark.skipif(sys.version_info < (3, 12), reason="PEP 695 type aliases require Python 3.12+")
-
-def test_union_type_alias_and_list():
-    # Dynamically exec a type alias using the new syntax so test file stays valid on <3.12 (even though skipped)
-    ns: dict = {}
-    code = """
-class A: ...
-class B: ...
-
-type MyAlias = A | B
-"""
-    exec(code, ns, ns)
-    MyAlias = ns['MyAlias']
-    A = ns['A']
-    B = ns['B']
-
-    # list[MyAlias] should yield (A, B)
-    core = get_core_types(list[MyAlias])
-    assert set(core) == {A, B}
-
-    # Direct alias should also work
-    core2 = get_core_types(MyAlias)
-    assert set(core2) == {A, B}