sql-glider 0.1.25__tar.gz → 0.1.27__tar.gz

{sql_glider-0.1.25 → sql_glider-0.1.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-glider
-Version: 0.1.25
+Version: 0.1.27
 Summary: SQL Utility Toolkit for better understanding, use, and governance of your queries in a native environment.
 Project-URL: Homepage, https://github.com/rycowhi/sql-glider/
 Project-URL: Repository, https://github.com/rycowhi/sql-glider/
@@ -30,6 +30,7 @@ Provides-Extra: databricks
 Requires-Dist: databricks-sdk>=0.20.0; extra == 'databricks'
 Provides-Extra: plotly
 Requires-Dist: plotly>=5.0.0; extra == 'plotly'
+Requires-Dist: pygraphviz>=1.11; extra == 'plotly'
 Description-Content-Type: text/markdown
 
 # SQL Glider

{sql_glider-0.1.25 → sql_glider-0.1.27}/docs/docs/graph-lineage.md

@@ -258,7 +258,7 @@ sqlglider graph query graph.json --downstream orders.order_total -f dot
 sqlglider graph query graph.json --upstream total_spent -f plotly
 ```
 
-Query diagrams include color-coded nodes and a legend:
+Query diagrams include color-coded nodes, edge labels showing the source SQL file, and a legend:
 
 | Color  | Meaning |
 |--------|---------|
@@ -266,6 +266,8 @@ Query diagrams include color-coded nodes and a legend:
 | Teal   | Root node (no upstream dependencies) |
 | Violet | Leaf node (no downstream consumers) |
 
+Each edge in the diagram is labeled with the SQL filename that defines that relationship, making it easy to trace data flow back to the source code.
+
 **Example:** Imagine a pipeline where a `revenue` report column draws from multiple sources through several transformation layers. Querying `--upstream revenue` would produce a diagram like this:
 
 ```mermaid
@@ -277,12 +279,12 @@ flowchart TD
     staging_orders_tax_amount["staging_orders.tax_amount"]
     mart_orders_total_usd["mart_orders.total_usd"]
     revenue["revenue"]
-    raw_orders_amount --> staging_orders_subtotal
-    raw_orders_tax --> staging_orders_tax_amount
-    staging_orders_subtotal --> mart_orders_total_usd
-    staging_orders_tax_amount --> mart_orders_total_usd
-    raw_exchange_rates_rate --> mart_orders_total_usd
-    mart_orders_total_usd --> revenue
+    raw_orders_amount -->|staging_orders.sql| staging_orders_subtotal
+    raw_orders_tax -->|staging_orders.sql| staging_orders_tax_amount
+    staging_orders_subtotal -->|mart_orders.sql| mart_orders_total_usd
+    staging_orders_tax_amount -->|mart_orders.sql| mart_orders_total_usd
+    raw_exchange_rates_rate -->|mart_orders.sql| mart_orders_total_usd
+    mart_orders_total_usd -->|reports.sql| revenue
 
     style revenue fill:#e6a843,stroke:#b8860b,stroke-width:3px
     style raw_orders_amount fill:#4ecdc4,stroke:#2b9e96
@@ -299,7 +301,7 @@ flowchart TD
     style legend_leaf fill:#c084fc,stroke:#7c3aed
 ```
 
-The amber node is the column you queried (`revenue`), teal nodes are ultimate root sources with no further upstream dependencies (`raw_orders.amount`, `raw_orders.tax`, `raw_exchange_rates.rate`), and intermediate nodes (`staging_orders.*`, `mart_orders.*`) appear in the default style. The legend is included automatically.
+The amber node is the column you queried (`revenue`), teal nodes are ultimate root sources with no further upstream dependencies (`raw_orders.amount`, `raw_orders.tax`, `raw_exchange_rates.rate`), and intermediate nodes (`staging_orders.*`, `mart_orders.*`) appear in the default style. Each edge is labeled with the SQL file that defines that relationship. The legend is included automatically.
 
 ### Mermaid Markdown Format
 
@@ -327,6 +329,20 @@ The `plotly` format outputs a JSON figure specification that can be loaded into
     pip install sql-glider[plotly]
     ```
 
+!!! tip "Better Layout with Graphviz"
+
+    For complex graphs with many nodes and edges, installing [Graphviz](https://graphviz.org/download/) on your system enables an optimized layout algorithm that minimizes edge crossings. Without Graphviz, a simpler layout is used that may result in overlapping edges.
+
+    ```bash
+    # Install Graphviz first (system package)
+    # Windows: choco install graphviz
+    # macOS: brew install graphviz
+    # Linux: apt install graphviz graphviz-dev
+
+    # Then install sql-glider with plotly extra
+    pip install sql-glider[plotly]
+    ```
+
 **Example usage with Dash:**
 
 ```python

{sql_glider-0.1.25 → sql_glider-0.1.27}/pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
 
 [project.optional-dependencies]
 databricks = ["databricks-sdk>=0.20.0"]
-plotly = ["plotly>=5.0.0"]
+plotly = ["plotly>=5.0.0", "pygraphviz>=1.11"]
 
 [project.urls]
 Homepage = "https://github.com/rycowhi/sql-glider/"

{sql_glider-0.1.25 → sql_glider-0.1.27}/src/sqlglider/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.25'
-__version_tuple__ = version_tuple = (0, 1, 25)
+__version__ = version = '0.1.27'
+__version_tuple__ = version_tuple = (0, 1, 27)
 
 __commit_id__ = commit_id = None

{sql_glider-0.1.25 → sql_glider-0.1.27}/src/sqlglider/cli.py

@@ -1715,11 +1715,15 @@ def graph_query(
         elif output_format == "mermaid":
             from sqlglider.graph.diagram_formatters import MermaidFormatter
 
-            print(MermaidFormatter.format_query_result(result))
+            print(MermaidFormatter.format_query_result(result, graph=querier.graph))
         elif output_format == "mermaid-markdown":
             from sqlglider.graph.diagram_formatters import MermaidMarkdownFormatter
 
-            print(MermaidMarkdownFormatter.format_query_result(result))
+            print(
+                MermaidMarkdownFormatter.format_query_result(
+                    result, graph=querier.graph
+                )
+            )
         elif output_format == "dot":
             from sqlglider.graph.diagram_formatters import DotFormatter
 

{sql_glider-0.1.25 → sql_glider-0.1.27}/src/sqlglider/graph/diagram_formatters.py

@@ -102,16 +102,26 @@ class MermaidFormatter:
             node_id = _sanitize_mermaid_id(node.identifier)
             lines.append(f'    {node_id}["{node.identifier}"]')
 
-        # Add edges
+        # Add edges with file path labels
         for edge in graph.edges:
             src = _sanitize_mermaid_id(edge.source_node)
             tgt = _sanitize_mermaid_id(edge.target_node)
-            lines.append(f"    {src} --> {tgt}")
+            # Extract filename from path
+            file_name = (
+                edge.file_path.split("/")[-1].split("\\")[-1] if edge.file_path else ""
+            )
+            if file_name:
+                lines.append(f"    {src} -->|{file_name}| {tgt}")
+            else:
+                lines.append(f"    {src} --> {tgt}")
 
         return "\n".join(lines)
 
     @staticmethod
-    def format_query_result(result: LineageQueryResult) -> str:
+    def format_query_result(
+        result: LineageQueryResult,
+        graph: Optional[LineageGraph] = None,
+    ) -> str:
         """Format query result as a Mermaid flowchart with styling.
 
         The queried column is highlighted in amber, root nodes in teal,
@@ -119,6 +129,7 @@ class MermaidFormatter:
 
         Args:
             result: LineageQueryResult from upstream/downstream query
+            graph: Optional LineageGraph for edge file path labels
 
         Returns:
             Mermaid diagram string with style directives and legend
@@ -134,16 +145,27 @@ class MermaidFormatter:
         all_nodes = _collect_query_nodes(result)
         edges = _collect_query_edges(result)
 
+        # Build edge file path lookup if graph is provided
+        edge_file_paths: dict[tuple[str, str], str] = {}
+        if graph:
+            for e in graph.edges:
+                edge_file_paths[(e.source_node, e.target_node)] = e.file_path
+
         # Declare nodes
         for identifier in sorted(all_nodes):
             node_id = _sanitize_mermaid_id(identifier)
             lines.append(f'    {node_id}["{identifier}"]')
 
-        # Add edges
+        # Add edges with optional file path labels
         for src, tgt in sorted(edges):
-            lines.append(
-                f"    {_sanitize_mermaid_id(src)} --> {_sanitize_mermaid_id(tgt)}"
-            )
+            src_id = _sanitize_mermaid_id(src)
+            tgt_id = _sanitize_mermaid_id(tgt)
+            file_path = edge_file_paths.get((src, tgt), "")
+            file_name = file_path.split("/")[-1].split("\\")[-1] if file_path else ""
+            if file_name:
+                lines.append(f"    {src_id} -->|{file_name}| {tgt_id}")
+            else:
+                lines.append(f"    {src_id} --> {tgt_id}")
 
         # Style directives
         queried_id = _sanitize_mermaid_id(result.query_column)
@@ -200,16 +222,20 @@ class MermaidMarkdownFormatter:
         return f"```mermaid\n{mermaid}\n```"
 
     @staticmethod
-    def format_query_result(result: LineageQueryResult) -> str:
+    def format_query_result(
+        result: LineageQueryResult,
+        graph: Optional[LineageGraph] = None,
+    ) -> str:
         """Format query result as a Mermaid diagram in a markdown code block.
 
         Args:
             result: LineageQueryResult from upstream/downstream query
+            graph: Optional LineageGraph for edge file path labels
 
         Returns:
             Markdown string with fenced Mermaid diagram
         """
-        mermaid = MermaidFormatter.format_query_result(result)
+        mermaid = MermaidFormatter.format_query_result(result, graph=graph)
         return f"```mermaid\n{mermaid}\n```"
 
 
@@ -338,7 +364,11 @@ def _compute_layered_layout(
     x_spacing: float = 250.0,
     y_spacing: float = 100.0,
 ) -> dict[str, tuple[float, float]]:
-    """Compute layered layout positions for nodes using topological ordering.
+    """Compute layered layout positions for nodes using Graphviz's dot algorithm.
+
+    Uses Graphviz's dot layout engine (Sugiyama algorithm) which minimizes edge
+    crossings by using the barycenter heuristic to optimize node ordering within
+    each layer.
 
     Positions nodes in layers from left to right based on their dependencies.
     Nodes with no incoming edges are placed in layer 0, their dependents in
@@ -356,6 +386,89 @@ def _compute_layered_layout(
     if not nodes:
         return {}
 
+    try:
+        import pygraphviz  # noqa: F401  # type: ignore[import-not-found]
+
+        return _compute_graphviz_layout(nodes, edges, x_spacing, y_spacing)
+    except ImportError:
+        # Fallback to simple layered layout if pygraphviz not available
+        return _compute_simple_layered_layout(nodes, edges, x_spacing, y_spacing)
+
+
+def _compute_graphviz_layout(
+    nodes: list[str],
+    edges: list[tuple[str, str]],
+    x_spacing: float = 250.0,
+    y_spacing: float = 100.0,
+) -> dict[str, tuple[float, float]]:
+    """Compute layout using Graphviz's dot algorithm with crossing minimization.
+
+    Args:
+        nodes: List of node identifiers
+        edges: List of (source, target) edge tuples
+        x_spacing: Horizontal spacing between layers
+        y_spacing: Vertical spacing between nodes in the same layer
+
+    Returns:
+        Dictionary mapping node identifiers to (x, y) positions
+    """
+    import pygraphviz as pgv  # type: ignore[import-not-found]
+
+    # Create directed graph
+    g = pgv.AGraph(directed=True, rankdir="LR")
+
+    # Set graph attributes for spacing
+    g.graph_attr["ranksep"] = str(x_spacing / 72.0)  # Convert pixels to inches
+    g.graph_attr["nodesep"] = str(y_spacing / 72.0)
+
+    # Add nodes
+    for node in nodes:
+        g.add_node(node)
+
+    # Add edges (only for nodes that exist in our node list)
+    node_set = set(nodes)
+    for src, tgt in edges:
+        if src in node_set and tgt in node_set:
+            g.add_edge(src, tgt)
+
+    # Compute layout using dot algorithm
+    g.layout(prog="dot")
+
+    # Extract positions
+    positions: dict[str, tuple[float, float]] = {}
+    for node in nodes:
+        n = g.get_node(node)
+        # Position is returned as "x,y" string in points (1/72 inch)
+        pos_str = n.attr.get("pos", "0,0")
+        if pos_str:
+            x_str, y_str = pos_str.split(",")
+            # Convert from points to our coordinate system
+            x = float(x_str)
+            y = float(y_str)
+            positions[node] = (x, y)
+
+    return positions
+
+
+def _compute_simple_layered_layout(
+    nodes: list[str],
+    edges: list[tuple[str, str]],
+    x_spacing: float = 250.0,
+    y_spacing: float = 100.0,
+) -> dict[str, tuple[float, float]]:
+    """Fallback simple layered layout using topological ordering.
+
+    Used when pygraphviz is not available. Does not minimize edge crossings.
+
+    Args:
+        nodes: List of node identifiers
+        edges: List of (source, target) edge tuples
+        x_spacing: Horizontal spacing between layers
+        y_spacing: Vertical spacing between nodes in the same layer
+
+    Returns:
+        Dictionary mapping node identifiers to (x, y) positions
+    """
     # Build adjacency structures
     incoming: dict[str, set[str]] = defaultdict(set)
     outgoing: dict[str, set[str]] = defaultdict(set)

{sql_glider-0.1.25 → sql_glider-0.1.27}/tests/sqlglider/graph/test_diagram_formatters.py

@@ -235,15 +235,17 @@ class TestMermaidFormatterFullGraph:
 
     def test_linear_graph_has_edges(self, linear_graph):
         result = MermaidFormatter.format_full_graph(linear_graph)
-        assert "a_col --> b_col" in result
-        assert "b_col --> c_col" in result
+        # Edges now include file path labels
+        assert "a_col -->|q.sql| b_col" in result
+        assert "b_col -->|q.sql| c_col" in result
 
     def test_diamond_graph_edges(self, diamond_graph):
         result = MermaidFormatter.format_full_graph(diamond_graph)
-        assert "a_col --> b_col" in result
-        assert "a_col --> c_col" in result
-        assert "b_col --> d_col" in result
-        assert "c_col --> d_col" in result
+        # Edges now include file path labels
+        assert "a_col -->|q.sql| b_col" in result
+        assert "a_col -->|q.sql| c_col" in result
+        assert "b_col -->|q.sql| d_col" in result
+        assert "c_col -->|q.sql| d_col" in result
 
     def test_starts_with_flowchart(self, linear_graph):
         result = MermaidFormatter.format_full_graph(linear_graph)
@@ -285,6 +287,45 @@ class TestMermaidFormatterQueryResult:
         result = MermaidFormatter.format_query_result(empty_query_result)
         assert "Legend" not in result
 
+    def test_with_graph_has_edge_labels(self, upstream_query_result):
+        """Test that passing a graph adds edge file path labels."""
+        # Create a graph that matches the query result edges
+        matching_graph = LineageGraph(
+            nodes=[
+                GraphNode.from_identifier("source.col", "/path/lineage.sql", 0),
+                GraphNode.from_identifier("mid.col", "/path/lineage.sql", 0),
+                GraphNode.from_identifier("target.col", "/path/lineage.sql", 0),
+            ],
+            edges=[
+                GraphEdge(
+                    source_node="source.col",
+                    target_node="mid.col",
+                    file_path="/path/lineage.sql",
+                    query_index=0,
+                ),
+                GraphEdge(
+                    source_node="mid.col",
+                    target_node="target.col",
+                    file_path="/path/lineage.sql",
+                    query_index=0,
+                ),
+            ],
+        )
+
+        result = MermaidFormatter.format_query_result(
+            upstream_query_result, graph=matching_graph
+        )
+        # Edges should have file path labels
+        assert "-->|lineage.sql|" in result
+
+    def test_without_graph_no_edge_labels(self, upstream_query_result):
+        """Test that without graph parameter, edges have no labels."""
+        result = MermaidFormatter.format_query_result(upstream_query_result)
+        # Edges should not have labels (no |...|)
+        assert "source_col --> mid_col" in result
+        assert "mid_col --> target_col" in result
+        assert "-->|" not in result
+
 
 # --- DotFormatter tests ---
 
@@ -382,7 +423,8 @@ class TestMermaidMarkdownFormatterFullGraph:
     def test_contains_mermaid_content(self, linear_graph):
         result = MermaidMarkdownFormatter.format_full_graph(linear_graph)
         assert "flowchart TD" in result
-        assert "a_col --> b_col" in result
+        # Edges now include file path labels
+        assert "a_col -->|q.sql| b_col" in result
 
     def test_empty_graph(self, empty_graph):
         result = MermaidMarkdownFormatter.format_full_graph(empty_graph)

{sql_glider-0.1.25 → sql_glider-0.1.27}/uv.lock

@@ -814,6 +814,12 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
 ]
 
+[[package]]
+name = "pygraphviz"
+version = "1.14"
+source = { registry = "https://pypi.org/simple/" }
+sdist = { url = "https://files.pythonhosted.org/packages/66/ca/823d5c74a73d6b8b08e1f5aea12468ef334f0732c65cbb18df2a7f285c87/pygraphviz-1.14.tar.gz", hash = "sha256:c10df02377f4e39b00ae17c862f4ee7e5767317f1c6b2dfd04cea6acc7fc2bea", size = 106003, upload-time = "2024-09-29T18:31:12.471Z" }
+
 [[package]]
 name = "pymdown-extensions"
 version = "10.20.1"
@@ -1161,6 +1167,7 @@ databricks = [
 ]
 plotly = [
     { name = "plotly" },
+    { name = "pygraphviz" },
 ]
 
 [package.dev-dependencies]
@@ -1185,6 +1192,7 @@ requires-dist = [
     { name = "jinja2", specifier = ">=3.0.0" },
     { name = "plotly", marker = "extra == 'plotly'", specifier = ">=5.0.0" },
     { name = "pydantic", specifier = ">=2.0.0" },
+    { name = "pygraphviz", marker = "extra == 'plotly'", specifier = ">=1.11" },
     { name = "rich", specifier = ">=13.0.0" },
     { name = "rustworkx", specifier = ">=0.15.0" },
     { name = "sqlglot", extras = ["rs"], specifier = ">=25.0.0" },