viscsv 0.1.1

Render CSV files (including image path columns) into an interactive static HTML viewer.

viscsv

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

中文文档 / Chinese README

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

pip install viscsv

For local development with uv:

uv venv
uv pip install -e .

Quick Start

CLI

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

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.