Metadata-Version: 2.4
Name: dbxplay
Version: 1.0.2
Summary: A Databricks-like interactive display() function for Jupyter Notebooks, AWS Glue, Google Colab, and VS Code.
Author: Varun
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: ipython>=7.0
Provides-Extra: pandas
Requires-Dist: pandas>=1.0; extra == "pandas"
Provides-Extra: polars
Requires-Dist: polars>=0.14; extra == "polars"
Provides-Extra: pyspark
Requires-Dist: pyspark>=3.0; extra == "pyspark"
Provides-Extra: all
Requires-Dist: pandas>=1.0; extra == "all"
Requires-Dist: polars>=0.14; extra == "all"
Requires-Dist: pyspark>=3.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pandas>=1.0; extra == "dev"

# dbxplay

A Databricks-like interactive `display()` function for **Jupyter Notebooks**, **AWS Glue**, **Google Colab**, and **VS Code**.

Brings the beautiful, interactive table UI from Databricks into any Python notebook environment — with sorting, filtering, searching, customizable X/Y charting, data profiling, context menus, column resizing, CSV/Excel export, and more.

## Installation

```bash
pip install dbxplay
```

Or install locally in editable mode:

```bash
pip install -e .
```

## Quick Start

```python
from dbxplay import display
import pandas as pd

df = pd.read_csv("your_data.csv")
display(df)
```

## Usage & Examples

```python
from dbxplay import display, init

# Package-level theme and mode initialization
# Modes: 'auto' (detect Glue/notebook), 'text' (Glue/stdout), 'html' (interactive notebook)
init(theme="dark", mode="auto")

# Basic usage (uses package default theme and mode)
display(df)

# Explicitly use text rendering mode (ideal for AWS Glue / CloudWatch logs / stdout)
display(df, mode="text")

# Override theme per display call
display(df, theme="light")
display(df, theme="dark")

# Stratified sampling across categories (PySpark, Pandas, Polars)
display(df, stratify_by="user_tier")

# Enable iframe srcdoc encapsulation (auto-enabled in AWS Glue Notebooks)
init(theme="dark", mode="html", use_iframe=True)

# Explicitly pass use_iframe per call
display(df, use_iframe=True)

# Sample more rows (e.g. 5,000)
display(df, limit=5000)

# Display all rows without truncation
display(df, limit=None)

# With options
display(df, limit=500, title="My Data", height=400, stratify_by="country_code", theme="dark", mode="auto", use_iframe=True)
```

### Parameters

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `data` | DataFrame/list/dict | *(required)* | The data to display |
| `limit` | int / None | 1000 | Max rows to render (pass a higher int like `5000`, or `None` for unlimited) |
| `title` | str | "Table" | Tab title in the top bar |
| `height` | int | None | Fixed height in px (auto-sizes to ~520px) |
| `stratify_by` | str | None | Optional column name to perform stratified sampling across categories |
| `theme` | str / None | None | Theme to render ('light' or 'dark'). Defaults to package theme set via `init(theme=...)` |
| `mode` | str / None | None | Rendering mode (`'auto'`, `'text'`, or `'html'`). In notebooks, renders interactive HTML widgets |
| `use_iframe` | bool / None | None | Encapsulate HTML inside an `<iframe srcdoc="...">` tag. Automatically enabled for AWS Glue Notebooks to bypass script sanitization |

### Supported Data Types

- **Pandas DataFrames**
- **Polars DataFrames**
- **PySpark DataFrames** (auto-limited to prevent OOM)
- **Lists of dicts** — `[{"a": 1, "b": 2}, ...]`
- **Dicts of lists** — `{"a": [1, 2], "b": [3, 4]}`

## AWS Glue Support

`dbxplay` provides native, first-class support for **AWS Glue Notebooks** (AWS Glue Studio Notebooks & Interactive Sessions) as well as **AWS Glue ETL / Python Shell jobs**:

- **AWS Glue Notebooks**: Automatically renders interactive HTML tables encapsulated inside sandboxed `<iframe srcdoc="...">` tags to bypass Jupyter script sanitization. All interactive controls (sorting, filtering, searching, charting, theme toggling, context menus) work seamlessly.
- **AWS Glue ETL / Terminal Scripts**: Automatically detects non-notebook/CLI environments and outputs clean, formatted ASCII text tables to CloudWatch logs/stdout.

```python
# Force iframe encapsulation for Glue Notebooks (auto-enabled in Glue)
display(df, use_iframe=True)

# Force formatted ASCII text mode for CloudWatch logs / stdout
display(df, mode="text")
```

## Features

| Feature | Description |
| :--- | :--- |
| 🌙/☀️ **Theme Toggle** | Live Light / Dark theme toggle button in output toolbar (Dark theme uses orange highlights) |
| 🔍 **Global Search** | Instant full-text search across all columns & values |
| ↕️ **Column Sorting** | Click column headers to sort ascending/descending |
| 🔽 **Column Filtering** | Per-column value checkbox dropdowns |
| 📊 **Custom Visualization** | Customizable X/Y axes & aggregations (COUNT, SUM, AVG, MIN, MAX) |
| 📋 **Data Profile** | Overview stats & pop-out closeable distribution charts |
| 🎯 **Filter by Value** | Right-click any cell → "Filter by this value" |
| 🚫 **Exclude Value** | Right-click → "Exclude this value" |
| 📋 **Copy as CSV/TSV/Markdown** | Right-click → Copy as → choose format |
| 📥 **Download CSV / Excel** | Top `Table ∨` dropdown → Download |
| 📐 **Column Resizing** | Drag column borders to resize |
| 📄 **Side Panel** | Row detail view panel |
| 🔢 **Data Type Icons** | Automatic type badges (ABC, #, 1.2, T/F, 📅, {}) |
| 🧪 **AWS Glue Notebook Ready** | Automatic `iframe` `srcdoc` encapsulation for AWS Glue Studio |
| ✅ **Zero Dependencies** | Self-contained HTML/CSS/JS — works everywhere |

## Context Menu (Right-Click)

Right-click any cell to access:
- **Copy** (⌘C)
- **Copy as** → CSV, TSV, Markdown
- **Filter by this value**
- **Exclude this value**
- **Toggle side panel**

## License

MIT


