fastapi-voyager 0.13.1__tar.gz → 0.13.3__tar.gz

{fastapi_voyager-0.13.1 → fastapi_voyager-0.13.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-voyager
-Version: 0.13.1
+Version: 0.13.3
 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
@@ -35,11 +35,12 @@ Visualize your FastAPI endpoints, and explore them interactively.
 
 > This repo is still in early stage, it supports pydantic v2 only
 
-[live demo](https://www.newsyeah.fun/voyager/) of project: [composition oriented development pattern](https://github.com/allmonday/composition-oriented-development-pattern)
+visit [live demo](https://www.newsyeah.fun/voyager/) 
+source code:[composition oriented development pattern](https://github.com/allmonday/composition-oriented-development-pattern)
 
-<img width="1600" height="986" alt="image" src="https://github.com/user-attachments/assets/8829cda0-f42d-4c84-be2f-b019bb5fe7e1" />
+<img width="1597" height="933" alt="image" src="https://github.com/user-attachments/assets/020bf5b2-6c69-44bf-ba1f-39389d388d27" />
 
-with configuration:
+with simple configuration it can be embedded into FastAPI.
 
 ```python
 app.mount('/voyager', 
@@ -67,6 +68,8 @@ pip install fastapi-voyager
 uv add fastapi-voyager
 ```
 
+run with cli:
+
 ```shell
 voyager -m path.to.your.app.module --server
 ```
@@ -77,47 +80,81 @@ voyager -m path.to.your.app.module --server
 voyager -m path.to.your.app.module --server --app api
 ```
 
-## Mount into project
-
-```python
-from fastapi import FastAPI
-from fastapi_voyager import create_voyager
-from tests.demo import app
-
-app.mount('/voyager', create_voyager(
-    app, 
-    module_color={"tests.service": "red"}, 
-    module_prefix="tests.service"),
-    swagger_url="/docs")
-```
 
 ## Features
 
 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 during design phase before turly implemtatioin.
+It is also an architecture tool that can identify issues inside implementation, finding out wrong relationships, overfetchs, or anything else.
+
+**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
 
-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
+Given ErDiagram defined by pydantic-resolve, application level entity relationship diagram can be visualized too.
 
 ### highlight nodes and links
 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="1100" height="700" alt="image" src="https://github.com/user-attachments/assets/3e0369ea-5fa4-469a-82c1-ed57d407e53d" />
 
-### focus on nodes
-
-Double click a node, and then toggle focus to hide irrelevant nodes.
-
-<img width="1061" height="937" alt="image" src="https://github.com/user-attachments/assets/79709b02-7571-43fc-abc9-17a287a97515" />
-
 ### view source code
 
 double click a node or route to show source code or open file in vscode.
 
 <img width="1297" height="940" alt="image" src="https://github.com/user-attachments/assets/c8bb2e7d-b727-42a6-8c9e-64dce297d2d8" />
 
-<img width="1132" height="824" alt="image" src="https://github.com/user-attachments/assets/b706e879-e4fc-48dd-ace1-99bf97e3ed6a" />
+### quick search
+
+seach schemas by name and dispaly it's upstream and downstreams.
+
+shift + click can quickly search current one
+
+<img width="1587" height="873" alt="image" src="https://github.com/user-attachments/assets/ee4716f3-233d-418f-bc0e-3b214d1498f7" />
+
+### display ER diagram
+
+ER diagram is a new feature from pydantic-resolve which provide a solid expression for business descritpions. 
+
+```python
+diagram = ErDiagram(
+    configs=[
+        Entity(
+            kls=Team,
+            relationships=[
+                Relationship( field='id', target_kls=list[Sprint], loader=sprint_loader.team_to_sprint_loader),
+                Relationship( field='id', target_kls=list[User], loader=user_loader.team_to_user_loader)
+            ]
+        ),
+        Entity(
+            kls=Sprint,
+            relationships=[
+                Relationship( field='id', target_kls=list[Story], loader=story_loader.sprint_to_story_loader)
+            ]
+        ),
+        Entity(
+            kls=Story,
+            relationships=[
+                Relationship( field='id', target_kls=list[Task], loader=task_loader.story_to_task_loader),
+                Relationship( field='owner_id', target_kls=User, loader=user_loader.user_batch_loader)
+            ]
+        ),
+        Entity(
+            kls=Task,
+            relationships=[
+                Relationship( field='owner_id', target_kls=User, loader=user_loader.user_batch_loader)
+            ]
+        )
+    ]
+)
+
+# display in voyager
+app.mount('/voyager', 
+          create_voyager(
+            app,
+            er_diagram=diagram)
+```
+
+<img width="1276" height="613" alt="image" src="https://github.com/user-attachments/assets/ea0091bb-ee11-4f71-8be3-7129d956c910" />
+
 
 
 ## Command Line Usage

{fastapi_voyager-0.13.1 → fastapi_voyager-0.13.3}/README.md

@@ -7,11 +7,12 @@ Visualize your FastAPI endpoints, and explore them interactively.
 
 > This repo is still in early stage, it supports pydantic v2 only
 
-[live demo](https://www.newsyeah.fun/voyager/) of project: [composition oriented development pattern](https://github.com/allmonday/composition-oriented-development-pattern)
+visit [live demo](https://www.newsyeah.fun/voyager/) 
+source code:[composition oriented development pattern](https://github.com/allmonday/composition-oriented-development-pattern)
 
-<img width="1600" height="986" alt="image" src="https://github.com/user-attachments/assets/8829cda0-f42d-4c84-be2f-b019bb5fe7e1" />
+<img width="1597" height="933" alt="image" src="https://github.com/user-attachments/assets/020bf5b2-6c69-44bf-ba1f-39389d388d27" />
 
-with configuration:
+with simple configuration it can be embedded into FastAPI.
 
 ```python
 app.mount('/voyager', 
@@ -39,6 +40,8 @@ pip install fastapi-voyager
 uv add fastapi-voyager
 ```
 
+run with cli:
+
 ```shell
 voyager -m path.to.your.app.module --server
 ```
@@ -49,47 +52,81 @@ voyager -m path.to.your.app.module --server
 voyager -m path.to.your.app.module --server --app api
 ```
 
-## Mount into project
-
-```python
-from fastapi import FastAPI
-from fastapi_voyager import create_voyager
-from tests.demo import app
-
-app.mount('/voyager', create_voyager(
-    app, 
-    module_color={"tests.service": "red"}, 
-    module_prefix="tests.service"),
-    swagger_url="/docs")
-```
 
 ## Features
 
 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 during design phase before turly implemtatioin.
+It is also an architecture tool that can identify issues inside implementation, finding out wrong relationships, overfetchs, or anything else.
+
+**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
 
-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
+Given ErDiagram defined by pydantic-resolve, application level entity relationship diagram can be visualized too.
 
 ### highlight nodes and links
 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="1100" height="700" alt="image" src="https://github.com/user-attachments/assets/3e0369ea-5fa4-469a-82c1-ed57d407e53d" />
 
-### focus on nodes
-
-Double click a node, and then toggle focus to hide irrelevant nodes.
-
-<img width="1061" height="937" alt="image" src="https://github.com/user-attachments/assets/79709b02-7571-43fc-abc9-17a287a97515" />
-
 ### view source code
 
 double click a node or route to show source code or open file in vscode.
 
 <img width="1297" height="940" alt="image" src="https://github.com/user-attachments/assets/c8bb2e7d-b727-42a6-8c9e-64dce297d2d8" />
 
-<img width="1132" height="824" alt="image" src="https://github.com/user-attachments/assets/b706e879-e4fc-48dd-ace1-99bf97e3ed6a" />
+### quick search
+
+seach schemas by name and dispaly it's upstream and downstreams.
+
+shift + click can quickly search current one
+
+<img width="1587" height="873" alt="image" src="https://github.com/user-attachments/assets/ee4716f3-233d-418f-bc0e-3b214d1498f7" />
+
+### display ER diagram
+
+ER diagram is a new feature from pydantic-resolve which provide a solid expression for business descritpions. 
+
+```python
+diagram = ErDiagram(
+    configs=[
+        Entity(
+            kls=Team,
+            relationships=[
+                Relationship( field='id', target_kls=list[Sprint], loader=sprint_loader.team_to_sprint_loader),
+                Relationship( field='id', target_kls=list[User], loader=user_loader.team_to_user_loader)
+            ]
+        ),
+        Entity(
+            kls=Sprint,
+            relationships=[
+                Relationship( field='id', target_kls=list[Story], loader=story_loader.sprint_to_story_loader)
+            ]
+        ),
+        Entity(
+            kls=Story,
+            relationships=[
+                Relationship( field='id', target_kls=list[Task], loader=task_loader.story_to_task_loader),
+                Relationship( field='owner_id', target_kls=User, loader=user_loader.user_batch_loader)
+            ]
+        ),
+        Entity(
+            kls=Task,
+            relationships=[
+                Relationship( field='owner_id', target_kls=User, loader=user_loader.user_batch_loader)
+            ]
+        )
+    ]
+)
+
+# display in voyager
+app.mount('/voyager', 
+          create_voyager(
+            app,
+            er_diagram=diagram)
+```
+
+<img width="1276" height="613" alt="image" src="https://github.com/user-attachments/assets/ea0091bb-ee11-4f71-8be3-7129d956c910" />
+
 
 
 ## Command Line Usage

{fastapi_voyager-0.13.1 → fastapi_voyager-0.13.3}/docs/changelog.md

@@ -141,11 +141,15 @@
 - 0.13.1
     - [x] show more details in er diagram
 - 0.13.2
+    - [x] show dashed line for link without dataloader
+- 0.13.3
+    - [x] show field description
+- 0.13.4
     - [ ] integration with pydantic-resolve
         - [ ] show hint for resolve, post fields
         - [ ] display loader as edges
     - [ ] add tests
-- 0.13.3
+- 0.13.5
     - [ ] refactor vue-main.js, move methods to store
     - [ ] refactor render.py
 

{fastapi_voyager-0.13.1 → fastapi_voyager-0.13.3}/src/fastapi_voyager/er_diagram.py

@@ -70,7 +70,7 @@ class DiagramRenderer:
     def render_link(self, link: Link) -> str:
         h = self._handle_schema_anchor
         if link.type == 'schema':
-            return f"""{h(link.source)}:e -> {h(link.target)}:w [style = "solid", label = "{link.label}", minlen=3];"""
+            return f"""{h(link.source)}:e -> {h(link.target)}:w [style = "{link.style}", label = "{link.label}", minlen=3];"""
         else:
             raise ValueError(f'Unknown link type: {link.type}')
 
@@ -154,6 +154,7 @@ class VoyagerErDiagram:
                  er_diagram: ErDiagram, 
                  show_fields: FieldType = 'single',
                  show_module: bool = False):
+
         self.er_diagram = er_diagram
         self.nodes: list[SchemaNode] = []
         self.node_set: dict[str, SchemaNode] = {}
@@ -186,7 +187,9 @@ class VoyagerErDiagram:
                         target=self.generate_node_head(full_class_name(anno)),
                         target_origin=full_class_name(anno),
                         type='schema',
-                        label=get_type_name(relationship.target_kls))
+                        label=get_type_name(relationship.target_kls),
+                        style='solid' if relationship.loader else 'solid, dashed'
+                        )
 
                 elif isinstance(relationship, MultipleRelationship):
                     for link in relationship.links:
@@ -197,7 +200,8 @@ class VoyagerErDiagram:
                             target_origin=full_class_name(anno),
                             type='schema',
                             biz=link.biz,
-                            label=f'{get_type_name(relationship.target_kls)} / {link.biz} '
+                            label=f'{get_type_name(relationship.target_kls)} / {link.biz} ',
+                            style='solid' if link.loader else 'solid, dashed'
                         )
 
     def add_to_node_set(self, schema, fk_set: set[str] | None = None) -> str:
@@ -226,6 +230,7 @@ class VoyagerErDiagram:
             target_origin: str,
             type: LinkType,
             label: str,
+            style: str,
             biz: str | None = None
         ) -> bool:
         """
@@ -241,7 +246,8 @@ class VoyagerErDiagram:
                 target=target,
                 target_origin=target_origin,
                 type=type,
-                label=label
+                label=label,
+                style=style
             ))
         return result
 

{fastapi_voyager-0.13.1 → fastapi_voyager-0.13.3}/src/fastapi_voyager/type.py

@@ -16,6 +16,7 @@ class FieldInfo:
     from_base: bool = False
     is_object: bool = False
     is_exclude: bool = False
+    desc: str = ''
 
 @dataclass
 class Tag(NodeBase):
@@ -68,6 +69,7 @@ class Link:
     target_origin: str
     type: LinkType
     label: str | None = None
+    style: str | None = None
 
 FieldType = Literal['single', 'object', 'all']
 PK = "PK"

{fastapi_voyager-0.13.1 → fastapi_voyager-0.13.3}/src/fastapi_voyager/type_helper.py

@@ -182,7 +182,8 @@ def get_pydantic_fields(schema: type[BaseModel], bases_fields: set[str]) -> list
             name=k,
             from_base=k in bases_fields,
             type_name=get_type_name(anno),
-            is_exclude=bool(v.exclude)
+            is_exclude=bool(v.exclude),
+            desc=v.description or ''
         ))
     return fields
 

{fastapi_voyager-0.13.1 → fastapi_voyager-0.13.3}/src/fastapi_voyager/version.py

@@ -1,2 +1,2 @@
 __all__ = ["__version__"]
-__version__ = "0.13.1"
+__version__ = "0.13.3"

{fastapi_voyager-0.13.1 → fastapi_voyager-0.13.3}/src/fastapi_voyager/web/component/schema-code-display.js

@@ -179,6 +179,7 @@ export default defineComponent({
                 <tr>
                   <th style="text-align:left; border-bottom:1px solid #ddd; padding:4px 6px;">Field</th>
                   <th style="text-align:left; border-bottom:1px solid #ddd; padding:4px 6px;">Type</th>
+                  <th style="text-align:left; border-bottom:1px solid #ddd; padding:4px 6px;">Description</th>
                   <th style="text-align:left; border-bottom:1px solid #ddd; padding:4px 6px;">Inherited</th>
                 </tr>
               </thead>
@@ -186,6 +187,7 @@ export default defineComponent({
                 <tr v-for="f in fields" :key="f.name">
                   <td style="padding:4px 6px; border-bottom:1px solid #f0f0f0;">{{ f.name }}</td>
                   <td style="padding:4px 6px; border-bottom:1px solid #f0f0f0; white-space:nowrap;">{{ f.type_name }}</td>
+                  <td style="padding:4px 6px; border-bottom:1px solid #f0f0f0; max-width: 200px;">{{ f.desc }}</td>
                   <td style="padding:4px 6px; border-bottom:1px solid #f0f0f0; text-align:left;">{{ f.from_base ? '✔︎' : '' }}</td>
                 </tr>
                 <tr v-if="!fields.length">

{fastapi_voyager-0.13.1 → fastapi_voyager-0.13.3}/tests/service/schema/schema.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 from typing import Literal
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from pydantic_resolve import Relationship, MultipleRelationship, Link
 from .base_entity import BaseEntity
 
@@ -16,7 +16,7 @@ class Task(BaseModel, BaseEntity):
         Relationship(field='owner_id', target_kls=Member),
         Relationship(field='story_id', target_kls='Story'),
     ]
-    id: int
+    id: int = Field(description="The unique identifier of the task")
     story_id: int
     description: str
     owner_id: int
@@ -35,8 +35,8 @@ class Story(BaseModel, BaseEntity):
 class Sprint(BaseModel, BaseEntity):
     __pydantic_resolve_relationships__ = [
         MultipleRelationship(field='id', target_kls=list[Story], links=[
-            Link(biz='all'),
-            Link(biz='done'),
+            Link(biz='all', loader=lambda x: x),
+            Link(biz='done', loader=lambda x: x),
         ]) 
     ]
     id: int