Metadata-Version: 2.4
Name: viscsv
Version: 0.1.1
Summary: Render CSV files (including image path columns) into an interactive static HTML viewer.
Author: viscsv authors
License-Expression: MIT
Keywords: csv,visualization,html,images,viewer
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Environment :: Web Environment
Classifier: Topic :: Multimedia :: Graphics :: Viewers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: twine>=6.2.0
Provides-Extra: dev
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Dynamic: license-file

# viscsv

Interactive CSV viewer for fast table preview, with first-class support for image path columns.

[中文文档 / Chinese README](README.zh-CN.md)

## Why viscsv

- Simple: one command generates a standalone HTML file.
- Practical: works with plain CSV plus local/remote image paths.
- Fast for preview: pagination and client-side interactions out of the box.
- Deploy-free: output is static HTML (and optional sidecar JSON for large datasets).

## Features

- Python API and CLI.
- Auto-detect image columns or set them explicitly.
- Search, sorting, grouping, table/grid switch.
- Sticky table header in data-scroll area.
- Local image support via relative path + `--image-root`.
- Cross-platform path normalization for Linux/macOS/Windows-style inputs.

## Installation

```bash
pip install viscsv
```

For local development with `uv`:

```bash
uv venv
uv pip install -e .
```

## Quick Start

### CLI

```bash
viscsv render data/example.csv -o output/preview.html --image-root images
```

Common options:

- `--image-root PATH`: resolve relative image paths.
- `--image-column NAME`: specify image column(s), repeatable.
- `--page-size N`: client page size.
- `--title TEXT`: viewer title.

### Python API

```python
from viscsv import render_csv

render_csv(
    csv_path="data/example.csv",
    output_html="output/preview.html",
    image_root="images",               # optional
    image_columns=["image_url"],       # optional
    page_size=200,
    title="Dataset Preview",
)
```

## Local Image Paths

Two recommended patterns:

1. CSV uses relative paths + `--image-root`.
2. CSV uses absolute paths directly.

Examples:

- Relative path value: `photos/cat01.jpg`
- Windows-style relative value: `photos\\cat01.jpg`
- Absolute path value: `/Users/alice/Pictures/cat01.jpg`
- Windows absolute value: `C:\\Users\\Alice\\Pictures\\cat01.jpg`

## Large Data Notes

`viscsv` is optimized for preview workflows. For very large CSV files, prefer:

- More selective columns.
- Reasonable `--page-size` (for example `100-500`).
- Sidecar JSON mode for huge row counts.


## License

MIT. See [LICENSE](LICENSE).
