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

{sql_glider-0.1.23 → sql_glider-0.1.25}/CLAUDE.md

@@ -276,17 +276,26 @@ uv run sqlglider graph query graph.json --upstream orders.total -f mermaid
 # Query with DOT (Graphviz) diagram output
 uv run sqlglider graph query graph.json --downstream customers.id -f dot
 
+# Query with Plotly JSON output (for Dash/Plotly apps)
+uv run sqlglider graph query graph.json --upstream orders.total -f plotly
+
 # Visualize entire graph as Mermaid diagram
 uv run sqlglider graph visualize graph.json
 
 # Visualize entire graph as DOT diagram
 uv run sqlglider graph visualize graph.json -f dot
 
+# Visualize entire graph as Plotly JSON
+uv run sqlglider graph visualize graph.json -f plotly
+
 # Save diagram to file
 uv run sqlglider graph visualize graph.json -o lineage.mmd
 uv run sqlglider graph visualize graph.json -f dot -o lineage.dot
+uv run sqlglider graph visualize graph.json -f plotly -o lineage.json
 ```
 
+**Note:** Plotly output requires the optional dependency: `pip install sql-glider[plotly]`
+
 ### SQL Templating
 
 SQL Glider supports Jinja2 templating for SQL files. This allows you to use variables, conditionals, and loops in your SQL before analysis.

sql_glider-0.1.23/README.md → sql_glider-0.1.25/PKG-INFO

@@ -1,3 +1,37 @@
+Metadata-Version: 2.4
+Name: sql-glider
+Version: 0.1.25
+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/
+Project-URL: Documentation, https://github.com/rycowhi/sql-glider/
+Project-URL: Issues, https://github.com/rycowhi/sql-glider/issues
+Author-email: Ryan Whitcomb <ryankwhitcomb@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: data-governance,data-lineage,lineage,sql,sqlglot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: SQL
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: rustworkx>=0.15.0
+Requires-Dist: sqlglot[rs]>=25.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: databricks
+Requires-Dist: databricks-sdk>=0.20.0; extra == 'databricks'
+Provides-Extra: plotly
+Requires-Dist: plotly>=5.0.0; extra == 'plotly'
+Description-Content-Type: text/markdown
+
 # SQL Glider
 
 ![SQL Glider Logo](./docs/docs/static/sqlglider-logo-transparent.png)
@@ -388,12 +422,33 @@ uv run sqlglider graph query graph.json --upstream orders.customer_id -f mermaid
 # Query with DOT (Graphviz) diagram output
 uv run sqlglider graph query graph.json --downstream customers.id -f dot
 
+# Query with Plotly JSON output (for interactive visualization)
+uv run sqlglider graph query graph.json --upstream orders.customer_id -f plotly
+
 # Visualize entire graph as a diagram
 uv run sqlglider graph visualize graph.json                    # Mermaid (default)
 uv run sqlglider graph visualize graph.json -f dot             # DOT/Graphviz
+uv run sqlglider graph visualize graph.json -f plotly          # Plotly JSON
 uv run sqlglider graph visualize graph.json -o lineage.mmd     # Save to file
 ```
 
+> **Note:** Plotly output requires an optional dependency. Install with: `pip install sql-glider[plotly]`
+
+The Plotly JSON output can be loaded into Plotly/Dash applications for interactive visualization:
+
+```python
+import plotly.io as pio
+from dash import Dash, dcc, html
+
+# Load the JSON output
+with open("lineage.json") as f:
+    fig = pio.from_json(f.read())
+
+# Use in a Dash app
+app = Dash(__name__)
+app.layout = html.Div([dcc.Graph(figure=fig)])
+```
+
 **Example Upstream Query Output:**
 ```
                               Sources for 'order_totals.total'
@@ -679,12 +734,24 @@ Arguments:
 Options:
   --upstream, -u              Find source columns for this column [optional]
   --downstream, -d            Find affected columns for this source [optional]
-  --output-format, -f         Output format: 'text', 'json', or 'csv' [default: text]
+  --output-format, -f         Output format: 'text', 'json', 'csv', 'mermaid', 'mermaid-markdown', 'dot', or 'plotly' [default: text]
+```
+
+```
+sqlglider graph visualize <graph_file> [OPTIONS]
+
+Arguments:
+  graph_file                  Path to graph JSON file [required]
+
+Options:
+  --output-format, -f         Diagram format: 'mermaid', 'mermaid-markdown', 'dot', or 'plotly' [default: mermaid]
+  --output-file, -o           Write diagram to file instead of stdout [optional]
 ```
 
 **Notes:**
 - `--upstream` and `--downstream` are mutually exclusive. Use one or the other.
 - Graph queries are case-insensitive for column matching.
+- Plotly output requires optional dependency: `pip install sql-glider[plotly]`
 
 ## Output Formats
 
@@ -889,6 +956,21 @@ UV_PUBLISH_TOKEN=pypi-...
 - **pydantic:** Data validation and serialization
 - **rustworkx:** High-performance graph library for cross-file lineage analysis
 
+### Optional Dependencies
+
+Install optional features with extras:
+
+```bash
+# Databricks catalog integration
+pip install sql-glider[databricks]
+
+# Plotly interactive visualization
+pip install sql-glider[plotly]
+
+# Install multiple extras
+pip install sql-glider[databricks,plotly]
+```
+
 ## References
 
 - [SQLGlot Documentation](https://sqlglot.com/)

sql_glider-0.1.23/PKG-INFO → sql_glider-0.1.25/README.md

@@ -1,35 +1,3 @@
-Metadata-Version: 2.4
-Name: sql-glider
-Version: 0.1.23
-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/
-Project-URL: Documentation, https://github.com/rycowhi/sql-glider/
-Project-URL: Issues, https://github.com/rycowhi/sql-glider/issues
-Author-email: Ryan Whitcomb <ryankwhitcomb@gmail.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-Keywords: data-governance,data-lineage,lineage,sql,sqlglot
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: SQL
-Classifier: Topic :: Database
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Requires-Dist: jinja2>=3.0.0
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: rustworkx>=0.15.0
-Requires-Dist: sqlglot[rs]>=25.0.0
-Requires-Dist: typer>=0.9.0
-Provides-Extra: databricks
-Requires-Dist: databricks-sdk>=0.20.0; extra == 'databricks'
-Description-Content-Type: text/markdown
-
 # SQL Glider
 
 ![SQL Glider Logo](./docs/docs/static/sqlglider-logo-transparent.png)
@@ -420,12 +388,33 @@ uv run sqlglider graph query graph.json --upstream orders.customer_id -f mermaid
 # Query with DOT (Graphviz) diagram output
 uv run sqlglider graph query graph.json --downstream customers.id -f dot
 
+# Query with Plotly JSON output (for interactive visualization)
+uv run sqlglider graph query graph.json --upstream orders.customer_id -f plotly
+
 # Visualize entire graph as a diagram
 uv run sqlglider graph visualize graph.json                    # Mermaid (default)
 uv run sqlglider graph visualize graph.json -f dot             # DOT/Graphviz
+uv run sqlglider graph visualize graph.json -f plotly          # Plotly JSON
 uv run sqlglider graph visualize graph.json -o lineage.mmd     # Save to file
 ```
 
+> **Note:** Plotly output requires an optional dependency. Install with: `pip install sql-glider[plotly]`
+
+The Plotly JSON output can be loaded into Plotly/Dash applications for interactive visualization:
+
+```python
+import plotly.io as pio
+from dash import Dash, dcc, html
+
+# Load the JSON output
+with open("lineage.json") as f:
+    fig = pio.from_json(f.read())
+
+# Use in a Dash app
+app = Dash(__name__)
+app.layout = html.Div([dcc.Graph(figure=fig)])
+```
+
 **Example Upstream Query Output:**
 ```
                               Sources for 'order_totals.total'
@@ -711,12 +700,24 @@ Arguments:
 Options:
   --upstream, -u              Find source columns for this column [optional]
   --downstream, -d            Find affected columns for this source [optional]
-  --output-format, -f         Output format: 'text', 'json', or 'csv' [default: text]
+  --output-format, -f         Output format: 'text', 'json', 'csv', 'mermaid', 'mermaid-markdown', 'dot', or 'plotly' [default: text]
+```
+
+```
+sqlglider graph visualize <graph_file> [OPTIONS]
+
+Arguments:
+  graph_file                  Path to graph JSON file [required]
+
+Options:
+  --output-format, -f         Diagram format: 'mermaid', 'mermaid-markdown', 'dot', or 'plotly' [default: mermaid]
+  --output-file, -o           Write diagram to file instead of stdout [optional]
 ```
 
 **Notes:**
 - `--upstream` and `--downstream` are mutually exclusive. Use one or the other.
 - Graph queries are case-insensitive for column matching.
+- Plotly output requires optional dependency: `pip install sql-glider[plotly]`
 
 ## Output Formats
 
@@ -921,6 +922,21 @@ UV_PUBLISH_TOKEN=pypi-...
 - **pydantic:** Data validation and serialization
 - **rustworkx:** High-performance graph library for cross-file lineage analysis
 
+### Optional Dependencies
+
+Install optional features with extras:
+
+```bash
+# Databricks catalog integration
+pip install sql-glider[databricks]
+
+# Plotly interactive visualization
+pip install sql-glider[plotly]
+
+# Install multiple extras
+pip install sql-glider[databricks,plotly]
+```
+
 ## References
 
 - [SQLGlot Documentation](https://sqlglot.com/)

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

@@ -221,7 +221,7 @@ Each entry in `columns` tells you:
 
 ## Visualizing Lineage
 
-SQL Glider can generate diagrams from lineage graphs in [Mermaid](https://mermaid.js.org/) and [DOT (Graphviz)](https://graphviz.org/doc/info/lang.html) formats. These are text-based diagram languages that render in many tools — Mermaid works natively in GitHub Markdown, GitLab, Notion, and more; DOT can be rendered with Graphviz into SVG, PNG, or PDF.
+SQL Glider can generate diagrams from lineage graphs in [Mermaid](https://mermaid.js.org/), [DOT (Graphviz)](https://graphviz.org/doc/info/lang.html), and [Plotly](https://plotly.com/python/) formats. Mermaid and DOT are text-based diagram languages that render in many tools — Mermaid works natively in GitHub Markdown, GitLab, Notion, and more; DOT can be rendered with Graphviz into SVG, PNG, or PDF. Plotly outputs JSON that can be loaded into interactive Plotly/Dash applications.
 
 ### Visualize an Entire Graph
 
@@ -234,9 +234,13 @@ sqlglider graph visualize graph.json
 # DOT (Graphviz)
 sqlglider graph visualize graph.json -f dot
 
+# Plotly JSON (for interactive visualization)
+sqlglider graph visualize graph.json -f plotly
+
 # Save to file
 sqlglider graph visualize graph.json -o lineage.mmd
 sqlglider graph visualize graph.json -f dot -o lineage.dot
+sqlglider graph visualize graph.json -f plotly -o lineage.json
 ```
 
 ### Diagram Output from Queries
@@ -249,6 +253,9 @@ sqlglider graph query graph.json --upstream total_spent -f mermaid
 
 # DOT diagram of downstream impact
 sqlglider graph query graph.json --downstream orders.order_total -f dot
+
+# Plotly JSON for interactive exploration
+sqlglider graph query graph.json --upstream total_spent -f plotly
 ```
 
 Query diagrams include color-coded nodes and a legend:
@@ -308,6 +315,51 @@ sqlglider graph visualize graph.json -f mermaid-markdown -o lineage.md
 
 This produces output with the `` ```mermaid `` fence included, so the diagram renders automatically when viewed in GitHub, GitLab, or any markdown tool with Mermaid support.
 
+### Plotly Interactive Visualization
+
+The `plotly` format outputs a JSON figure specification that can be loaded into [Plotly](https://plotly.com/python/) or [Dash](https://dash.plotly.com/) applications for interactive visualization with zooming, panning, and hover details.
+
+!!! warning "Optional Dependency"
+
+    Plotly output requires an optional dependency. Install it with:
+
+    ```bash
+    pip install sql-glider[plotly]
+    ```
+
+**Example usage with Dash:**
+
+```python
+import plotly.io as pio
+from dash import Dash, dcc, html
+
+# Load the JSON output from sqlglider
+with open("lineage.json") as f:
+    fig = pio.from_json(f.read())
+
+# Create an interactive Dash app
+app = Dash(__name__)
+app.layout = html.Div([
+    html.H1("Lineage Graph"),
+    dcc.Graph(figure=fig, style={"height": "80vh"})
+])
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```
+
+The Plotly output uses the same color scheme as Mermaid and DOT diagrams:
+
+| Color  | Meaning |
+|--------|---------|
+| Amber  | The queried column |
+| Teal   | Root node (no upstream dependencies) |
+| Violet | Leaf node (no downstream consumers) |
+
+See an example of a plot loaded into Dash below:
+
+![Plotly-Dash Example](./static/plotly-dash-example.png)
+
 ### Rendering Diagrams
 
 **Mermaid:**
@@ -322,6 +374,12 @@ This produces output with the `` ```mermaid `` fence included, so the diagram re
 - Use `-Tsvg` for scalable vector output
 - Many IDEs have Graphviz preview extensions
 
+**Plotly:**
+
+- Load the JSON into any Plotly-compatible environment (Python, Dash, Jupyter notebooks)
+- SQL Glider includes a viewer script: `python examples/plotly_viewer.py lineage.json`
+- Export to static images with `fig.write_image("lineage.png")`
+
 ## Building Graphs from Multiple Sources
 
 ### Explicit File List

sql_glider-0.1.25/examples/plotly_viewer.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""Simple Dash app to view SQL Glider Plotly lineage output.
+
+Usage:
+    # graph visualize has -o flag for file output
+    uv run sqlglider graph visualize graph.json -f plotly -o lineage.json
+    uv run python examples/plotly_viewer.py lineage.json
+
+    # graph query needs shell redirect - use PowerShell on Windows for proper encoding
+    uv run sqlglider graph query graph.json --upstream orders.total -f plotly | Out-File -Encoding utf8 lineage.json
+    uv run python examples/plotly_viewer.py lineage.json
+
+    # On Unix/macOS:
+    sqlglider graph query graph.json --upstream orders.total -f plotly > lineage.json
+    python examples/plotly_viewer.py lineage.json
+"""
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    import dash
+    from dash import dcc, html
+except ImportError:
+    print("Error: Dash is required. Install with: pip install dash", file=sys.stderr)
+    sys.exit(1)
+
+
+def load_figure(source: str | Path | None = None) -> dict:
+    """Load Plotly figure from file or stdin."""
+    if source is None or source == "-":
+        # Read from stdin
+        if sys.stdin.isatty():
+            print("Usage: python plotly_viewer.py <lineage.json>", file=sys.stderr)
+            print(
+                "   or: sqlglider graph visualize graph.json -f plotly | python plotly_viewer.py",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        content = sys.stdin.read()
+        if not content.strip():
+            print("Error: No input received from stdin", file=sys.stderr)
+            print("Note: On Windows, piping may not work reliably.", file=sys.stderr)
+            print(
+                "Try: sqlglider graph query ... -f plotly -o output.json",
+                file=sys.stderr,
+            )
+            print("Then: python plotly_viewer.py output.json", file=sys.stderr)
+            sys.exit(1)
+    else:
+        path = Path(source)
+        if not path.exists():
+            print(f"Error: File not found: {path}", file=sys.stderr)
+            sys.exit(1)
+        # Try multiple encodings - Windows redirect can create UTF-16 files
+        for encoding in ["utf-8", "utf-16", "utf-8-sig"]:
+            try:
+                content = path.read_text(encoding=encoding)
+                break
+            except UnicodeDecodeError:
+                continue
+        else:
+            print(
+                "Error: Could not decode file with UTF-8 or UTF-16 encoding",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid JSON: {e}", file=sys.stderr)
+        if len(content) < 200:
+            print(f"Content received: {content!r}", file=sys.stderr)
+        else:
+            print(f"Content starts with: {content[:200]!r}...", file=sys.stderr)
+        sys.exit(1)
+
+
+def create_app(figure: dict) -> dash.Dash:
+    """Create Dash app with the lineage graph."""
+    app = dash.Dash(__name__)
+
+    title = figure.get("layout", {}).get("title", {}).get("text", "Lineage Graph")
+
+    app.layout = html.Div(
+        [
+            html.H1(title, style={"textAlign": "center", "fontFamily": "sans-serif"}),
+            dcc.Graph(
+                id="lineage-graph",
+                figure=figure,
+                style={"height": "85vh"},
+                config={
+                    "displayModeBar": True,
+                    "scrollZoom": True,
+                    "modeBarButtonsToAdd": ["select2d", "lasso2d"],
+                },
+            ),
+        ],
+        style={"padding": "20px"},
+    )
+
+    return app
+
+
+def main():
+    source = sys.argv[1] if len(sys.argv) > 1 else None
+    figure = load_figure(source)
+    app = create_app(figure)
+
+    print("Starting Dash server at http://127.0.0.1:8050")
+    print("Press Ctrl+C to stop")
+    app.run(debug=True, host="127.0.0.1", port=8050)
+
+
+if __name__ == "__main__":
+    main()