Metadata-Version: 2.4
Name: wherewolf
Version: 0.5.1
Summary: A production-grade, local SQL workbench for querying files (CSV, Parquet, JSON) using DuckDB or Spark.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: duckdb>=1.5.0
Requires-Dist: fastexcel>=0.20.2
Requires-Dist: ibis-framework>=12.0.0
Requires-Dist: polars>=1.40.1
Requires-Dist: psutil>=7.2.2
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: pyspark>=4.1.1
Requires-Dist: sqlglot>=29.0.1
Requires-Dist: streamlit-ace>=0.1.1
Requires-Dist: streamlit>=1.55.0
Requires-Dist: xlsxwriter>=3.2.9
Description-Content-Type: text/markdown

# Wherewolf

<img src="https://raw.githubusercontent.com/beallio/wherewolf/main/src/wherewolf/assets/img/wherewolf_banner.png?cacheBuster=10" width="100%">

[![CI](https://github.com/beallio/wherewolf/actions/workflows/ci.yml/badge.svg?cacheBuster=10)](https://github.com/beallio/wherewolf/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/wherewolf.svg?cacheBuster=10)](https://pypi.org/project/wherewolf/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?cacheBuster=10)](https://opensource.org/licenses/MIT)

A production-grade, local SQL workbench for querying files (CSV, Parquet, JSON) using DuckDB or Spark.

## Features
- **Multi-Engine Support:** Execute SQL via DuckDB (local) or Spark (local[*]). Native support for CSV, Parquet, JSON, and Excel (`.xlsx`, `.xls`).
- **📁 Dataset Catalog:** Improved file browser with directory-first sorting, folder icons, and extension filtering for a cleaner experience.
- **🔗 Multi-Table Queries:** Perform JOINs, unions, and subqueries across different file formats in a single session.
- **📊 Schema & Metadata HUD:** Instant visibility of column names and data types for any dataset in your catalog.
- **SQL Translation:** Real-time translation between DuckDB and SparkSQL dialects using SQLGlot.
- **Modern UI:** Distraction-free interface with a hidden toolbar, reduced whitespace, and clear visual hierarchy.
- **Safe Preview:** Scrollable results limited to 1000 rows.
- **Query History:** Persists past queries in `~/.wherewolf/history.json`.
- **Export:** Download query results as CSV, Excel, or Parquet. DataFrame handling and exports are Polars-based. When the preview is truncated, use **Prepare full export** to re-run the query without a row limit and download the entire result set.
- **Execution Metrics:** Tracks row count and execution time.

![Wherewolf Screenshot](https://raw.githubusercontent.com/beallio/wherewolf/main/src/wherewolf/assets/img/screenshot.png?cacheBuster=10)

## Installation

Ensure you have [uv](https://github.com/astral-sh/uv) installed.

### From PyPI (Recommended)
```bash
uv tool install wherewolf
wherewolf
```

### From Source
```bash
git clone https://github.com/beallio/wherewolf.git
cd wherewolf
uv sync
```

## Usage

If running from source:
```bash
uv run streamlit run src/wherewolf/app.py
```

1. Use the **Manage Dataset Catalog** section in the sidebar to browse and add files.
2. Each file is assigned an alias (e.g., `users`, `orders`).
3. Write your SQL query using these aliases in the editor.
4. Click **Run** to execute.
5. View results, execution metrics, or switch the **Metadata Focus** to inspect other schemas.
6. Export or view the translated SQL if needed.

## Development

Run tests:
```bash
uv run pytest
```

Lint/Format:
```bash
ruff check . --fix
ruff format .
```

## Dependencies
- `streamlit`
- `duckdb`
- `pyspark`
- `ibis-framework`
- `sqlglot`
- `pyarrow`
- `polars`
- `fastexcel`
- `xlsxwriter`
