fastapi-voyager 0.14.1__py3-none-any.whl → 0.15.1__py3-none-any.whl

fastapi_voyager/render.py

@@ -1,11 +1,18 @@
+"""
+Render FastAPI application structure to DOT format using Jinja2 templates.
+"""
 from logging import getLogger
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
 
 from fastapi_voyager.module import build_module_route_tree, build_module_schema_tree
+from fastapi_voyager.render_style import RenderConfig
 from fastapi_voyager.type import (
     PK,
     FieldType,
-    Link,
     FieldInfo,
+    Link,
     ModuleNode,
     ModuleRoute,
     Route,
@@ -15,8 +22,38 @@ from fastapi_voyager.type import (
 
 logger = getLogger(__name__)
 
+# Get the template directory relative to this file
+TEMPLATE_DIR = Path(__file__).parent / "templates"
+
+
+class TemplateRenderer:
+    """
+    Jinja2-based template renderer for DOT and HTML templates.
+    """
+
+    def __init__(self, template_dir: Path = TEMPLATE_DIR):
+        # Initialize Jinja2 environment
+        self.env = Environment(
+            loader=FileSystemLoader(template_dir),
+            autoescape=select_autoescape(),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    def render_template(self, template_name: str, **context) -> str:
+        """Render a template with the given context."""
+        template = self.env.get_template(template_name)
+        return template.render(**context)
+
 
 class Renderer:
+    """
+    Render FastAPI application structure to DOT format.
+
+    This class handles the conversion of tags, routes, schemas, and links
+    into Graphviz DOT format, with support for custom styling and filtering.
+    """
+
     def __init__(
         self,
         *,
@@ -25,6 +62,7 @@ class Renderer:
         schema: str | None = None,
         show_module: bool = True,
         show_pydantic_resolve_meta: bool = False,
+        config: RenderConfig | None = None,
     ) -> None:
         self.show_fields = show_fields if show_fields in ('single', 'object', 'all') else 'single'
         self.module_color = module_color or {}
@@ -32,252 +70,444 @@ class Renderer:
         self.show_module = show_module
         self.show_pydantic_resolve_meta = show_pydantic_resolve_meta
 
+        # Use provided config or create default
+        self.config = config or RenderConfig()
+        self.colors = self.config.colors
+        self.style = self.config.style
+
+        # Initialize template renderer
+        self.template_renderer = TemplateRenderer()
+
         logger.info(f'show_module: {self.show_module}')
         logger.info(f'module_color: {self.module_color}')
-    
-    def render_pydantic_related_markup(self, field: FieldInfo):
-        if self.show_pydantic_resolve_meta is False:
-            return ''
 
-        parts: list[str] = []
+    def _render_pydantic_meta_parts(self, field: FieldInfo) -> list[str]:
+        """Render pydantic-resolve metadata as HTML parts."""
+        if not self.show_pydantic_resolve_meta:
+            return []
+
+        parts = []
         if field.is_resolve:
-            parts.append('<font color="#47a80f">  ● resolve</font>')
+            parts.append(
+                self.template_renderer.render_template(
+                    'html/colored_text.j2',
+                    text='● resolve',
+                    color=self.colors.resolve
+                )
+            )
         if field.is_post:
-            parts.append('<font color="#427fa4">  ● post</font>')
+            parts.append(
+                self.template_renderer.render_template(
+                    'html/colored_text.j2',
+                    text='● post',
+                    color=self.colors.post
+                )
+            )
         if field.expose_as_info:
-            parts.append(f'<font color="#895cb9">  ● expose as: {field.expose_as_info}</font>')
+            parts.append(
+                self.template_renderer.render_template(
+                    'html/colored_text.j2',
+                    text=f'● expose as: {field.expose_as_info}',
+                    color=self.colors.expose_as
+                )
+            )
         if field.send_to_info:
             to_collectors = ', '.join(field.send_to_info)
-            parts.append(f'<font color="#ca6d6d">  ● send to: {to_collectors}</font>')
+            parts.append(
+                self.template_renderer.render_template(
+                    'html/colored_text.j2',
+                    text=f'● send to: {to_collectors}',
+                    color=self.colors.send_to
+                )
+            )
         if field.collect_info:
             defined_collectors = ', '.join(field.collect_info)
-            parts.append(f'<font color="#777">  ● collectors: {defined_collectors}</font>')
-
-        if not parts:
-            return ''
-        
-        return '<br align="left"/><br align="left"/>' + '<br align="left"/>'.join(parts) + '<br align="left"/>'
-
-    def render_schema_label(self, node: SchemaNode, color: str | None=None) -> str:
-        """
-        TODO: should improve the logic with show_pydantic_resolve_meta
-        """
+            parts.append(
+                self.template_renderer.render_template(
+                    'html/colored_text.j2',
+                    text=f'● collectors: {defined_collectors}',
+                    color=self.colors.collector
+                )
+            )
 
-        has_base_fields = any(f.from_base for f in node.fields)
+        return parts
 
-        # if self.show_pydantic_resolve_meta, show all fields with resolve/post/expose/collector info
+    def _render_schema_field(
+        self,
+        field: FieldInfo,
+        max_type_length: int | None = None
+    ) -> str:
+        """Render a single schema field."""
+        max_len = max_type_length or self.config.max_type_length
+
+        # Truncate type name if too long
+        type_name = field.type_name
+        if len(type_name) > max_len:
+            type_name = type_name[:max_len] + self.config.type_suffix
+
+        # Format field display
+        field_text = f'{field.name}: {type_name}'
+
+        # Render pydantic metadata
+        meta_parts = self._render_pydantic_meta_parts(field)
+        meta_html = self.template_renderer.render_template(
+            'html/pydantic_meta.j2',
+            meta_parts=meta_parts
+        )
+
+        # Render field text (with strikethrough if excluded)
+        text_html = self.template_renderer.render_template(
+            'html/colored_text.j2',
+            text=field_text,
+            color='#000',  # Default color
+            strikethrough=field.is_exclude
+        )
+
+        # Combine field text and metadata
+        content = f'<font>  {text_html}  </font> {meta_html}'
+
+        # Render the table row
+        return self.template_renderer.render_template(
+            'html/schema_field_row.j2',
+            port=field.name,
+            align='left',
+            content=content
+        )
+
+    def _get_filtered_fields(self, node: SchemaNode) -> list[FieldInfo]:
+        """Get fields filtered by show_fields and show_pydantic_resolve_meta settings."""
+
+        # Filter fields based on pydantic-resolve meta setting
         if self.show_pydantic_resolve_meta:
-            fields = [n for n in node.fields if n.has_pydantic_resolve_meta is True or n.from_base is False]
+            fields = [n for n in node.fields if n.has_pydantic_resolve_meta or not n.from_base]
         else:
-            fields = [n for n in node.fields if n.from_base is False]
+            fields = [n for n in node.fields if not n.from_base]
 
+        # Further filter by show_fields setting
         if self.show_fields == 'all':
-            _fields = fields
+            return fields
         elif self.show_fields == 'object':
             if self.show_pydantic_resolve_meta:
-                # to better display resolve meta info
-                _fields = [f for f in fields if f.is_object is True or f.has_pydantic_resolve_meta is True]
+                # Show object fields or fields with pydantic-resolve metadata
+                return [f for f in fields if f.is_object or f.has_pydantic_resolve_meta]
             else:
-                _fields = [f for f in fields if f.is_object is True]
+                # Show only object fields
+                return [f for f in fields if f.is_object]
         else:  # 'single'
-            _fields = []
+            return []
 
-        fields_parts: list[str] = []
-        if self.show_fields == 'all' and has_base_fields:
-            fields_parts.append('<tr><td align="left" cellpadding="8"><font color="#999">  Inherited Fields ... </font></td></tr>')
+    def render_schema_label(self, node: SchemaNode, color: str | None = None) -> str:
+        """
+        Render a schema node's label as an HTML table.
 
-        for field in _fields:
-            type_name = field.type_name[:25] + '..' if len(field.type_name) > 25 else field.type_name
-            display_xml = f'<s align="left">{field.name}: {type_name} </s>' if field.is_exclude else f'{field.name}: {type_name}'
-            field_str = f"""<tr><td align="left" port="f{field.name}" cellpadding="8"><font>  {display_xml}  </font> {self.render_pydantic_related_markup(field)}  </td></tr>"""
-            fields_parts.append(field_str)
+        TODO: Improve logic with show_pydantic_resolve_meta
+        """
+        fields = self._get_filtered_fields(node)
+
+        # Render field rows
+        rows = []
+        has_base_fields = any(f.from_base for f in node.fields)
 
-        default_color = '#009485' if color is None else color
-        header_color = 'tomato' if node.id == self.schema else default_color
-        header = f"""<tr><td cellpadding="6" bgcolor="{header_color}" align="center" colspan="1" port="{PK}"> <font color="white">    {node.name}    </font></td> </tr>"""
-        field_content = ''.join(fields_parts) if fields_parts else ''
-        return f"""<<table border="0" cellborder="1" cellpadding="0" cellspacing="0" bgcolor="white"> {header} {field_content}   </table>>"""
+        # Add inherited fields notice if needed
+        if self.show_fields == 'all' and has_base_fields:
+            notice = self.template_renderer.render_template(
+                'html/colored_text.j2',
+                text='  Inherited Fields ... ',
+                color=self.colors.text_gray
+            )
+            rows.append(
+                self.template_renderer.render_template(
+                    'html/schema_field_row.j2',
+                    content=notice,
+                    align='left'
+                )
+            )
+
+        # Render each field
+        for field in fields:
+            rows.append(self._render_schema_field(field))
+
+        # Determine header color
+        default_color = self.colors.primary if color is None else color
+        header_color = self.colors.highlight if node.id == self.schema else default_color
+
+        # Render header
+        header = self.template_renderer.render_template(
+            'html/schema_header.j2',
+            text=node.name,
+            bg_color=header_color,
+            port=PK
+        )
+
+        # Render complete table
+        return self.template_renderer.render_template(
+            'html/schema_table.j2',
+            header=header,
+            rows=''.join(rows)
+        )
 
     def _handle_schema_anchor(self, source: str) -> str:
+        """Handle schema anchor for DOT links."""
         if '::' in source:
             a, b = source.split('::', 1)
             return f'"{a}":{b}'
         return f'"{source}"'
 
+    def _format_link_attributes(self, attrs: dict) -> str:
+        """Format link attributes for DOT format."""
+        return ', '.join(f'{k}="{v}"' for k, v in attrs.items())
+
     def render_link(self, link: Link) -> str:
-        h = self._handle_schema_anchor
-        if link.type == 'tag_route':
-            return f"""{h(link.source)}:e -> {h(link.target)}:w [style = "solid", minlen=3];"""
-        elif link.type == 'route_to_schema':
-            return f"""{h(link.source)}:e -> {h(link.target)}:w [style = "solid", dir="back", arrowtail="odot", minlen=3];"""
-        elif link.type == 'schema':
-            return f"""{h(link.source)}:e -> {h(link.target)}:w [style = "solid", label = "", dir="back", minlen=3, arrowtail="odot"];"""
-        elif link.type == 'parent':
-            return f"""{h(link.source)}:e -> {h(link.target)}:w [style = "solid, dashed", dir="back", minlen=3, taillabel = "< inherit >", color = "purple", tailport="n"];"""
-        elif link.type == 'subset':
-            return f"""{h(link.source)}:e -> {h(link.target)}:w [style = "solid, dashed", dir="back", minlen=3, taillabel = "< subset >", color = "orange", tailport="n"];"""
-        elif link.type == 'tag_to_schema':
-            return f"""{h(link.source)}:e -> {h(link.target)}:w [style = "solid", minlen=3];"""
+        """Render a link in DOT format."""
+        source = self._handle_schema_anchor(link.source)
+        target = self._handle_schema_anchor(link.target)
+
+        # Build link attributes
+        # If link.style is explicitly set (e.g., 'solid, dashed' for ER diagrams), use it
+        # Otherwise, get default style from configuration based on link.type
+        if link.style is not None:
+            attrs = {'style': link.style}
+            if link.label:
+                attrs['label'] = link.label
+            # attrs['minlen'] = 3
         else:
-            raise ValueError(f'Unknown link type: {link.type}')
-
-    def render_module_schema_content(self, nodes: list[SchemaNode]) -> str:
-        def render_node(node: SchemaNode, color: str | None=None) -> str:
-            return f'''
-                "{node.id}" [
-                    label = {self.render_schema_label(node, color)}
-                    shape = "plain"
-                    margin="0.5,0.1"
-                ];'''
-
-        def render_module_schema(mod: ModuleNode, inherit_color: str | None=None, show_cluster:bool=True) -> str:
-            color: str | None = inherit_color
-            cluster_color: str | None = None
-
-
-            # recursively vist module from short to long:  'a', 'a.b', 'a.b.c'
-            # color_flag: {'a', 'a.b.c'}
-            # at first 'a', match 'a' -> color, remove 'a' from color_flag
-            # at 'a.b', no match
-            # at 'a.b.c', match 'a.b.c' -> color, remove 'a.b.c' from color_flag
-            for k in module_color_flag:
-                if mod.fullname.startswith(k):  
-                    module_color_flag.remove(k)
-                    color = self.module_color[k]
-                    cluster_color = color if color != inherit_color else None
-                    break
-
-            inner_nodes = [ render_node(node, color) for node in mod.schema_nodes ]
-            inner_nodes_str = '\n'.join(inner_nodes)
-            child_str = '\n'.join(render_module_schema(mod=m, inherit_color=color, show_cluster=show_cluster) for m in mod.modules)
-
-            if show_cluster:
-                return f'''
-                    subgraph cluster_module_{mod.fullname.replace('.', '_')} {{
-                        tooltip="{mod.fullname}"
-                        color = "#666"
-                        style="rounded"
-                        label = "  {mod.name}"
-                        labeljust = "l"
-                        {(f'pencolor = "{cluster_color}"' if cluster_color else 'pencolor="#ccc"')}
-                        {('penwidth = 3' if color else 'penwidth=""')}
-                        {inner_nodes_str}
-                        {child_str}
-                    }}'''
+            attrs = self.style.get_link_attributes(link.type)
+            if link.label:
+                attrs['label'] = link.label
+
+        return self.template_renderer.render_template(
+            'dot/link.j2',
+            source=source,
+            target=target,
+            attributes=self._format_link_attributes(attrs)
+        )
+
+    def render_schema_node(self, node: SchemaNode, color: str | None = None) -> str:
+        """Render a schema node in DOT format."""
+        label = self.render_schema_label(node, color)
+
+        return self.template_renderer.render_template(
+            'dot/schema_node.j2',
+            id=node.id,
+            label=label,
+            margin=self.style.node_margin
+        )
+
+    def render_tag_node(self, tag: Tag) -> str:
+        """Render a tag node in DOT format."""
+        return self.template_renderer.render_template(
+            'dot/tag_node.j2',
+            id=tag.id,
+            name=tag.name,
+            margin=self.style.node_margin
+        )
+
+    def render_route_node(self, route: Route) -> str:
+        """Render a route node in DOT format."""
+        # Truncate response schema if too long
+        response_schema = route.response_schema
+        if len(response_schema) > self.config.max_type_length:
+            response_schema = response_schema[:self.config.max_type_length] + self.config.type_suffix
+
+        return self.template_renderer.render_template(
+            'dot/route_node.j2',
+            id=route.id,
+            name=route.name,
+            response_schema=response_schema,
+            margin=self.style.node_margin
+        )
+
+    def _render_module_schema(
+        self,
+        mod: ModuleNode,
+        module_color_flag: set[str],
+        inherit_color: str | None = None,
+        show_cluster: bool = True
+    ) -> str:
+        """Render a module schema tree."""
+        color = inherit_color
+        cluster_color: str | None = None
+
+        # Check if this module has a custom color
+        for k in module_color_flag:
+            if mod.fullname.startswith(k):
+                module_color_flag.remove(k)
+                color = self.module_color[k]
+                cluster_color = color if color != inherit_color else None
+                break
+
+        # Render inner schema nodes
+        inner_nodes = [
+            self.render_schema_node(node, color)
+            for node in mod.schema_nodes
+        ]
+        inner_nodes_str = '\n'.join(inner_nodes)
+
+        # Recursively render child modules
+        child_str = '\n'.join(
+            self._render_module_schema(
+                m,
+                module_color_flag=module_color_flag,
+                inherit_color=color,
+                show_cluster=show_cluster
+            )
+            for m in mod.modules
+        )
+
+        if show_cluster:
+            # Render as a cluster
+            cluster_id = f'module_{mod.fullname.replace(".", "_")}'
+            pen_style = ''
+
+            if cluster_color:
+                pen_style = f'pencolor = "{cluster_color}"'
+                pen_style += '\n' + f'penwidth = 3' if color else ''
             else:
-                return f'''
-                    {inner_nodes_str}
-                    {child_str}
-                '''
+                pen_style = 'pencolor="#ccc"'
+
+            return self.template_renderer.render_template(
+                'dot/cluster.j2',
+                cluster_id=cluster_id,
+                label=mod.name,
+                tooltip=mod.fullname,
+                border_color=self.colors.border,
+                pen_color=cluster_color,
+                pen_width=3 if color and not cluster_color else None,
+                content=f'{inner_nodes_str}\n{child_str}'
+            )
+        else:
+            # Render without cluster
+            return f'{inner_nodes_str}\n{child_str}'
 
-        # if self.show_module:
+    def render_module_schema_content(self, nodes: list[SchemaNode]) -> str:
+        """Render all module schemas."""
         module_schemas = build_module_schema_tree(nodes)
         module_color_flag = set(self.module_color.keys())
-        return '\n'.join(render_module_schema(mod=m, show_cluster=self.show_module) for m in module_schemas)
 
-    
+        return '\n'.join(
+            self._render_module_schema(
+                m,
+                module_color_flag=module_color_flag,
+                show_cluster=self.show_module
+            )
+            for m in module_schemas
+        )
+
+    def _render_module_route(self, mod: ModuleRoute, show_cluster: bool = True) -> str:
+        """Render a module route tree."""
+        # Render inner route nodes
+        inner_nodes = [self.render_route_node(r) for r in mod.routes]
+        inner_nodes_str = '\n'.join(inner_nodes)
+
+        # Recursively render child modules
+        child_str = '\n'.join(
+            self._render_module_route(m, show_cluster=show_cluster)
+            for m in mod.modules
+        )
+
+        if show_cluster:
+            cluster_id = f'route_module_{mod.fullname.replace(".", "_")}'
+
+            return self.template_renderer.render_template(
+                'dot/cluster.j2',
+                cluster_id=cluster_id,
+                label=mod.name,
+                tooltip=mod.fullname,
+                border_color=self.colors.border,
+                pen_color=None,
+                pen_width=None,
+                content=f'{inner_nodes_str}\n{child_str}'
+            )
+        else:
+            return f'{inner_nodes_str}\n{child_str}'
+
     def render_module_route_content(self, routes: list[Route]) -> str:
-        def render_route(route: Route) -> str:
-            response_schema = route.response_schema[:25] + '..' if len(route.response_schema) > 25 else route.response_schema
-            return f'''
-                "{route.id}" [
-                    label = "    {route.name} | {response_schema}    "
-                    margin="0.5,0.1"
-                    shape = "record"
-                ];'''
-
-        def render_module_route(mod: ModuleRoute, show_cluster: bool=True) -> str:
-            # Inner route nodes, same style as flat route_str
-            inner_nodes = [
-                render_route(r) for r in mod.routes
-            ]
-            inner_nodes_str = '\n'.join(inner_nodes)
-            child_str = '\n'.join(render_module_route(m, show_cluster=show_cluster) for m in mod.modules)
-            if show_cluster:
-                return f'''
-                    subgraph cluster_route_module_{mod.fullname.replace('.', '_')} {{
-                        tooltip="{mod.fullname}"
-                        color = "#666"
-                        style="rounded"
-                        label = "  {mod.name}"
-                        labeljust = "l"
-                        {inner_nodes_str}
-                        {child_str}
-                    }}'''
-            else:
-                return f'''
-                    {inner_nodes_str}
-                    {child_str}
-                '''
+        """Render all module routes."""
         module_routes = build_module_route_tree(routes)
-        module_routes_str = '\n'.join(render_module_route(m, show_cluster=self.show_module) for m in module_routes)
-        return module_routes_str
 
+        return '\n'.join(
+            self._render_module_route(m, show_cluster=self.show_module)
+            for m in module_routes
+        )
+
+    def _render_cluster_container(
+        self,
+        name: str,
+        label: str,
+        content: str,
+        fontsize: str | None = None
+    ) -> str:
+        """Render a cluster container (for tags, routes, schemas)."""
+        return self.template_renderer.render_template(
+            'dot/cluster_container.j2',
+            name=name,
+            label=label,
+            content=content,
+            border_color=self.colors.border,
+            margin=self.style.cluster_margin,
+            fontsize=fontsize or self.style.cluster_fontsize
+        )
+
+    def render_dot(
+        self,
+        tags: list[Tag],
+        routes: list[Route],
+        nodes: list[SchemaNode],
+        links: list[Link],
+        spline_line: bool = False
+    ) -> str:
+        """
+        Render the complete DOT graph.
+
+        Args:
+            tags: List of tags
+            routes: List of routes
+            nodes: List of schema nodes
+            links: List of links
+            spline_line: Whether to use spline lines
 
-    def render_dot(self, tags: list[Tag], routes: list[Route], nodes: list[SchemaNode], links: list[Link], spline_line=False) -> str:
+        Returns:
+            Complete DOT graph as a string
+        """
+        # Render tag nodes
+        tag_str = '\n'.join(self.render_tag_node(t) for t in tags)
 
-        tag_str = '\n'.join([
-            f'''
-            "{t.id}" [
-                label = "    {t.name}    "
-                shape = "record"
-                margin="0.5,0.1"
-            ];''' for t in tags
-        ])
+        # Render tags cluster
+        tags_cluster = self._render_cluster_container(
+            name='tags',
+            label='Tags',
+            content=tag_str
+        )
 
+        # Render routes cluster
         module_routes_str = self.render_module_route_content(routes)
+        routes_cluster = self._render_cluster_container(
+            name='router',
+            label='Routes',
+            content=module_routes_str
+        )
+
+        # Render schemas cluster
         module_schemas_str = self.render_module_schema_content(nodes)
+        schemas_cluster = self._render_cluster_container(
+            name='schema',
+            label='Schema',
+            content=module_schemas_str
+        )
+
+        # Render links
         link_str = '\n'.join(self.render_link(link) for link in links)
 
-        dot_str = f'''
-        digraph world {{
-            pad="0.5"
-            nodesep=0.8
-            {'splines=line' if spline_line else ''}
-            fontname="Helvetica,Arial,sans-serif"
-            node [fontname="Helvetica,Arial,sans-serif"]
-            edge [
-                fontname="Helvetica,Arial,sans-serif"
-                color="gray"
-            ]
-            graph [
-                rankdir = "LR"
-            ];
-            node [
-                fontsize = "16"
-            ];
-
-            subgraph cluster_tags {{ 
-                color = "#aaa"
-                margin=18
-                style="dashed"
-                label = "  Tags"
-                labeljust = "l"
-                fontsize = "20"
-                {tag_str}
-            }}
-
-            subgraph cluster_router {{
-                color = "#aaa"
-                margin=18
-                style="dashed"
-                label = "  Routes"
-                labeljust = "l"
-                fontsize = "20"
-                {module_routes_str}
-            }}
-
-            subgraph cluster_schema {{
-                color = "#aaa"
-                margin=18
-                style="dashed"
-                label="  Schema"
-                labeljust="l"
-                fontsize="20"
-                    {module_schemas_str}
-            }}
-
-            {link_str}
-            }}
-        '''
-        return dot_str
+        # Render complete digraph
+        return self.template_renderer.render_template(
+            'dot/digraph.j2',
+            pad=self.style.pad,
+            nodesep=self.style.nodesep,
+            spline='line' if spline_line else '',
+            font=self.style.font,
+            node_fontsize=self.style.node_fontsize,
+            tags_cluster=tags_cluster,
+            routes_cluster=routes_cluster,
+            schemas_cluster=schemas_cluster,
+            links=link_str
+        )