Metadata-Version: 2.4
Name: chabiao
Version: 0.4.1
Summary: Fast spreadsheet viewer, filter and processor - 查表，闪电般的表格查阅筛选工具
Author-email: EasyCam <easycam@github.com>
License-Expression: GPL-3.0-or-later
Keywords: chinese,excel,filter,spreadsheet,viewer,查表
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.0
Requires-Dist: tabulate>=0.9
Requires-Dist: xlrd>=2.0
Provides-Extra: all
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: jinja2>=3.1; extra == 'all'
Requires-Dist: pyqtgraph>=0.13; extra == 'all'
Requires-Dist: pyside6>=6.5; extra == 'all'
Requires-Dist: uvicorn>=0.23; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: gui
Requires-Dist: pyqtgraph>=0.13; extra == 'gui'
Requires-Dist: pyside6>=6.5; extra == 'gui'
Provides-Extra: web
Requires-Dist: fastapi>=0.100; extra == 'web'
Requires-Dist: jinja2>=3.1; extra == 'web'
Requires-Dist: uvicorn>=0.23; extra == 'web'
Description-Content-Type: text/markdown

# ChaBiao 查表 - Fast Spreadsheet Viewer, Filter & Processor

⚡ Lightning-fast spreadsheet viewer, filter and processor. Built for large Excel files (15MB+, 20K+ rows) that make Excel choke on filter dropdowns.

![ChaBiao GUI — Light Theme](images/gui_light_data.png)
![ChaBiao GUI — Dark Theme](images/gui_dark_zh.png)

## Features

- **Fast Filtering**: Instant column filtering - no more waiting for Excel's filter dropdowns
- **Keyword Search**: Full-text search across all columns with regex support
- **Spotlight / Focus Cell**: Highlight active row and column for easy reading (聚光灯功能)
![ChaBiao GUI — Spotlight](images/gui_light_spotlight.png)
- **Multi-Sheet Tabs**: Switch between sheets with tab widget (auto-hidden for single-sheet files)
- **Column Sorting**: Click column headers to sort ascending/descending
- **Cross-Reference**: Search in one table, extract columns to another (查表整合)
- **Data Charts**: Optional pyqtgraph chart visualization for numeric columns
- **Multi-format**: .xlsx, .xls, .csv, .tsv, .xlsm, .ods
- **Three Interfaces**: CLI, PySide6 GUI, and Web (FastAPI)
- **10 Languages**: 🇨🇳 中文 · 🇺🇸 English · 🇯🇵 日本語 · 🇫🇷 Français · 🇷🇺 Русский · 🇩🇪 Deutsch · 🇪🇸 Español · 🇧🇷 Português · 🇮🇹 Italiano · 🇰🇷 한국어
- **Dark Theme**: Catppuccin-inspired dark theme for GUI and Web
- **Pagination**: 500 rows/page for smooth scrolling on large files
- **Data Aggregation**: Pivot tables, group-by, subtotals
- **File Comparison**: Merge and compare two spreadsheet files
- **Export**: Convert between formats (xlsx, csv, json, tsv), web export with pagination
- **Agent Integration**: OpenAI function-calling tools for AI agents

## Requirements

- Python >= 3.10
- pandas >= 2.0
- openpyxl >= 3.1
- tabulate >= 0.9

Optional:
- PySide6 >= 6.5 (for GUI)
- pyqtgraph >= 0.13 (for charts, optional)
- FastAPI + uvicorn (for Web)

## Installation

```bash
# Basic (CLI only)
pip install chabiao

# With GUI support (includes pyqtgraph for charts)
pip install chabiao[gui]

# With Web support
pip install chabiao[web]

# Everything
pip install chabiao[all]

# Development
pip install chabiao[dev]
```

## Quick Start

### CLI

```bash
# Open and inspect a spreadsheet
chabiao open data.xlsx

# Filter by column with various conditions
chabiao filter data.xlsx --column City --contains Beijing
chabiao filter data.xlsx --column Price --gt 100 --lt 500
chabiao filter data.xlsx --column Sales --top-n 10

# Search for a keyword across columns
chabiao search data.xlsx --keyword error --columns Message,Level

# Aggregate data (like Excel pivot table)
chabiao aggregate data.xlsx --group-by City --agg Sales:sum --agg Price:mean

# Compare/merge two files
chabiao compare data1.xlsx data2.xlsx --on ID --how left

# Export to different format
chabiao export data.xlsx -o output.csv --format csv

# Spotlight on a specific row
chabiao spotlight data.xlsx --row 100 --column Price
```

### Python API

```python
from chabiao import open_file, filter_data, search_data, spotlight_view

# Open a spreadsheet
result = open_file(input_path="data.xlsx")
print(result.success)    # True
print(result.data)       # File info and metadata

# Filter data
result = filter_data(input_path="data.xlsx", column="City", contains="Beijing")
print(result.data["total_rows"])  # Number of matching rows

# Search across columns
result = search_data(input_path="data.xlsx", keyword="error", columns=["Message"])
print(result.data["total_matches"])

# Spotlight on a row
result = spotlight_view(input_path="data.xlsx", row=100, column="Price")
print(result.data["row_data"])       # Full row data
print(result.data["column_stats"])   # Column statistics
```

### GUI

```bash
# Launch GUI
chabiao-gui

# Open a file directly
chabiao-gui data.xlsx

# Open with dark theme and Chinese
chabiao-gui data.xlsx --theme dark --lang zh

# Custom page size
chabiao-gui data.xlsx --page-size 200
```

![ChaBiao GUI — Filter](images/gui_light_filter.png)
![ChaBiao GUI — Multi-Sheet](images/gui_light_multisheet.png)

Features:
- Open file from command line: `chabiao-gui data.xlsx`
- CLI options: `--lang zh --theme dark --page-size 200`
- Multi-language support (10 languages): View → Language
- Light/Dark theme switching: View → Theme
- Instant column filter (contains/equals/regex/search)
- Spotlight mode (F6) to highlight rows and columns
- Column sorting by clicking headers
- Multi-sheet tab switching
- Chart visualization (F7, requires pyqtgraph)
- Pagination for large files (500 rows/page)
- Copy selection to clipboard (Ctrl+C)
- Export to CSV/JSON/Excel

### Web Interface

```bash
chabiao-web
# or
python -m chabiao --web
```

Open http://localhost:8900 in your browser. Supports language (`?lang=zh`) and theme (`?theme=dark`) URL parameters. Web export supports pagination with `?start=0&limit=1000` for large datasets.

## Usage

### CLI Unified Flags

| Flag | Description |
|------|-------------|
| `-V, --version` | Show version |
| `-v, --verbose` | Verbose output |
| `-o, --output` | Output file path |
| `--json` | Output as JSON |
| `-q, --quiet` | Suppress non-essential output |

### CLI Commands

| Command | Description |
|---------|-------------|
| `open` | Open and inspect a spreadsheet |
| `filter` | Filter data by column conditions |
| `search` | Search keyword across columns |
| `aggregate` | Aggregate data by grouping |
| `compare` | Compare/merge two spreadsheet files |
| `export` | Export data to different format |
| `spotlight` | Focus on a specific row/cell |

### Filter Options

| Option | Description |
|--------|-------------|
| `--contains` | Text contains filter |
| `--regex` | Regex pattern filter |
| `--equals` | Exact match filter |
| `--not-equals` | Not equal filter |
| `--gt` / `--lt` | Greater than / Less than |
| `--ge` / `--le` | Greater/Less than or equal |
| `--top-n` | Top N values |
| `--bottom-n` | Bottom N values |
| `--above-avg` | Above average |
| `--below-avg` | Below average |

## Agent Integration (OpenAI Function Calling)

```python
from chabiao.tools import TOOLS, dispatch

# Use TOOLS in your OpenAI API call
response = client.chat.completions.create(
    model="gpt-4",
    messages=[...],
    tools=TOOLS,
)

# Dispatch tool calls
for tool_call in response.choices[0].message.tool_calls:
    result = dispatch(tool_call.function.name, tool_call.function.arguments)
    print(result)
```

Available tools:
- `chabiao_open_file` - Open and inspect spreadsheet
- `chabiao_filter_data` - Filter with various conditions
- `chabiao_search_data` - Search keywords across columns
- `chabiao_aggregate_data` - Group and aggregate data
- `chabiao_compare_data` - Compare/merge two files
- `chabiao_export_data` - Export to different format
- `chabiao_spotlight` - Focus on a specific row/cell

## Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
ruff format . && ruff check .

# Type check
mypy chabiao

# Build
python -m build
```

## License

GPL-3.0-or-later