dash-control 0.1.1__py3-none-any.whl

dash_control-0.1.1.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: dash-control
+Version: 0.1.1
+Summary: Databricks Control Center — live system-table dashboard for platform, governance, cost, users, jobs, and queries
+Project-URL: Homepage, https://github.com/dash-libs/dash-control
+Author-email: Darshan Shah <darshan.innovation@gmail.com>
+License: Apache-2.0
+Keywords: control-center,cost,dashboard,databricks,governance,observability,system-tables,unity-catalog
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: dash-uis==0.2.3
+Requires-Dist: ipywidgets>=8.0
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pdoc; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dash-control
+
+**Databricks Control Center** — a live, 8-panel system-table dashboard for platform, governance, cost, and operations teams. One `%pip install` + one `launch()` call gives you an always-on view of your entire Databricks workspace.
+
+```python
+%pip install dash-control
+from dashcontrol import launch, ControlCenterConfig
+
+config = ControlCenterConfig(
+    date_range_days=30,
+    catalogs=["main", "analytics"],
+)
+launch(config)
+```
+
+## Panels
+
+| Panel | What it shows |
+|---|---|
+| **Health** | DBU today, active users, failed jobs (last 24 h), total table count, 7-day DBU sparkline |
+| **Cost** | Daily spend by SKU, top clusters, top jobs, top users by DBU, burn-rate projection |
+| **Users** | Top users by query count & tables accessed, inactive users, permission changes |
+| **Catalog** | Table inventory, tables by schema, stale tables, column count distribution, most-accessed tables |
+| **Jobs** | Success rate, top failures, longest runs, daily run volume trend |
+| **Queries** | Slowest queries, most expensive queries, top users, error summary |
+| **Governance** | Tables without owners, PII columns, access anomalies, schema changes |
+| **Custom** | Run any SQL against system tables; define custom panels in `ControlCenterConfig` |
+
+## Configuration
+
+```python
+from dashcontrol import ControlCenterConfig, CustomPanel
+
+config = ControlCenterConfig(
+    date_range_days=14,          # default look-back window (also adjustable in the UI)
+    catalogs=["main"],           # limit catalog scope; empty = all catalogs
+    panels=["health", "cost"],   # show only these panels
+    row_limit=200,               # max rows per table result
+    workspace_name="prod",       # displayed in the header
+    custom_panels=[
+        CustomPanel(
+            name="My Query",
+            sql="SELECT user_name, COUNT(*) AS cnt FROM system.access.audit GROUP BY 1",
+            description="Custom audit rollup",
+        )
+    ],
+)
+```
+
+## Requirements
+
+- Databricks Runtime 13.3 LTS or later (system tables must be enabled)
+- Unity Catalog workspace
+- `ipywidgets` (included as a dependency)
+
+## Architecture
+
+Every panel is **lazy-loaded** — clicking Load runs the query; nothing executes on `launch()`. Queries target Databricks system tables (`system.billing.*`, `system.access.audit`, `system.jobs.*`, `system.query.history`, `system.information_schema.*`). All queries degrade gracefully: if a system table isn't available on your workspace tier, the panel shows an info banner instead of crashing.
+
+## Part of the DashLibs suite
+
+| Package | Purpose |
+|---|---|
+| [dash-dq](https://pypi.org/project/dash-dq/) | 60+ data quality checks |
+| [dash-synthetic](https://pypi.org/project/dash-synthetic/) | Synthetic data generation |
+| [dash-observe](https://pypi.org/project/dash-observe/) | Freshness, volume & schema monitoring |
+| [dash-gov](https://pypi.org/project/dash-gov/) | Table/column lineage + role classification |
+| [dash-ontology](https://pypi.org/project/dash-ontology/) | Auto-inferred business ontology from lineage |
+| **dash-control** | Control Center — this package |
+
+## License
+
+Apache 2.0

dash_control-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+dashcontrol/__init__.py,sha256=1k2hWujkfIk-F8Nm5yYxWDd2NRjEWGD6JdMZQA3SORg,229
+dashcontrol/config.py,sha256=pd8OoxDMjHtzSC_8iGrICd76inlMzJl6lDV71jTvbeA,2152
+dashcontrol/formatters.py,sha256=pF81n5HivSK2pXYQn5ztZxhgBpTGg288T2ZAORMdJvk,5528
+dashcontrol/runner.py,sha256=u05oNBdqKORmtQSobkW6Ln-7DZ92db9L6GKbu08H3dU,2511
+dashcontrol/sql.py,sha256=6qCVek5EvvN7iGYPVnb5j2EU2GQhzE6YDVDJ4B0y9cg,18083
+dashcontrol/ui.py,sha256=ENWTFrEZ1gchWgt4OheC4CdSslc3Rzx6kYqmJWC19qs,20934
+dash_control-0.1.1.dist-info/METADATA,sha256=7tdps6aVCPdM6t13lUQP7tE29Ab8-ieCMSHzzdYopqM,4457
+dash_control-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+dash_control-0.1.1.dist-info/RECORD,,

dash_control-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

dashcontrol/__init__.py

@@ -0,0 +1,6 @@
+"""DashControl — Databricks Control Center."""
+from dashcontrol.config import ControlCenterConfig, CustomPanel
+from dashcontrol.ui import launch
+
+__version__ = "0.1.1"
+__all__ = ["ControlCenterConfig", "CustomPanel", "launch"]

dashcontrol/config.py

@@ -0,0 +1,62 @@
+"""
+ControlCenterConfig — user-facing configuration for the Control Center.
+
+All fields have sensible defaults so teams can call launch() with zero config,
+or pre-wire a domain-specific dashboard by passing a config object.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+ALL_PANELS = ["health", "cost", "users", "catalog", "jobs", "queries", "governance"]
+
+
+@dataclass
+class CustomPanel:
+    title: str
+    sql: str
+    description: str = ""
+
+
+@dataclass
+class ControlCenterConfig:
+    """
+    Configuration for the Databricks Control Center.
+
+    Parameters
+    ----------
+    date_range_days
+        Default lookback window for all time-based queries (default: 30).
+    catalogs
+        List of catalogs to scope table/lineage queries to.
+        Empty list means all visible catalogs.
+    panels
+        Which built-in panels to show. Defaults to all.
+    custom_panels
+        User-defined SQL panels appended after the built-in tabs.
+    row_limit
+        Max rows returned per panel query (default: 500).
+    workspace_name
+        Optional display name shown in the dashboard header.
+    """
+    date_range_days: int = 30
+    catalogs: list[str] = field(default_factory=list)
+    panels: list[str] = field(default_factory=lambda: list(ALL_PANELS))
+    custom_panels: list[CustomPanel] = field(default_factory=list)
+    row_limit: int = 500
+    workspace_name: str = ""
+
+    def __post_init__(self):
+        unknown = set(self.panels) - set(ALL_PANELS)
+        if unknown:
+            raise ValueError(f"Unknown panels: {unknown}. Valid: {ALL_PANELS}")
+        if self.date_range_days < 1 or self.date_range_days > 365:
+            raise ValueError("date_range_days must be between 1 and 365")
+        if self.row_limit < 1 or self.row_limit > 10_000:
+            raise ValueError("row_limit must be between 1 and 10,000")
+
+    def catalog_filter(self, col: str = "table_catalog") -> str:
+        """SQL WHERE fragment to filter by configured catalogs."""
+        if not self.catalogs:
+            return ""
+        quoted = ", ".join(f"'{c}'" for c in self.catalogs)
+        return f"AND {col} IN ({quoted})"

dashcontrol/formatters.py

@@ -0,0 +1,161 @@
+"""
+Pure-Python formatting utilities — no Spark dependency.
+
+Converts query result rows (list[dict]) into styled HTML tables,
+stat tiles, trend sparklines, and CSV exports for the Control Center UI.
+"""
+from __future__ import annotations
+from typing import Optional
+
+# Colour palette
+_TEAL   = "#2A9D90"
+_AMBER  = "#F4A261"
+_RED    = "#E63946"
+_GREEN  = "#2DC653"
+_GREY   = "#6B7280"
+_LIGHT  = "#F9FAFB"
+_BORDER = "#E5E7EB"
+
+
+def stat_tile(label: str, value, color: str = _TEAL, unit: str = "") -> str:
+    """Render a single KPI tile (label + big number)."""
+    return (
+        f"<div style='display:inline-block;padding:14px 20px;margin:6px;"
+        f"border-radius:8px;background:{_LIGHT};border:1px solid {_BORDER};"
+        f"min-width:140px;text-align:center'>"
+        f"<div style='font-size:26px;font-weight:700;color:{color}'>"
+        f"{value}{unit}</div>"
+        f"<div style='font-size:11px;color:{_GREY};margin-top:4px'>{label}</div>"
+        f"</div>"
+    )
+
+
+def stat_row(tiles: list[str]) -> str:
+    """Wrap stat tiles in a flex row."""
+    inner = "".join(tiles)
+    return f"<div style='display:flex;flex-wrap:wrap;gap:4px;margin-bottom:12px'>{inner}</div>"
+
+
+def html_table(
+    rows: list[dict],
+    highlight_col: Optional[str] = None,
+    max_rows: int = 200,
+    col_widths: Optional[dict] = None,
+) -> str:
+    """
+    Convert a list of row-dicts to a styled HTML table.
+
+    highlight_col — column whose values determine row background colour
+                    (high numeric value = amber, error strings = red)
+    """
+    if not rows:
+        return "<div style='color:#9ca3af;font-size:12px;padding:8px'>No data</div>"
+
+    cols = list(rows[0].keys())
+    col_widths = col_widths or {}
+
+    def _header(col: str) -> str:
+        w = f"min-width:{col_widths[col]};" if col in col_widths else ""
+        label = col.replace("_", " ").title()
+        return (
+            f"<th style='padding:6px 10px;background:#F3F4F6;text-align:left;"
+            f"font-size:11px;color:{_GREY};font-weight:600;white-space:nowrap;{w}'>"
+            f"{label}</th>"
+        )
+
+    def _cell(val, col: str) -> str:
+        text = "" if val is None else str(val)
+        # Truncate long strings
+        display = text[:80] + "…" if len(text) > 80 else text
+        return (
+            f"<td style='padding:5px 10px;font-size:12px;"
+            f"font-family:monospace;border-top:1px solid {_BORDER}'>"
+            f"{display}</td>"
+        )
+
+    def _row_bg(row: dict) -> str:
+        if highlight_col and highlight_col in row:
+            v = row[highlight_col]
+            if isinstance(v, str) and any(k in v.upper() for k in ("FAIL", "ERROR", "DENIED")):
+                return "background:#FEF2F2;"
+        return ""
+
+    headers = "".join(_header(c) for c in cols)
+    body_rows = ""
+    for r in rows[:max_rows]:
+        bg = _row_bg(r)
+        cells = "".join(_cell(r.get(c), c) for c in cols)
+        body_rows += f"<tr style='{bg}'>{cells}</tr>"
+
+    footer = ""
+    if len(rows) > max_rows:
+        footer = (
+            f"<tr><td colspan='{len(cols)}' style='padding:6px 10px;"
+            f"font-size:11px;color:{_GREY};text-align:center'>"
+            f"Showing {max_rows} of {len(rows)} rows</td></tr>"
+        )
+
+    return (
+        f"<div style='overflow-x:auto'>"
+        f"<table style='border-collapse:collapse;width:100%;font-size:12px'>"
+        f"<thead><tr>{headers}</tr></thead>"
+        f"<tbody>{body_rows}{footer}</tbody>"
+        f"</table></div>"
+    )
+
+
+def error_box(message: str) -> str:
+    """Red alert box for query errors."""
+    return (
+        f"<div style='padding:10px 14px;background:#FEF2F2;border:1px solid #FCA5A5;"
+        f"border-radius:6px;color:{_RED};font-size:12px;font-family:monospace'>"
+        f"⚠ {message}</div>"
+    )
+
+
+def info_box(message: str) -> str:
+    """Blue info box."""
+    return (
+        f"<div style='padding:10px 14px;background:#EFF6FF;border:1px solid #BFDBFE;"
+        f"border-radius:6px;color:#1D4ED8;font-size:12px'>"
+        f"ℹ {message}</div>"
+    )
+
+
+def section_header(title: str, subtitle: str = "") -> str:
+    sub = f"<span style='font-size:11px;color:{_GREY};margin-left:8px'>{subtitle}</span>" if subtitle else ""
+    return (
+        f"<div style='font-weight:600;font-size:13px;color:#374151;"
+        f"margin:12px 0 6px;padding-bottom:4px;border-bottom:1px solid {_BORDER}'>"
+        f"{title}{sub}</div>"
+    )
+
+
+def sparkline_html(values: list[float], label: str = "") -> str:
+    """
+    Minimal ASCII sparkline for trend data (no JS/SVG required).
+    Uses Unicode block characters: ▁▂▃▄▅▆▇█
+    """
+    blocks = "▁▂▃▄▅▆▇█"
+    if not values or all(v == 0 for v in values):
+        return f"<span style='font-family:monospace;color:{_GREY}'>{'▁' * 10}</span>"
+    mn, mx = min(values), max(values)
+    rng = mx - mn or 1
+    chars = "".join(blocks[min(7, int((v - mn) / rng * 7))] for v in values)
+    return (
+        f"<span style='font-family:monospace;font-size:14px;color:{_TEAL}'>{chars}</span>"
+        + (f"<span style='font-size:10px;color:{_GREY};margin-left:4px'>{label}</span>" if label else "")
+    )
+
+
+def format_number(n) -> str:
+    """Format large numbers with K/M suffixes."""
+    try:
+        n = float(n)
+    except (TypeError, ValueError):
+        return str(n)
+    if abs(n) >= 1_000_000:
+        return f"{n / 1_000_000:.1f}M"
+    if abs(n) >= 1_000:
+        return f"{n / 1_000:.1f}K"
+    return f"{n:,.0f}" if n == int(n) else f"{n:,.2f}"

dashcontrol/runner.py

@@ -0,0 +1,78 @@
+"""
+Query runner — executes SQL against Databricks system tables.
+
+Spark is imported inside functions only (never at module level) so this
+module can be imported and tested without a live Spark session.
+"""
+from __future__ import annotations
+from typing import Optional
+
+
+class QueryResult:
+    """Holds the result of a panel query with metadata."""
+
+    def __init__(self, rows: list[dict], sql: str, error: Optional[str] = None):
+        self.rows = rows
+        self.sql = sql
+        self.error = error
+        self.ok = error is None
+
+    def __len__(self) -> int:
+        return len(self.rows)
+
+    def column_names(self) -> list[str]:
+        return list(self.rows[0].keys()) if self.rows else []
+
+    def column_values(self, col: str) -> list:
+        return [r.get(col) for r in self.rows]
+
+    def first_value(self, col: str, default=None):
+        return self.rows[0].get(col, default) if self.rows else default
+
+    def to_csv(self) -> str:
+        if not self.rows:
+            return ""
+        cols = self.column_names()
+        lines = [",".join(str(c) for c in cols)]
+        for row in self.rows:
+            lines.append(",".join(str(row.get(c, "")) for c in cols))
+        return "\n".join(lines)
+
+
+def run_query(sql: str, limit: int = 500) -> QueryResult:
+    """
+    Execute a SQL query against Databricks system tables.
+
+    Uses the active SparkSession — must be run inside a Databricks notebook
+    (or any environment where a SparkSession is already active).
+
+    Parameters
+    ----------
+    sql   : SQL string (use functions from dashcontrol.sql)
+    limit : max rows to return
+
+    Returns
+    -------
+    QueryResult with .rows (list of dicts) and .ok / .error
+    """
+    try:
+        from pyspark.sql import SparkSession
+        spark = SparkSession.getActiveSession()
+        if spark is None:
+            return QueryResult([], sql, error="No active Spark session. Run inside a Databricks notebook.")
+        df = spark.sql(sql.strip())
+        rows = [r.asDict() for r in df.limit(limit).collect()]
+        return QueryResult(rows, sql)
+    except Exception as e:
+        return QueryResult([], sql, error=str(e))
+
+
+def run_query_safe(sql: str, limit: int = 500) -> QueryResult:
+    """
+    Same as run_query but returns a QueryResult with error set (never raises)
+    even for system tables that don't exist on the current workspace tier.
+    """
+    try:
+        return run_query(sql, limit)
+    except Exception as e:
+        return QueryResult([], sql, error=str(e))