flatapicli 0.1.0__py3-none-any.whl

flatapicli/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+__all__ = ["store", "server", "cli"]

flatapicli/cli.py

@@ -0,0 +1,170 @@
+import sys
+import threading
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(
+    name="flatapi",
+    help="Serve flat files (CSV, XLSX, JSON) as a local REST API.",
+    add_completion=False,
+)
+
+console = Console()
+
+
+def _keyboard_listener(dir_path: Path, stop_event: threading.Event):
+    """Runs in a background thread. Handles r=reload, q=quit."""
+    while not stop_event.is_set():
+        try:
+            cmd = input().strip().lower()
+        except EOFError:
+            break
+        if cmd == "r":
+            console.print("\n[cyan]🔄 Manual reload...[/cyan]")
+            from flatapi import store
+            loaded = store.load_directory(dir_path)
+            console.print(f"[green]✅ Reloaded: {', '.join(loaded)}[/green]\n")
+        elif cmd in ("q", "exit", "quit"):
+            console.print("\n[yellow]🛑 Shutting down...[/yellow]")
+            stop_event.set()
+            # Signal uvicorn to stop
+            import os, signal
+            os.kill(os.getpid(), signal.SIGINT)
+            break
+
+
+@app.command()
+def serve(
+    dir: Path = typer.Option(
+        ..., "--dir", "-d",
+        help="Directory containing your data files.",
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True,
+    ),
+    port: int = typer.Option(3000, "--port", "-p", help="Port to run the server on."),
+    host: str = typer.Option("127.0.0.1", "--host", "-h", help="Host to bind to. Use 0.0.0.0 for network/VPS access."),
+    watch: bool = typer.Option(False, "--watch", "-w", help="Auto-reload store when files change."),
+    reload: bool = typer.Option(False, "--reload", help="Enable uvicorn auto-reload (dev mode, restarts server)."),
+):
+    """
+    Start the flatapi server pointing at a directory of data files.
+
+    \b
+    While running:
+      r + Enter  → reload data files without restarting server
+      q + Enter  → clean shutdown
+
+    \b
+    Examples:
+      flatapi serve --dir ./data
+      flatapi serve --dir ./data --port 8080 --watch
+      flatapi serve --dir ./data --host 0.0.0.0
+    """
+    from flatapi import store
+
+    console.print(f"\n[bold cyan]flatapi[/bold cyan] scanning [green]{dir}[/green]...\n")
+    loaded = store.load_directory(dir)
+
+    if not loaded:
+        console.print("[bold red]No supported files found.[/bold red] (Supported: .csv, .xlsx, .xls, .json)")
+        raise typer.Exit(1)
+
+    # Print loaded files table
+    table = Table(title="Loaded Files", show_header=True, header_style="bold magenta")
+    table.add_column("File", style="cyan")
+    table.add_column("Sheets", style="green")
+    table.add_column("Endpoint")
+
+    for fname in loaded:
+        stem = Path(fname).stem.lower()
+        sheets = store.list_sheets(stem)
+        sheet_str = ", ".join(sheets) if sheets else "-"
+        table.add_row(fname, sheet_str, f"http://{host}:{port}/{stem}/api")
+
+    console.print(table)
+    console.print(f"\n[bold]Docs:[/bold]  http://{host}:{port}/docs")
+    console.print(f"[bold]Root:[/bold]  http://{host}:{port}/\n")
+    console.print("[dim]Commands: [r] reload  [q] quit[/dim]\n")
+
+    # Start file watcher if --watch
+    observer = None
+    if watch:
+        from flatapicli.watcher import start_watcher
+        observer = start_watcher(dir, on_reload=lambda files: console.print(f"[green]✅ Reloaded: {', '.join(files)}[/green]"))
+        console.print(f"[cyan]👁  Watching {dir} for changes...[/cyan]\n")
+
+    # Start keyboard listener thread
+    stop_event = threading.Event()
+    kb_thread = threading.Thread(
+        target=_keyboard_listener,
+        args=(dir, stop_event),
+        daemon=True,
+    )
+    kb_thread.start()
+
+    # Start uvicorn
+    import uvicorn
+    try:
+        uvicorn.run(
+            "flatapi.server:app",
+            host=host,
+            port=port,
+            reload=reload,
+            log_level="info",
+        )
+    finally:
+        stop_event.set()
+        if observer:
+            observer.stop()
+            observer.join()
+        console.print("[green]✅ flatapi stopped.[/green]")
+
+
+@app.command(name="list-files")
+def list_files(
+    dir: Path = typer.Option(
+        ..., "--dir", "-d",
+        help="Directory to inspect.",
+        exists=True, file_okay=False, dir_okay=True, resolve_path=True,
+    ),
+):
+    """List all supported files in a directory without starting the server."""
+    from flatapi import store
+
+    console.print(f"\nScanning [green]{dir}[/green]...\n")
+    loaded = store.load_directory(dir)
+
+    if not loaded:
+        console.print("[yellow]No supported files found.[/yellow]")
+        raise typer.Exit()
+
+    table = Table(show_header=True, header_style="bold magenta")
+    table.add_column("File")
+    table.add_column("Sheet")
+    table.add_column("Columns")
+    table.add_column("Rows")
+
+    for fname in loaded:
+        stem = Path(fname).stem.lower()
+        sheets = store.list_sheets(stem)
+        for i, sheet in enumerate(sheets):
+            df = store.get_sheet(stem, sheet)
+            table.add_row(
+                fname if i == 0 else "",
+                sheet,
+                str(len(df.columns)),
+                str(len(df)),
+            )
+
+    console.print(table)
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

flatapicli/parsers/__init__.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+import pandas as pd
+
+from .csv_parser import load as load_csv
+from .xlsx_parser import load as load_xlsx
+from .json_parser import load as load_json
+
+SUPPORTED_EXTENSIONS = {".csv", ".xlsx", ".xls", ".json"}
+
+_LOADERS = {
+    ".csv": load_csv,
+    ".xlsx": load_xlsx,
+    ".xls": load_xlsx,
+    ".json": load_json,
+}
+
+
+def load_file(path: Path) -> dict[str, pd.DataFrame]:
+    """
+    Returns a dict of {sheet_name: DataFrame}.
+    Single-sheet formats use 'default' as the sheet name.
+    """
+    ext = path.suffix.lower()
+    loader = _LOADERS.get(ext)
+    if loader is None:
+        raise ValueError(
+            f"Unsupported file type '{ext}'. "
+            f"Supported: {', '.join(SUPPORTED_EXTENSIONS)}"
+        )
+    return loader(path)

flatapicli/parsers/csv_parser.py

@@ -0,0 +1,8 @@
+import pandas as pd
+from pathlib import Path
+
+
+def load(path: Path) -> dict[str, pd.DataFrame]:
+    """Returns {'default': DataFrame}"""
+    df = pd.read_csv(path)
+    return {"default": df}

flatapicli/parsers/json_parser.py

@@ -0,0 +1,25 @@
+import json
+import pandas as pd
+from pathlib import Path
+
+
+def load(path: Path) -> dict[str, pd.DataFrame]:
+    """
+    Supports:
+      - Array of objects: [{...}, {...}]  → single 'default' sheet
+      - Object of arrays: {"sheet1": [{...}], "sheet2": [{...}]}  → multi-sheet
+    """
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    if isinstance(data, list):
+        return {"default": pd.DataFrame(data)}
+
+    if isinstance(data, dict):
+        # Check if values are lists of objects → treat as named sheets
+        if all(isinstance(v, list) for v in data.values()):
+            return {k: pd.DataFrame(v) for k, v in data.items()}
+        # Single flat object → wrap as one-row DataFrame
+        return {"default": pd.DataFrame([data])}
+
+    raise ValueError(f"Unsupported JSON structure in {path.name}")

flatapicli/parsers/xlsx_parser.py

@@ -0,0 +1,8 @@
+import pandas as pd
+from pathlib import Path
+
+
+def load(path: Path) -> dict[str, pd.DataFrame]:
+    """Returns {sheet_name: DataFrame} for every sheet in the workbook."""
+    xl = pd.ExcelFile(path, engine="openpyxl")
+    return {sheet: xl.parse(sheet) for sheet in xl.sheet_names}

flatapicli/server.py

@@ -0,0 +1,454 @@
+"""
+Route structure:
+  GET /                                        → list all loaded files
+  GET /meta                                    → full schema for Swagger UI dropdowns
+  GET /meta/{filename}                         → sheets + columns for a file
+  GET /meta/{filename}/{sheet}                 → columns for a sheet
+  GET /{filename}/api                          → file health + schema
+  GET /{filename}/api/rows                     → all rows (default sheet)
+  GET /{filename}/api/{column}                 → column values (default sheet)
+  GET /{filename}/api/{sheet}/rows             → all rows in named sheet
+  GET /{filename}/api/{sheet}/{column}         → column values from named sheet
+  GET /{filename}/api/{sheet}/{column}/{row_id}→ single cell
+"""
+import math
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import JSONResponse, HTMLResponse
+from fastapi.middleware.cors import CORSMiddleware
+
+from . import store
+
+app = FastAPI(
+    title="flatapi",
+    description="Serve flat files (CSV, XLSX, JSON) as a local REST API.",
+    version="0.1.0",
+    docs_url=None,   # We override /docs with custom Swagger UI
+    redoc_url="/redoc",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _sanitize(obj):
+    import numpy as np
+    if isinstance(obj, np.integer): return int(obj)
+    if isinstance(obj, np.floating): return None if (np.isnan(obj) or np.isinf(obj)) else float(obj)
+    if isinstance(obj, np.bool_): return bool(obj)
+    if isinstance(obj, float) and (obj != obj): return None
+    return obj
+
+
+def _df_to_records(df) -> list[dict]:
+    records = df.to_dict(orient="records")
+    return [{k: _sanitize(v) for k, v in row.items()} for row in records]
+
+
+def _build_endpoint_hints(filename: str, sheets: list, schema: dict) -> list[str]:
+    hints = []
+    for sheet in sheets:
+        prefix = (
+            f"/{filename}/api"
+            if sheet == "default"
+            else f"/{filename}/api/{sheet}"
+        )
+        hints.append(f"GET {prefix}/rows")
+        for col in schema[sheet]["columns"]:
+            hints.append(f"GET {prefix}/{col}")
+    return hints
+
+
+# ── Meta endpoints (for Swagger UI dynamic dropdowns) ─────────────────────────
+
+@app.get("/meta", tags=["meta"])
+def get_meta():
+    """Returns full schema of all loaded files. Used by Swagger UI dropdowns."""
+    result = {}
+    for filename in store.list_files():
+        sheets = store.list_sheets(filename)
+        result[filename] = {}
+        for sheet in sheets:
+            df = store.get_sheet(filename, sheet)
+            result[filename][sheet] = list(df.columns)
+    return result
+
+
+@app.get("/meta/{filename}", tags=["meta"])
+def get_file_meta(filename: str):
+    sheets = store.list_sheets(filename)
+    if sheets is None:
+        raise HTTPException(status_code=404, detail=f"File '{filename}' not found.")
+    result = {}
+    for sheet in sheets:
+        df = store.get_sheet(filename, sheet)
+        result[sheet] = list(df.columns)
+    return result
+
+
+@app.get("/meta/{filename}/{sheet}", tags=["meta"])
+def get_sheet_meta(filename: str, sheet: str):
+    df = store.get_sheet(filename, sheet)
+    if df is None:
+        raise HTTPException(status_code=404, detail=f"Sheet '{sheet}' not found in '{filename}'.")
+    return {"columns": list(df.columns)}
+
+
+# ── Custom Swagger UI with chained dropdowns ───────────────────────────────────
+
+@app.get("/docs", include_in_schema=False)
+async def custom_swagger():
+    html = """
+<!DOCTYPE html>
+<html>
+<head>
+  <title>flatapi - Swagger UI</title>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui.css">
+  <style>
+    body { margin: 0; }
+    .flatapi-bar {
+      background: #1b1b1b;
+      color: #fff;
+      padding: 10px 20px;
+      font-family: monospace;
+      font-size: 14px;
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      flex-wrap: wrap;
+    }
+    .flatapi-bar label { color: #aaa; font-size: 12px; }
+    .flatapi-bar select {
+      background: #2d2d2d;
+      color: #fff;
+      border: 1px solid #444;
+      padding: 4px 8px;
+      border-radius: 4px;
+      font-size: 13px;
+      cursor: pointer;
+    }
+    .flatapi-bar select:disabled { opacity: 0.4; cursor: not-allowed; }
+    .flatapi-bar .url-preview {
+      margin-left: auto;
+      color: #4CAF50;
+      font-size: 13px;
+      word-break: break-all;
+    }
+    .flatapi-bar button {
+      background: #4CAF50;
+      color: #fff;
+      border: none;
+      padding: 5px 14px;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 13px;
+    }
+    .flatapi-bar button:hover { background: #45a049; }
+    #swagger-ui { padding-top: 4px; }
+  </style>
+</head>
+<body>
+
+<div class="flatapi-bar">
+  <span style="color:#4CAF50;font-weight:bold;">⚡ flatapi</span>
+
+  <div>
+    <label>File</label><br>
+    <select id="sel-file" onchange="onFileChange()">
+      <option value="">— select file —</option>
+    </select>
+  </div>
+
+  <div>
+    <label>Sheet</label><br>
+    <select id="sel-sheet" onchange="onSheetChange()" disabled>
+      <option value="">— select sheet —</option>
+    </select>
+  </div>
+
+  <div>
+    <label>Column</label><br>
+    <select id="sel-col" onchange="onColChange()" disabled>
+      <option value="">— select column —</option>
+    </select>
+  </div>
+
+  <div>
+    <label>Row ID (optional)</label><br>
+    <input id="inp-row" type="number" min="0" placeholder="e.g. 0"
+      style="background:#2d2d2d;color:#fff;border:1px solid #444;padding:4px 8px;border-radius:4px;font-size:13px;width:80px;"
+      oninput="buildUrl()">
+  </div>
+
+  <button onclick="openUrl()">Open ↗</button>
+
+  <div class="url-preview" id="url-preview"></div>
+</div>
+
+<div id="swagger-ui"></div>
+
+<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui-bundle.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.0/swagger-ui-standalone-preset.js"></script>
+<script>
+  let meta = {};
+
+  // Init Swagger UI
+  SwaggerUIBundle({
+    url: "/openapi.json",
+    dom_id: '#swagger-ui',
+    presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+    layout: "StandaloneLayout",
+    deepLinking: true,
+  });
+
+  // Load meta and populate file dropdown
+  async function loadMeta() {
+    const res = await fetch('/meta');
+    meta = await res.json();
+    const sel = document.getElementById('sel-file');
+    sel.innerHTML = '<option value="">— select file —</option>';
+    for (const fname of Object.keys(meta)) {
+      const opt = document.createElement('option');
+      opt.value = fname;
+      opt.textContent = fname;
+      sel.appendChild(opt);
+    }
+  }
+
+  function onFileChange() {
+    const file = document.getElementById('sel-file').value;
+    const selSheet = document.getElementById('sel-sheet');
+    const selCol = document.getElementById('sel-col');
+
+    selSheet.innerHTML = '<option value="">— select sheet —</option>';
+    selCol.innerHTML = '<option value="">— select column —</option>';
+    selCol.disabled = true;
+
+    if (!file) { selSheet.disabled = true; buildUrl(); return; }
+
+    const sheets = Object.keys(meta[file] || {});
+    selSheet.disabled = false;
+
+    if (sheets.length === 1 && sheets[0] === 'default') {
+      // Single sheet — skip sheet selector, populate columns directly
+      selSheet.innerHTML = '<option value="default">default</option>';
+      selSheet.disabled = true;
+      populateColumns(file, 'default');
+    } else {
+      for (const s of sheets) {
+        const opt = document.createElement('option');
+        opt.value = s; opt.textContent = s;
+        selSheet.appendChild(opt);
+      }
+    }
+    buildUrl();
+  }
+
+  function onSheetChange() {
+    const file = document.getElementById('sel-file').value;
+    const sheet = document.getElementById('sel-sheet').value;
+    if (file && sheet) populateColumns(file, sheet);
+    buildUrl();
+  }
+
+  function populateColumns(file, sheet) {
+    const cols = meta[file]?.[sheet] || [];
+    const selCol = document.getElementById('sel-col');
+    selCol.innerHTML = '<option value="">— all rows —</option>';
+    for (const c of cols) {
+      const opt = document.createElement('option');
+      opt.value = c; opt.textContent = c;
+      selCol.appendChild(opt);
+    }
+    selCol.disabled = false;
+    buildUrl();
+  }
+
+  function onColChange() { buildUrl(); }
+
+  function buildUrl() {
+    const file  = document.getElementById('sel-file').value;
+    const sheet = document.getElementById('sel-sheet').value;
+    const col   = document.getElementById('sel-col').value;
+    const row   = document.getElementById('inp-row').value;
+
+    if (!file) { document.getElementById('url-preview').textContent = ''; return; }
+
+    const isDefault = !sheet || sheet === 'default';
+    let url = `/${file}/api`;
+
+    if (!isDefault) url += `/${sheet}`;
+
+    if (col) {
+      url += `/${col}`;
+      if (row !== '') url += `/${row}`;
+    } else {
+      url += '/rows';
+    }
+
+    document.getElementById('url-preview').textContent = url;
+    return url;
+  }
+
+  function openUrl() {
+    const url = buildUrl();
+    if (url) window.open(url, '_blank');
+  }
+
+  loadMeta();
+</script>
+</body>
+</html>
+"""
+    return HTMLResponse(html)
+
+
+# ── Root ──────────────────────────────────────────────────────────────────────
+
+@app.get("/", tags=["root"])
+def root():
+    files = store.list_files()
+    return {
+        "status": "running",
+        "loaded_files": files,
+        "count": len(files),
+        "hint": "Access a file at /{filename}/api  |  Explorer: /docs",
+    }
+
+
+# ── File-level ────────────────────────────────────────────────────────────────
+
+@app.get("/{filename}/api", tags=["data"])
+def file_info(filename: str):
+    sheets = store.list_sheets(filename)
+    if sheets is None:
+        raise HTTPException(status_code=404, detail=f"File '{filename}' not found.")
+
+    schema = {}
+    for sheet_name in sheets:
+        df = store.get_sheet(filename, sheet_name)
+        schema[sheet_name] = {
+            "columns": list(df.columns),
+            "row_count": len(df),
+            "dtypes": {col: str(dtype) for col, dtype in df.dtypes.items()},
+        }
+
+    is_multi = len(sheets) > 1 or sheets[0] != "default"
+    return {
+        "status": "ok",
+        "file": filename,
+        "sheets": sheets,
+        "multi_sheet": is_multi,
+        "schema": schema,
+        "endpoints": _build_endpoint_hints(filename, sheets, schema),
+    }
+
+
+# ── Default-sheet routes ───────────────────────────────────────────────────────
+
+@app.get("/{filename}/api/rows", tags=["data"])
+def get_all_rows(
+    filename: str,
+    limit: Optional[int] = Query(None, ge=1),
+    offset: int = Query(0, ge=0),
+):
+    df = store.get_sheet(filename, "default")
+    if df is None:
+        sheets = store.list_sheets(filename)
+        if sheets:
+            raise HTTPException(
+                status_code=400,
+                detail=f"'{filename}' has multiple sheets: {sheets}. Use /{filename}/api/{{sheetname}}/rows",
+            )
+        raise HTTPException(status_code=404, detail=f"File '{filename}' not found.")
+
+    sliced = df.iloc[offset: offset + limit] if limit else df.iloc[offset:]
+    return {
+        "file": filename, "sheet": "default",
+        "total": len(df), "offset": offset, "limit": limit,
+        "rows": _df_to_records(sliced),
+    }
+
+
+@app.get("/{filename}/api/{column_or_sheet}", tags=["data"])
+def get_column_or_sheet_info(filename: str, column_or_sheet: str):
+    df = store.get_sheet(filename, "default")
+    if df is not None and column_or_sheet in df.columns:
+        return {
+            "file": filename, "sheet": "default",
+            "column": column_or_sheet,
+            "values": [_sanitize(v) for v in df[column_or_sheet].tolist()],
+        }
+
+    sheet_df = store.get_sheet(filename, column_or_sheet)
+    if sheet_df is not None:
+        return {
+            "file": filename, "sheet": column_or_sheet,
+            "columns": list(sheet_df.columns),
+            "row_count": len(sheet_df),
+            "hint": f"Use /{filename}/api/{column_or_sheet}/rows for all rows",
+        }
+
+    sheets = store.list_sheets(filename)
+    if sheets is None:
+        raise HTTPException(status_code=404, detail=f"File '{filename}' not found.")
+    raise HTTPException(
+        status_code=404,
+        detail=f"'{column_or_sheet}' is not a column or sheet in '{filename}'.",
+    )
+
+
+# ── Named-sheet routes ────────────────────────────────────────────────────────
+
+@app.get("/{filename}/api/{sheet}/rows", tags=["data"])
+def get_sheet_rows(
+    filename: str, sheet: str,
+    limit: Optional[int] = Query(None, ge=1),
+    offset: int = Query(0, ge=0),
+):
+    df = store.get_sheet(filename, sheet)
+    if df is None:
+        raise HTTPException(status_code=404, detail=f"Sheet '{sheet}' not found in '{filename}'.")
+    sliced = df.iloc[offset: offset + limit] if limit else df.iloc[offset:]
+    return {
+        "file": filename, "sheet": sheet,
+        "total": len(df), "offset": offset, "limit": limit,
+        "rows": _df_to_records(sliced),
+    }
+
+
+@app.get("/{filename}/api/{sheet}/{column}", tags=["data"])
+def get_sheet_column(filename: str, sheet: str, column: str):
+    df = store.get_sheet(filename, sheet)
+    if df is None:
+        raise HTTPException(status_code=404, detail=f"Sheet '{sheet}' not found in '{filename}'.")
+    if column not in df.columns:
+        raise HTTPException(status_code=404, detail=f"Column '{column}' not found. Available: {list(df.columns)}")
+    return {
+        "file": filename, "sheet": sheet, "column": column,
+        "values": [_sanitize(v) for v in df[column].tolist()],
+    }
+
+
+@app.get("/{filename}/api/{sheet}/{column}/{row_id}", tags=["data"])
+def get_cell(filename: str, sheet: str, column: str, row_id: int):
+    df = store.get_sheet(filename, sheet)
+    if df is None:
+        raise HTTPException(status_code=404, detail=f"Sheet '{sheet}' not found in '{filename}'.")
+    if column not in df.columns:
+        raise HTTPException(status_code=404, detail=f"Column '{column}' not found. Available: {list(df.columns)}")
+    if not (0 <= row_id < len(df)):
+        raise HTTPException(status_code=404, detail=f"Row {row_id} out of range. File has {len(df)} rows (0-indexed).")
+    return {
+        "file": filename, "sheet": sheet, "column": column,
+        "row_id": row_id, "value": _sanitize(df.iloc[row_id][column]),
+    }

flatapicli/store.py

@@ -0,0 +1,74 @@
+"""
+In-memory store with thread-safe read/write via RLock.
+Structure: _store[filename_stem][sheet_name] = pd.DataFrame
+"""
+from pathlib import Path
+from typing import Dict
+import threading
+import pandas as pd
+
+from .parsers import load_file, SUPPORTED_EXTENSIONS
+
+_store: Dict[str, Dict[str, pd.DataFrame]] = {}
+_lock = threading.RLock()
+_watch_dir: Path | None = None
+
+
+def load_directory(dir_path: Path) -> list[str]:
+    global _store, _watch_dir
+    _watch_dir = dir_path
+    new_store = {}
+    loaded = []
+
+    for file in sorted(dir_path.iterdir()):
+        if file.suffix.lower() not in SUPPORTED_EXTENSIONS:
+            continue
+        try:
+            sheets = load_file(file)
+            new_store[file.stem.lower()] = sheets
+            loaded.append(file.name)
+        except Exception as e:
+            print(f"  ⚠  Skipped '{file.name}': {e}")
+
+    with _lock:
+        _store = new_store
+
+    return loaded
+
+
+def get_store() -> Dict[str, Dict[str, pd.DataFrame]]:
+    with _lock:
+        return dict(_store)
+
+
+def get_file(filename: str) -> Dict[str, pd.DataFrame] | None:
+    with _lock:
+        return _store.get(filename.lower())
+
+
+def get_sheet(filename: str, sheet: str) -> pd.DataFrame | None:
+    with _lock:
+        file_data = _store.get(filename.lower())
+        if file_data is None:
+            return None
+        result = file_data.get(sheet.lower())
+        if result is None:
+            result = file_data.get(sheet)
+        return result
+
+
+def list_files() -> list[str]:
+    with _lock:
+        return list(_store.keys())
+
+
+def list_sheets(filename: str) -> list[str] | None:
+    with _lock:
+        file_data = _store.get(filename.lower())
+        if file_data is None:
+            return None
+        return list(file_data.keys())
+
+
+def get_watch_dir() -> Path | None:
+    return _watch_dir

flatapicli/watcher.py

@@ -0,0 +1,59 @@
+"""
+Background file watcher using watchdog.
+Reloads the store when any supported file in the watched directory changes.
+"""
+import threading
+import time
+from pathlib import Path
+
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler
+
+from . import store
+from .parsers import SUPPORTED_EXTENSIONS
+
+
+class _ReloadHandler(FileSystemEventHandler):
+    def __init__(self, dir_path: Path, on_reload=None):
+        self._dir = dir_path
+        self._on_reload = on_reload
+        self._debounce_timer: threading.Timer | None = None
+        self._lock = threading.Lock()
+
+    def _debounced_reload(self):
+        """Debounce: wait 500ms after last event before reloading."""
+        with self._lock:
+            if self._debounce_timer:
+                self._debounce_timer.cancel()
+            self._debounce_timer = threading.Timer(0.5, self._do_reload)
+            self._debounce_timer.start()
+
+    def _do_reload(self):
+        print("\n🔄 File change detected — reloading store...")
+        loaded = store.load_directory(self._dir)
+        print(f"✅ Reloaded: {', '.join(loaded)}")
+        if self._on_reload:
+            self._on_reload(loaded)
+
+    def on_modified(self, event):
+        if not event.is_directory:
+            if Path(event.src_path).suffix.lower() in SUPPORTED_EXTENSIONS:
+                self._debounced_reload()
+
+    def on_created(self, event):
+        if not event.is_directory:
+            if Path(event.src_path).suffix.lower() in SUPPORTED_EXTENSIONS:
+                self._debounced_reload()
+
+    def on_deleted(self, event):
+        if not event.is_directory:
+            if Path(event.src_path).suffix.lower() in SUPPORTED_EXTENSIONS:
+                self._debounced_reload()
+
+
+def start_watcher(dir_path: Path, on_reload=None) -> Observer:
+    handler = _ReloadHandler(dir_path, on_reload=on_reload)
+    observer = Observer()
+    observer.schedule(handler, str(dir_path), recursive=False)
+    observer.start()
+    return observer

flatapicli-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+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

flatapicli-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+flatapicli/__init__.py,sha256=qunU3WBgb0U6h8BTQIpSBaZKItCt3KcWYJZsiIdTRWI,59
+flatapicli/cli.py,sha256=avfVJU-0yHpyKLJ6WKmyMyUCriQRAkvHWtNhYR9DXM4,5299
+flatapicli/server.py,sha256=4QeDG70abzUHSlPU5tUG4HlEejk2V5DMWiyy19C8Ebc,15454
+flatapicli/store.py,sha256=VBmd-oORHkmpATk5FL3-JPYOcAJeR9rSC_v9EQzSaLQ,1827
+flatapicli/watcher.py,sha256=oJ-yx1N3Is7UJR_kaV6fFteoKbumm-JWE6gXxwxWhzY,2057
+flatapicli/parsers/__init__.py,sha256=wUkspYTJoKuSTPdaX5UPAJhGaKDg3r8uOlV2go9DVvY,769
+flatapicli/parsers/csv_parser.py,sha256=Ys4j7xvXbOjX5JmOJTJ4Y014bOmnQEROetZ1U3JZ2gs,191
+flatapicli/parsers/json_parser.py,sha256=u2QVRFFmCq8DbVvvZzQZVmEtBpaf-3B57eHLK9yI2nA,851
+flatapicli/parsers/xlsx_parser.py,sha256=gzNiTeCoMBg7bi5UG3WBbFmBUXaK9L8J-3jLYHVYCs4,282
+flatapicli-0.1.0.dist-info/licenses/LICENSE,sha256=1TES4q8_6NDkOQNpl28FQ5pBQXlN1eRloOH9_VWuXIA,1074
+flatapicli-0.1.0.dist-info/METADATA,sha256=5TuesWvm1246QiaDapFAyxv9b35EuG0lf-lEDe2EqLY,3810
+flatapicli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+flatapicli-0.1.0.dist-info/entry_points.txt,sha256=2kDUO23tAQqtlZSWUCBeswSHrVEzJiHzl_W2XMJMdIA,47
+flatapicli-0.1.0.dist-info/top_level.txt,sha256=QY_EmQoo9QgoUYDhSd25MOfYV3IgvJUlOqxU8LXBqv4,11
+flatapicli-0.1.0.dist-info/RECORD,,

flatapicli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flatapicli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flatapi = flatapicli.cli:app

flatapicli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Avinash Prajapati
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flatapicli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flatapicli