Metadata-Version: 2.4
Name: flatapicli
Version: 0.1.0
Summary: Serve flat files (CSV, XLSX, JSON) as a local REST API instantly.
Author: Avinash Prajapati
License-Expression: MIT
Project-URL: Homepage, https://github.com/avinash/flatapicli
Project-URL: Issues, https://github.com/avinash/flatapicli/issues
Keywords: csv,xlsx,json,api,fastapi,local,prototyping
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.23.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: watchdog>=4.0.0
Dynamic: license-file

# ⚡ flatapicli

> Serve flat files (CSV, XLSX, JSON) as a local REST API instantly.

![Python](https://img.shields.io/badge/Python-3.10+-blue?logo=python&logoColor=white)
![FastAPI](https://img.shields.io/badge/FastAPI-0.138+-009688?logo=fastapi&logoColor=white)
![Pandas](https://img.shields.io/badge/Pandas-3.0+-150458?logo=pandas&logoColor=white)
![Uvicorn](https://img.shields.io/badge/Uvicorn-0.49+-4051b5)
![Typer](https://img.shields.io/badge/Typer-0.20+-grey)
![Watchdog](https://img.shields.io/badge/Watchdog-6.0+-orange)
![License](https://img.shields.io/badge/License-MIT-green)

---

## Install

```bash
pip install flatapicli
```

## Usage

```bash
# Start the server pointing at a directory
flatapicli serve --dir ./data

# Custom port
flatapicli serve --dir ./data --port 8080

# Expose to network (VPS / LAN)
flatapicli serve --dir ./data --host 0.0.0.0

# Auto-reload store on file change (no server restart)
flatapicli serve --dir ./data --watch

# Inspect files without starting server
flatapicli list-files --dir ./data
```

**While running:**
- `r` + Enter → reload data files without restarting server
- `q` + Enter → clean shutdown

## URL Structure

Given a directory with `products.csv`, `orders.xlsx` (sheets: `jan`, `feb`), and `users.json`:

| URL | Response |
|-----|----------|
| `GET /` | All loaded files |
| `GET /products/api` | Schema, columns, row count |
| `GET /products/api/rows` | All rows |
| `GET /products/api/rows?limit=10&offset=0` | Paginated rows |
| `GET /products/api/name` | All values in column `name` |
| `GET /orders/api` | Schema for all sheets |
| `GET /orders/api/jan/rows` | All rows in sheet `jan` |
| `GET /orders/api/jan/amount` | Column `amount` from sheet `jan` |
| `GET /orders/api/jan/amount/0` | Single cell: row 0, column `amount`, sheet `jan` |

## Supported Formats

| Format | Extension | Multi-sheet |
|--------|-----------|-------------|
| CSV | `.csv` | No |
| Excel | `.xlsx`, `.xls` | Yes |
| JSON | `.json` | Yes (object of arrays) |

### JSON format

Single sheet (array of objects):
```json
[{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
```

Multi-sheet (object of arrays):
```json
{
  "users": [{"id": 1, "name": "Alice"}],
  "admins": [{"id": 99, "name": "Root"}]
}
```

## Interactive Docs

Custom Swagger UI with chained dropdowns (File → Sheet → Column) available at `http://localhost:3000/docs`.

## Deployment (VPS)

```bash
pip install flatapicli
flatapicli serve --dir /data/files --host 0.0.0.0 --port 3000
```

Run behind nginx or use a systemd service for production stability.

## Contributing

TOON (Token-Oriented Object Notation) parser contributions welcome. Add a parser in `flatapicli/parsers/` following the existing pattern and register it in `flatapicli/parsers/__init__.py`.

## License

MIT
