Metadata-Version: 2.5
Name: darsh
Version: 0.3.0
Summary: A magically simple, yet extremely powerful Python data application engine.
Author: Satyam Rana
License: MIT
Keywords: AI Practitioner,Dashboard,Data Analytics,Data Science,Interactive,Python,Satyam Rana,UI,Web Development
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.9
Requires-Dist: fastapi>=0.100.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: uvicorn>=0.23.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# ✨ Darsh

**Data analytics, without the ceremony.**

[![PyPI - Version](https://img.shields.io/pypi/v/darsh.svg)](https://pypi.org/project/darsh/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/darsh.svg)](https://pypi.org/project/darsh/)

---

> **Extremely simple on the surface. Extremely powerful underneath.**

You have data. You want a world-class, responsive dashboard. You probably don't want to spend your evening fighting with HTML, CSS, JavaScript, WebGL configuration, and 400 lines of boilerplate callbacks.

```python
import darsh as da

data = da.load("sales.csv").clean()
da.dashboard(data)

da.get_app().run(port=8501)
```

No HTML. No CSS. No JavaScript. Zero ceremony.

---

## ⚡ Installation

```bash
pip install darsh
```

👉 **Looking for recipes and guides? Check out [HOW_TO_USE.md](HOW_TO_USE.md)**

---

## 🧠 The Visual Analytics Mental Model

Just like in **Power BI**, different charts answer different business questions. The golden rule to remember:

> **Bar = Compare | Line = Trend | Pie = Share | Scatter = Relationship**

| Question | Visual Type | Core Purpose | Real-World Example |
| :--- | :--- | :--- | :--- |
| **Which is bigger?** | 📊 **Bar Chart** | Compare discrete categories | `Sales by Product` |
| **Is it changing?** | 📈 **Line Chart** | Track continuous trends over time | `Monthly Revenue Trajectory` |
| **What's my slice?** | 🥧 **Pie / Donut** | Parts of a whole (share %) | `Market Share by Category` |
| **Are they linked?** | 🔵 **Scatter Plot** | Discover correlation & clusters | `Advertising Spend vs Sales` |

---

## 🚀 Feature Highlights

- ⚡ **Zero-Boilerplate Web App**: Generates a high-performance, responsive web application directly from Python.
- 🌙 **Native Dark & Light Themes**: Deep space glassmorphic dark mode with interactive instant switcher (or `Cmd+D`).
- 📱 **Streamlit-Style Off-Canvas Sidebar**: Smooth collapsible drawer with mobile backdrop blur and keyboard shortcut (`Cmd+B`).
- 🔄 **Real-Time Cross-Filtering**: Dropdowns, sliders, and search inputs filter every chart on the canvas simultaneously.
- 🖱️ **Interactive Mouse Navigation**: Full mouse-pointer scroll zooming (`scrollZoom`), click-and-drag panning, and double-click zoom reset.
- 📋 **Interactive Data Tables**: Paginated, searchable tables (`da.table(df)`).
- 📈 **Matplotlib & Plotly Power**: Multi-line series, custom markers, line shapes (`spline` / `linear`), custom axes, and dimensions (`height` & `width`).
- 🌐 **3D WebGL Visualization**: Hardware-accelerated 3D scatter, line, and bar topology plots with rotational drag.

---

## 📖 Complete API Reference & Guide

### 1. Data Ingestion & Auto-Cleaning

```python
# Load local CSV or remote URL
data = da.load("sales.csv")

# Wrap existing DataFrame
data = da.data(df)

# Automatic cleanup (missing values, duplicates, datetimes)
clean_df = da.load("sales.csv").clean().pandas()
```

---

### 2. App Setup & Layout Utilities

#### `da.initialize(title="Dashboard", layout="wide", theme="light")`
- `layout`: `"centered"` (1350px width) or `"wide"` (100% full-screen canvas).
- `theme`: `"light"`, `"dark"`, or `"auto"`.

#### `da.page_header(title, subtitle=None, accent_color="#007AFF", badge="🟢 Live")`
Adds an Apple-styled top banner with title, subtitle, accent bar, and status badge.

#### `da.header(text)` & `da.subheader(text)`
Hierarchical section headings.

#### `da.row(children)`
Responsive horizontal flex grid.

#### `da.table(df, title="Explorer", page_size=8)`
Renders an interactive, paginated data table.

---

### 3. Reactive Sidebar & Cross-Filtering

```python
da.sidebar([
    da.sidebar_header("Global Filters"),
    da.select_filter("Region", column="Region", options=["North America", "Europe", "Asia"]),
    da.select_filter("Product", column="Product", options=["Hardware", "Software", "Services"]),
    da.sidebar_divider(),
    da.range_slider("Max Server Load", column="Server Load (%)", min_val=0, max_val=100, step=5),
    da.search_filter("Search Regions", column="Region", placeholder="Type region name..."),
    da.sidebar_divider(),
    da.sidebar_text("Press Cmd+B to toggle sidebar, Cmd+D for Dark Mode.")
], title="Command Center", width=280, collapsed=False)
```

---

### 4. KPI Metric Cards

```python
da.row([
    da.metric("Total Revenue", "$48,250,000", delta="+18.5%"),
    da.metric("Customer Churn", "1.2%", delta="-0.4%"),
    da.metric("Net Promoter Score", "74", delta="+6 pts", delta_color="#5856D6")
])
```

---

### 5. 2D Interactive Charts

#### 📈 Line Charts (Multi-Line & Markers)
```python
# Multi-line with list of Y columns
da.line_chart(
    df,
    x="Month",
    y=["Revenue", "Operating Cost", "Net Profit"],
    colors=["#007AFF", "#FF9500", "#34C759"],
    markers=True,
    marker_size=6,
    line_width=3.0,
    title="Financial Performance Trajectory",
    height=400
)

# Grouped multi-line by category
da.line_chart(
    df,
    x="Date",
    y="Active Users",
    color="Product",     # Automatically plots 1 line per Product!
    markers=True,
    title="Active Users by Product Line"
)
```

#### 📊 Bar Charts (Vertical, Horizontal, Stacked, Clustered)
```python
da.bar_chart(df, x="Region", y="Revenue", color="#007AFF", orientation="v")
da.stacked_bar_chart(df, x="Quarter", y=["Hardware", "Software"], colors=["#007AFF", "#34C759"])
```

#### 🥧 Pie & Donut Charts
```python
da.donut_chart(df, labels="Category", values="Sales", hole=0.45, colors=["#007AFF", "#5856D6", "#FF9500"])
```

#### 🔵 Scatter & Bubble Plots
```python
da.scatter_chart(df, x="AdSpend", y="Sales", color="Region", size="CSAT", marker_size=10)
```

---

### 6. 3D WebGL Charting Engine

```python
da.scatter_3d(df, x="Users", y="Load", z="CSAT", color="Product", title="3D System Telemetry")
da.line_3d(df, x="Date", y="Revenue", z="Users", color="#007AFF", title="Growth Trajectory 3D")
da.bar_3d(df, x="Region", y="Product", z="Revenue", colorscale="Blues", title="Revenue Matrix 3D")
```

---

### 7. Automatic Magic Dashboard

```python
data = da.load("sales.csv").clean()
da.dashboard(data)
da.get_app().run(port=8501)
```

---

## 👨‍💻 Creator & Maintainer

**Darsh** was created by **[Satyam Rana](https://www.satyamrana.in/)**, a Full-Stack Engineer, AI Practitioner, and Educator passionate about crafting high-performance developer tools and beautiful data systems.

---

## 📄 License

Darsh is open-source software licensed under the [MIT License](https://opensource.org/licenses/MIT).
