dbxplay 0.1.0__py3-none-any.whl

dbxplay/__init__.py

@@ -0,0 +1,13 @@
+"""
+dbxplay — A Databricks-like interactive display() function
+for Jupyter Notebooks, AWS Glue, Google Colab, and VS Code.
+
+Usage:
+    from dbxplay import display
+    display(df)
+"""
+
+from dbxplay.core import display
+
+__version__ = "0.1.0"
+__all__ = ["display"]

dbxplay/core.py

@@ -0,0 +1,288 @@
+"""
+core.py — Main display() function and DataFrame type detection/conversion.
+"""
+
+import json
+import uuid
+import html as html_module
+import math
+from typing import Any, Dict, List, Optional, Union
+
+from dbxplay.templates import render_table_html
+
+
+def _is_pyspark_dataframe(obj: Any) -> bool:
+    """Check if the object is a PySpark DataFrame without importing PySpark."""
+    cls_name = type(obj).__name__
+    module = type(obj).__module__ or ""
+    return cls_name == "DataFrame" and "pyspark" in module
+
+
+def _is_pandas_dataframe(obj: Any) -> bool:
+    """Check if the object is a Pandas DataFrame."""
+    cls_name = type(obj).__name__
+    module = type(obj).__module__ or ""
+    return cls_name == "DataFrame" and "pandas" in module
+
+
+def _is_polars_dataframe(obj: Any) -> bool:
+    """Check if the object is a Polars DataFrame."""
+    cls_name = type(obj).__name__
+    module = type(obj).__module__ or ""
+    return cls_name == "DataFrame" and "polars" in module
+
+
+def _infer_dtype_category(values: list, col_name: str = "") -> str:
+    """Infer a human-readable dtype category from a sample of Python values.
+
+    Returns one of: 'string', 'integer', 'float', 'boolean', 'datetime', 'complex'
+    """
+    import datetime as dt
+
+    non_none = [v for v in values if v is not None]
+    if not non_none:
+        return "string"
+
+    sample = non_none[:50]
+
+    # Check boolean first (bool is subclass of int in Python)
+    if all(isinstance(v, bool) for v in sample):
+        return "boolean"
+    if all(isinstance(v, int) and not isinstance(v, bool) for v in sample):
+        return "integer"
+    if all(isinstance(v, (int, float)) and not isinstance(v, bool) for v in sample):
+        return "float"
+    if all(isinstance(v, (dt.datetime, dt.date)) for v in sample):
+        return "datetime"
+    if all(isinstance(v, (dict, list)) for v in sample):
+        return "complex"
+
+    # Try to detect string-encoded timestamps
+    str_vals = [v for v in sample if isinstance(v, str)]
+    if str_vals and len(str_vals) == len(sample):
+        ts_count = sum(1 for s in str_vals[:10] if len(s) >= 10 and s[4:5] == "-")
+        if ts_count >= len(str_vals[:10]) * 0.8:
+            return "datetime"
+
+    return "string"
+
+
+def _pandas_dtype_to_category(dtype) -> str:
+    """Convert a pandas dtype to our category string."""
+    dtype_str = str(dtype).lower()
+    if "bool" in dtype_str:
+        return "boolean"
+    if "int" in dtype_str:
+        return "integer"
+    if "float" in dtype_str or "double" in dtype_str:
+        return "float"
+    if "datetime" in dtype_str or "timestamp" in dtype_str:
+        return "datetime"
+    if "object" in dtype_str or "string" in dtype_str or "str" in dtype_str:
+        return "string"
+    if "category" in dtype_str:
+        return "string"
+    return "string"
+
+
+def _spark_dtype_to_category(dtype_str: str) -> str:
+    """Convert a PySpark dtype string to our category string."""
+    dtype_str = dtype_str.lower()
+    if "bool" in dtype_str:
+        return "boolean"
+    if "int" in dtype_str or "long" in dtype_str or "short" in dtype_str or "byte" in dtype_str:
+        return "integer"
+    if "float" in dtype_str or "double" in dtype_str or "decimal" in dtype_str:
+        return "float"
+    if "timestamp" in dtype_str or "date" in dtype_str:
+        return "datetime"
+    if "struct" in dtype_str or "array" in dtype_str or "map" in dtype_str:
+        return "complex"
+    return "string"
+
+
+def _polars_dtype_to_category(dtype) -> str:
+    """Convert a Polars dtype to our category string."""
+    dtype_str = str(dtype).lower()
+    if "bool" in dtype_str:
+        return "boolean"
+    if "int" in dtype_str or "uint" in dtype_str:
+        return "integer"
+    if "float" in dtype_str or "decimal" in dtype_str:
+        return "float"
+    if "date" in dtype_str or "time" in dtype_str or "duration" in dtype_str:
+        return "datetime"
+    if "struct" in dtype_str or "list" in dtype_str:
+        return "complex"
+    return "string"
+
+
+def _safe_str(val: Any) -> str:
+    """Convert a value to a display-safe string."""
+    if val is None:
+        return "null"
+    if isinstance(val, bool):
+        return str(val).lower()
+    if isinstance(val, float):
+        if val != val:  # NaN check
+            return "NaN"
+        if val == float("inf"):
+            return "Infinity"
+        if val == float("-inf"):
+            return "-Infinity"
+    return str(val)
+
+
+def _convert_to_records(
+    data: Any,
+    limit: int = 1000,
+) -> tuple:
+    """Convert various DataFrame types to a list of dicts and column metadata.
+
+    Returns:
+        (records: List[Dict], columns: List[Dict], total_rows: int, truncated: bool)
+        Each column dict has keys: 'name', 'dtype_category'
+    """
+
+    if _is_pyspark_dataframe(data):
+        total_rows = None
+        limited = data.limit(limit)
+        pdf = limited.toPandas()
+        records = pdf.to_dict("records")
+        columns = []
+        for field in data.schema.fields:
+            columns.append({
+                "name": field.name,
+                "dtype_category": _spark_dtype_to_category(str(field.dataType)),
+            })
+        truncated = len(records) >= limit
+        return records, columns, total_rows, truncated
+
+    if _is_pandas_dataframe(data):
+        total_rows = len(data)
+        truncated = total_rows > limit
+        df_sample = data.head(limit) if truncated else data
+        records = json.loads(df_sample.to_json(orient="records", date_format="iso", default_handler=str))
+        columns = []
+        for col_name in data.columns:
+            columns.append({
+                "name": str(col_name),
+                "dtype_category": _pandas_dtype_to_category(data[col_name].dtype),
+            })
+        return records, columns, total_rows, truncated
+
+    if _is_polars_dataframe(data):
+        total_rows = data.height
+        truncated = total_rows > limit
+        df_sample = data.head(limit) if truncated else data
+        records = df_sample.to_dicts()
+        columns = []
+        for col_name in data.columns:
+            columns.append({
+                "name": col_name,
+                "dtype_category": _polars_dtype_to_category(data[col_name].dtype),
+            })
+        return records, columns, total_rows, truncated
+
+    if isinstance(data, list):
+        if not data:
+            return [], [], 0, False
+        total_rows = len(data)
+        truncated = total_rows > limit
+        sample = data[:limit]
+
+        if isinstance(sample[0], dict):
+            records = sample
+            all_keys = []
+            seen = set()
+            for row in sample:
+                for k in row:
+                    if k not in seen:
+                        all_keys.append(k)
+                        seen.add(k)
+            columns = []
+            for k in all_keys:
+                vals = [row.get(k) for row in sample]
+                columns.append({
+                    "name": str(k),
+                    "dtype_category": _infer_dtype_category(vals, str(k)),
+                })
+            return records, columns, total_rows, truncated
+        else:
+            records = [{"value": v} for v in sample]
+            columns = [{"name": "value", "dtype_category": _infer_dtype_category(sample)}]
+            return records, columns, total_rows, truncated
+
+    if isinstance(data, dict):
+        col_names = list(data.keys())
+        max_len = max((len(v) if isinstance(v, list) else 1) for v in data.values()) if data else 0
+        total_rows = max_len
+        truncated = total_rows > limit
+        actual_len = min(max_len, limit)
+        records = []
+        for i in range(actual_len):
+            row = {}
+            for c in col_names:
+                vals = data[c]
+                if isinstance(vals, list):
+                    row[c] = vals[i] if i < len(vals) else None
+                else:
+                    row[c] = vals
+            records.append(row)
+        columns = []
+        for c in col_names:
+            vals = data[c] if isinstance(data[c], list) else [data[c]]
+            columns.append({
+                "name": str(c),
+                "dtype_category": _infer_dtype_category(vals[:50], str(c)),
+            })
+        return records, columns, total_rows, truncated
+
+    raise TypeError(
+        f"display() does not support type '{type(data).__name__}'. "
+        "Supported types: PySpark DataFrame, Pandas DataFrame, Polars DataFrame, list, dict."
+    )
+
+
+def display(
+    data: Any,
+    limit: int = 1000,
+    title: str = "Table",
+    height: Optional[int] = None,
+) -> None:
+    """Display a DataFrame or data structure in an interactive Databricks-style table.
+
+    Args:
+        data: A PySpark, Pandas, or Polars DataFrame, or a list of dicts / dict of lists.
+        limit: Maximum number of rows to display (default 1000). PySpark DataFrames
+               are automatically limited to avoid OOM.
+        title: The tab title shown in the top bar (default "Table").
+        height: Optional fixed height in pixels for the table container. If None,
+                the table auto-sizes up to ~500px then scrolls.
+    """
+    from IPython.display import display as ipy_display, HTML
+
+    records, columns, total_rows, truncated = _convert_to_records(data, limit=limit)
+
+    # Sanitize all record values for safe JSON embedding
+    safe_records = []
+    for row in records:
+        safe_row = {}
+        for k, v in row.items():
+            safe_row[k] = _safe_str(v)
+        safe_records.append(safe_row)
+
+    table_id = "db_table_" + uuid.uuid4().hex[:12]
+
+    html_str = render_table_html(
+        table_id=table_id,
+        records=safe_records,
+        columns=columns,
+        total_rows=total_rows,
+        truncated=truncated,
+        limit=limit,
+        title=title,
+        height=height,
+    )
+
+    ipy_display(HTML(html_str))

dbxplay/icons.py

@@ -0,0 +1,171 @@
+"""
+SVG icons used in the Databricks-like table UI.
+These are inline SVG strings matching the Databricks visual style.
+"""
+
+
+def get_type_icon_svg(dtype_category: str) -> str:
+    """Return an inline SVG icon for the given data type category.
+
+    Categories: 'string', 'integer', 'float', 'boolean', 'datetime', 'complex'
+    """
+    icons = {
+        # ABC icon for string columns
+        "string": (
+            '<svg class="db-type-icon" viewBox="0 0 16 16" width="14" height="14" fill="none">'
+            '<text x="1" y="12" font-size="7.5" font-weight="700" fill="#5f6368" '
+            'font-family="Arial,sans-serif" letter-spacing="0.5">'
+            '<tspan fill="#1a73e8">A</tspan>'
+            '<tspan fill="#5f6368">B</tspan>'
+            '</text>'
+            '<text x="10.5" y="8" font-size="5.5" font-weight="600" fill="#5f6368" '
+            'font-family="Arial,sans-serif">C</text>'
+            '</svg>'
+        ),
+        # 123 icon for integer columns
+        "integer": (
+            '<svg class="db-type-icon" viewBox="0 0 16 16" width="14" height="14" fill="none">'
+            '<text x="0" y="12" font-size="10" font-weight="700" fill="#5f6368" '
+            'font-family="Arial,sans-serif" letter-spacing="-0.5">#</text>'
+            '</svg>'
+        ),
+        # Decimal icon for float columns
+        "float": (
+            '<svg class="db-type-icon" viewBox="0 0 16 16" width="14" height="14" fill="none">'
+            '<text x="0" y="12" font-size="7" font-weight="700" fill="#5f6368" '
+            'font-family="Arial,sans-serif" letter-spacing="-0.2">1.2</text>'
+            '</svg>'
+        ),
+        # T/F icon for boolean columns
+        "boolean": (
+            '<svg class="db-type-icon" viewBox="0 0 16 16" width="14" height="14" fill="none">'
+            '<text x="0" y="12" font-size="7.5" font-weight="700" fill="#5f6368" '
+            'font-family="Arial,sans-serif">'
+            '<tspan fill="#1a73e8">T</tspan>'
+            '<tspan fill="#5f6368">/F</tspan>'
+            '</text>'
+            '</svg>'
+        ),
+        # Calendar icon for datetime columns
+        "datetime": (
+            '<svg class="db-type-icon" viewBox="0 0 16 16" width="14" height="14" fill="none">'
+            '<rect x="1" y="3" width="14" height="12" rx="2" stroke="#5f6368" stroke-width="1.3" fill="none"/>'
+            '<line x1="1" y1="7" x2="15" y2="7" stroke="#5f6368" stroke-width="1.3"/>'
+            '<line x1="5" y1="1" x2="5" y2="5" stroke="#5f6368" stroke-width="1.3" stroke-linecap="round"/>'
+            '<line x1="11" y1="1" x2="11" y2="5" stroke="#5f6368" stroke-width="1.3" stroke-linecap="round"/>'
+            '<rect x="4" y="9.5" width="2.5" height="2" rx="0.5" fill="#1a73e8"/>'
+            '</svg>'
+        ),
+        # Braces icon for complex/json columns
+        "complex": (
+            '<svg class="db-type-icon" viewBox="0 0 16 16" width="14" height="14" fill="none">'
+            '<text x="1" y="13" font-size="12" font-weight="400" fill="#5f6368" '
+            'font-family="Arial,sans-serif">{}</text>'
+            '</svg>'
+        ),
+    }
+    return icons.get(dtype_category, icons["string"])
+
+
+def get_sort_icon_svg() -> str:
+    """Return the sort arrow SVG for column headers."""
+    return (
+        '<svg class="db-sort-icon" viewBox="0 0 10 14" width="8" height="12" fill="none">'
+        '<path class="db-sort-asc" d="M5 0L9 5H1L5 0Z" fill="#bcc0c4"/>'
+        '<path class="db-sort-desc" d="M5 14L1 9H9L5 14Z" fill="#bcc0c4"/>'
+        '</svg>'
+    )
+
+
+def get_chevron_down_svg(size: int = 12) -> str:
+    """Return a small chevron-down SVG for dropdown indicators."""
+    return (
+        f'<svg viewBox="0 0 10 6" width="{size}" height="{size}" fill="none" '
+        f'style="vertical-align:middle;">'
+        f'<path d="M1 1L5 5L9 1" stroke="#444" stroke-width="1.5" '
+        f'stroke-linecap="round" stroke-linejoin="round"/>'
+        f'</svg>'
+    )
+
+
+def get_plus_svg(size: int = 14) -> str:
+    """Return a plus icon SVG."""
+    return (
+        f'<svg viewBox="0 0 12 12" width="{size}" height="{size}" fill="none">'
+        f'<path d="M6 1V11M1 6H11" stroke="#666" stroke-width="1.5" '
+        f'stroke-linecap="round"/>'
+        f'</svg>'
+    )
+
+
+def get_download_svg() -> str:
+    """Return a download icon SVG."""
+    return (
+        '<svg viewBox="0 0 16 16" width="14" height="14" fill="none">'
+        '<path d="M8 2V10M8 10L5 7M8 10L11 7" stroke="#333" stroke-width="1.4" '
+        'stroke-linecap="round" stroke-linejoin="round"/>'
+        '<path d="M3 13H13" stroke="#333" stroke-width="1.4" stroke-linecap="round"/>'
+        '</svg>'
+    )
+
+
+def get_copy_svg() -> str:
+    """Return a copy icon SVG."""
+    return (
+        '<svg viewBox="0 0 16 16" width="14" height="14" fill="none">'
+        '<rect x="5" y="5" width="8" height="9" rx="1.5" stroke="#333" stroke-width="1.2"/>'
+        '<path d="M11 5V3.5A1.5 1.5 0 009.5 2H3.5A1.5 1.5 0 002 3.5V10.5A1.5 1.5 0 003.5 12H5" '
+        'stroke="#333" stroke-width="1.2"/>'
+        '</svg>'
+    )
+
+
+def get_filter_svg() -> str:
+    """Return a filter funnel icon SVG."""
+    return (
+        '<svg viewBox="0 0 16 16" width="14" height="14" fill="none">'
+        '<path d="M2 3H14L10 8.5V12L6 14V8.5L2 3Z" stroke="#333" stroke-width="1.2" '
+        'stroke-linejoin="round"/>'
+        '</svg>'
+    )
+
+
+def get_exclude_svg() -> str:
+    """Return a circle-slash (exclude) icon SVG."""
+    return (
+        '<svg viewBox="0 0 16 16" width="14" height="14" fill="none">'
+        '<circle cx="8" cy="8" r="6" stroke="#333" stroke-width="1.2"/>'
+        '<line x1="3.5" y1="12.5" x2="12.5" y2="3.5" stroke="#333" stroke-width="1.2"/>'
+        '</svg>'
+    )
+
+
+def get_panel_svg() -> str:
+    """Return a side-panel toggle icon SVG."""
+    return (
+        '<svg viewBox="0 0 16 16" width="14" height="14" fill="none">'
+        '<rect x="1" y="2" width="14" height="12" rx="2" stroke="#333" stroke-width="1.2"/>'
+        '<line x1="10" y1="2" x2="10" y2="14" stroke="#333" stroke-width="1.2"/>'
+        '</svg>'
+    )
+
+
+def get_search_svg() -> str:
+    """Return a search/magnifying glass icon SVG."""
+    return (
+        '<svg viewBox="0 0 16 16" width="14" height="14" fill="none">'
+        '<circle cx="7" cy="7" r="4.5" stroke="#888" stroke-width="1.3"/>'
+        '<line x1="10.5" y1="10.5" x2="14" y2="14" stroke="#888" stroke-width="1.3" '
+        'stroke-linecap="round"/>'
+        '</svg>'
+    )
+
+
+def get_close_svg(size: int = 12) -> str:
+    """Return a small X close icon SVG."""
+    return (
+        f'<svg viewBox="0 0 10 10" width="{size}" height="{size}" fill="none">'
+        f'<path d="M2 2L8 8M8 2L2 8" stroke="#666" stroke-width="1.5" '
+        f'stroke-linecap="round"/>'
+        f'</svg>'
+    )