viscsv 0.1.0__tar.gz

viscsv-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: viscsv
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pillow>=12.1.0
+
+# VisCSV
+
+![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)
+![Pandas](https://img.shields.io/badge/Pandas-2.x-150458?logo=pandas&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-000000?logo=opensourceinitiative&logoColor=white)
+
+VisCSV turns CSV data (with image paths) into a clean, interactive HTML table.  
+Simple API, fast preview, no server required.
+
+## Highlights
+
+- Image columns support (local paths or URLs)
+- Smart type inference (number, datetime, boolean, json, code)
+- Drag to reorder columns
+- Resize column widths
+- Built-in horizontal/vertical scrolling
+- Chunked loading for large datasets
+
+## Quickstart
+
+```python
+from viscsv import preview
+
+preview("data.csv", output="output")
+```
+
+Open `output/viewer.html` in your browser.
+
+## With Image Columns
+
+```python
+from viscsv import preview
+
+preview("data.csv", image="image_path", output="output")
+```
+
+## Use the Class API
+
+```python
+from viscsv import VisCSV
+
+vc = VisCSV(image="image")
+vc.add("imgs/1.jpg", label="cat", score=0.98)
+vc.add([
+    {"image": "imgs/2.jpg", "label": "dog", "score": 0.87},
+    {"image": "imgs/3.jpg", "label": "fox", "score": 0.72},
+])
+vc.build(output="output")
+```
+
+## Type Hints (Optional)
+
+```python
+preview(
+    "data.csv",
+    output="output",
+    type_hints={"payload": "json", "created_at": "datetime"},
+)
+```
+
+## Large Datasets
+
+```python
+preview("big.csv", output="output", chunk_size=2000)
+```
+
+## Links
+
+- 中文说明: [README-ch.md](README-ch.md)

viscsv-0.1.0/README.md

@@ -0,0 +1,69 @@
+# VisCSV
+
+![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)
+![Pandas](https://img.shields.io/badge/Pandas-2.x-150458?logo=pandas&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-000000?logo=opensourceinitiative&logoColor=white)
+
+VisCSV turns CSV data (with image paths) into a clean, interactive HTML table.  
+Simple API, fast preview, no server required.
+
+## Highlights
+
+- Image columns support (local paths or URLs)
+- Smart type inference (number, datetime, boolean, json, code)
+- Drag to reorder columns
+- Resize column widths
+- Built-in horizontal/vertical scrolling
+- Chunked loading for large datasets
+
+## Quickstart
+
+```python
+from viscsv import preview
+
+preview("data.csv", output="output")
+```
+
+Open `output/viewer.html` in your browser.
+
+## With Image Columns
+
+```python
+from viscsv import preview
+
+preview("data.csv", image="image_path", output="output")
+```
+
+## Use the Class API
+
+```python
+from viscsv import VisCSV
+
+vc = VisCSV(image="image")
+vc.add("imgs/1.jpg", label="cat", score=0.98)
+vc.add([
+    {"image": "imgs/2.jpg", "label": "dog", "score": 0.87},
+    {"image": "imgs/3.jpg", "label": "fox", "score": 0.72},
+])
+vc.build(output="output")
+```
+
+## Type Hints (Optional)
+
+```python
+preview(
+    "data.csv",
+    output="output",
+    type_hints={"payload": "json", "created_at": "datetime"},
+)
+```
+
+## Large Datasets
+
+```python
+preview("big.csv", output="output", chunk_size=2000)
+```
+
+## Links
+
+- 中文说明: [README-ch.md](README-ch.md)

viscsv-0.1.0/pyproject.toml

@@ -0,0 +1,10 @@
+[project]
+name = "viscsv"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pandas>=2.3.3",
+    "pillow>=12.1.0",
+]

viscsv-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

viscsv-0.1.0/src/viscsv/__init__.py

@@ -0,0 +1,3 @@
+from .builder import build_viewer, preview, render, VisCSV
+
+__all__ = ["build_viewer", "preview", "render", "VisCSV"]

viscsv-0.1.0/src/viscsv/builder.py

@@ -0,0 +1,438 @@
+from __future__ import annotations
+
+from pathlib import Path
+import json
+import shutil
+from typing import Iterable, Mapping, Sequence
+
+import numpy as np
+import pandas as pd
+
+from .meta import write_meta_chunk_js
+from .thumbnail import make_thumbnail
+from .viewer import write_viewer
+
+
+class VisCSV:
+    def __init__(
+        self,
+        image: str | Sequence[str] | None = None,
+        image_columns: str | Sequence[str] | None = None,
+        dataframe: pd.DataFrame | None = None,
+    ) -> None:
+        image = image if image is not None else image_columns
+        if isinstance(image, str):
+            image = [image]
+        self.image_columns = list(image) if image is not None else []
+        self.df = dataframe.copy() if dataframe is not None else pd.DataFrame()
+        self._validate_image_columns()
+
+    @classmethod
+    def from_csv(
+        cls,
+        csv_path: str | Path,
+        image: str | Sequence[str] | None = None,
+        **kwargs,
+    ) -> "VisCSV":
+        path = Path(csv_path)
+        if not path.exists():
+            raise FileNotFoundError(f"CSV not found: {path}")
+        data = pd.read_csv(path, **kwargs)
+        return cls(image=image, dataframe=data)
+
+    def add(self, *args, **fields) -> None:
+        if len(args) == 1 and not fields:
+            self.add_any(args[0])
+            return
+        if not args:
+            raise TypeError("add() expects data or image path.")
+        image_path = args[0]
+        if not self.image_columns:
+            raise ValueError("No image column configured. Use add_row/add_rows or set image column.")
+        row = {self.image_columns[0]: str(image_path), **fields}
+        self.add_row(row)
+
+    def add_data(self, data) -> None:
+        self.add_any(data)
+
+    def add_any(self, data) -> None:
+        if isinstance(data, pd.DataFrame):
+            self.add_rows(data)
+            return
+        if isinstance(data, dict):
+            self.add_row(data)
+            return
+        if isinstance(data, (list, tuple)):
+            if data and isinstance(data[0], dict):
+                self.add_rows(data)
+                return
+            if data and isinstance(data[0], (list, tuple)):
+                self.add_rows(data)
+                return
+        self.add_row(data)
+
+    def add_row(self, row: dict | Sequence) -> None:
+        if isinstance(row, dict):
+            df = pd.DataFrame([row])
+        elif isinstance(row, (list, tuple)):
+            if not len(self.df.columns):
+                raise ValueError("Cannot append list row without existing columns.")
+            df = pd.DataFrame([row], columns=list(self.df.columns))
+        else:
+            raise TypeError("row must be a dict or a list/tuple.")
+        self.df = pd.concat([self.df, df], ignore_index=True)
+        self._validate_image_columns()
+
+    def add_rows(self, rows: Iterable) -> None:
+        if isinstance(rows, pd.DataFrame):
+            df = rows
+        else:
+            rows = list(rows)
+            if not rows:
+                return
+            if isinstance(rows[0], dict):
+                df = pd.DataFrame(rows)
+            else:
+                if not len(self.df.columns):
+                    raise ValueError("Cannot append list rows without existing columns.")
+                df = pd.DataFrame(rows, columns=list(self.df.columns))
+        self.df = pd.concat([self.df, df], ignore_index=True)
+        self._validate_image_columns()
+
+    def to_csv(self, csv_path: str | Path, **kwargs) -> None:
+        path = Path(csv_path)
+        self.df.to_csv(path, index=False, **kwargs)
+
+    def build(
+        self,
+        output: str | Path = "output",
+        thumb_size: int = 256,
+        batch: int = 80,
+        image_column: str | None = None,
+        launch: bool = False,
+        type_hints: Mapping[str, str] | None = None,
+        chunk_size: int = 500,
+    ) -> Path:
+        image_column = image_column or (self.image_columns[0] if self.image_columns else None)
+        return render(
+            self.df,
+            image=image_column,
+            output=output,
+            thumb_size=thumb_size,
+            batch=batch,
+            image_columns=self.image_columns,
+            launch=launch,
+            type_hints=type_hints,
+            chunk_size=chunk_size,
+        )
+
+    def _validate_image_columns(self) -> None:
+        if not self.image_columns:
+            return
+        if len(self.df.columns) == 0:
+            return
+        for col in self.image_columns:
+            if col not in self.df.columns:
+                raise ValueError(f"Image column not found: {col}")
+
+
+def render(
+    data: str | Path | pd.DataFrame | list[dict] | list[tuple],
+    image: str | None = None,
+    output: str | Path = "output",
+    columns: list[str] | None = None,
+    thumb_size: int = 256,
+    batch: int = 80,
+    image_columns: Sequence[str] | None = None,
+    launch: bool = False,
+    type_hints: Mapping[str, str] | None = None,
+    chunk_size: int = 500,
+) -> Path:
+    df = _normalize_data(data, image=image, columns=columns)
+    inferred = infer_image_columns(df) if image_columns is None else list(image_columns)
+    if image is not None and image not in inferred:
+        inferred = [image] + [c for c in inferred if c != image]
+    return _build_viewer_from_df(
+        df,
+        image_columns=inferred,
+        output=output,
+        thumb_size=thumb_size,
+        batch=batch,
+        launch=launch,
+        type_hints=type_hints,
+        chunk_size=chunk_size,
+    )
+
+
+def build_viewer(
+    data: str | Path | pd.DataFrame | list[dict] | list[tuple],
+    image_column: str = "image",
+    output_dir: str = "output",
+    columns: list[str] | None = None,
+    thumb_size: int = 256,
+    batch_render: int = 80,
+    launch: bool = False,
+    type_hints: Mapping[str, str] | None = None,
+    chunk_size: int = 500,
+) -> Path:
+    return render(
+        data,
+        image=image_column,
+        output=output_dir,
+        columns=columns,
+        thumb_size=thumb_size,
+        batch=batch_render,
+        image_columns=[image_column],
+        launch=launch,
+        type_hints=type_hints,
+        chunk_size=chunk_size,
+    )
+
+
+def preview(
+    data: str | Path | pd.DataFrame | list[dict] | list[tuple],
+    image: str | None = None,
+    **kwargs,
+) -> Path:
+    return render(data, image=image, **kwargs)
+
+
+def _normalize_data(
+    data: str | Path | pd.DataFrame | list[dict] | list[tuple],
+    image: str | None,
+    columns: list[str] | None,
+) -> pd.DataFrame:
+    if isinstance(data, (str, Path)):
+        path = Path(data)
+        if not path.exists():
+            raise FileNotFoundError(f"CSV not found: {path}")
+        df = pd.read_csv(path)
+    elif isinstance(data, pd.DataFrame):
+        df = data.copy()
+    elif isinstance(data, list) and data:
+        if isinstance(data[0], tuple):
+            if image is None:
+                raise ValueError("image is required when using tuple data.")
+            if columns is None:
+                raise ValueError("columns is required when using tuple data.")
+            df = pd.DataFrame(data, columns=[image] + list(columns))
+        elif isinstance(data[0], dict):
+            df = pd.DataFrame(data)
+        else:
+            raise TypeError("Unsupported data format for render.")
+    else:
+        raise TypeError("Data must be a CSV path, DataFrame, or non-empty list.")
+
+    if image is not None and image not in df.columns:
+        raise ValueError(f"Image column not found: {image}")
+    return df
+
+
+def infer_image_columns(df: pd.DataFrame, sample_size: int = 50) -> list[str]:
+    candidates = []
+    name_hints = {"image", "img", "picture", "pic", "photo", "thumbnail", "thumb", "path", "filepath", "file"}
+    image_exts = {".jpg", ".jpeg", ".png", ".webp", ".bmp", ".gif"}
+
+    for col in df.columns:
+        if not pd.api.types.is_object_dtype(df[col]):
+            continue
+        col_lower = str(col).lower()
+        sample = df[col].dropna().astype(str).head(sample_size)
+        if sample.empty:
+            continue
+        hit = 0
+        for v in sample:
+            v = v.strip()
+            if v.startswith("http://") or v.startswith("https://"):
+                if any(ext in v.lower() for ext in image_exts):
+                    hit += 1
+                    continue
+            if any(v.lower().endswith(ext) for ext in image_exts):
+                hit += 1
+        ratio = hit / max(len(sample), 1)
+        if ratio >= 0.6 or any(h in col_lower for h in name_hints):
+            candidates.append(col)
+    return candidates
+
+
+def _infer_column_types(
+    df: pd.DataFrame,
+    image_columns: Sequence[str],
+    type_hints: Mapping[str, str] | None = None,
+    sample_size: int = 80,
+) -> dict[str, str]:
+    result: dict[str, str] = {}
+    type_hints = type_hints or {}
+    for col in df.columns:
+        if col in image_columns:
+            result[col] = "image"
+            continue
+        if col in type_hints:
+            result[col] = type_hints[col]
+            continue
+        result[col] = _infer_semantic_type(df[col], sample_size=sample_size)
+    return result
+
+
+def _infer_semantic_type(series: pd.Series, sample_size: int = 80) -> str:
+    dtype = series.dtype
+    if pd.api.types.is_bool_dtype(dtype):
+        return "boolean"
+    if pd.api.types.is_numeric_dtype(dtype):
+        return "number"
+    if pd.api.types.is_datetime64_any_dtype(dtype):
+        return "datetime"
+
+    sample = series.dropna().astype(str).head(sample_size)
+    if sample.empty:
+        return "string"
+
+    sample_list = [v.strip() for v in sample if v and str(v).strip()]
+    if not sample_list:
+        return "string"
+
+    json_hits = sum(1 for s in sample_list if _looks_like_json(s))
+    md_hits = sum(1 for s in sample_list if _looks_like_markdown(s))
+    code_hits = sum(1 for s in sample_list if _looks_like_code(s))
+    num_hits = _count_numeric(sample_list)
+    date_hits = _count_datetime(sample_list)
+
+    ratio = lambda n: n / max(len(sample_list), 1)
+    if ratio(json_hits) >= 0.6:
+        return "json"
+    if ratio(md_hits) >= 0.5:
+        return "markdown"
+    if ratio(code_hits) >= 0.5:
+        return "code"
+    if ratio(date_hits) >= 0.6:
+        return "datetime"
+    if ratio(num_hits) >= 0.8:
+        return "number"
+    return "string"
+
+
+def _looks_like_json(text: str) -> bool:
+    if not (text.startswith("{") and text.endswith("}")) and not (
+        text.startswith("[") and text.endswith("]")
+    ):
+        return False
+    try:
+        json.loads(text)
+        return True
+    except Exception:
+        return False
+
+
+def _looks_like_markdown(text: str) -> bool:
+    indicators = ("```", "# ", "## ", "- ", "* ", "> ", "[", "](", "**", "_")
+    return any(token in text for token in indicators)
+
+
+def _looks_like_code(text: str) -> bool:
+    indicators = (";", "{", "}", "def ", "class ", "function ", "=>", "var ", "let ", "const ")
+    return any(token in text for token in indicators)
+
+def _count_numeric(values: list[str]) -> int:
+    if not values:
+        return 0
+    parsed = pd.to_numeric(pd.Series(values), errors="coerce")
+    return int(parsed.notna().sum())
+
+
+def _count_datetime(values: list[str]) -> int:
+    if not values:
+        return 0
+    parsed = pd.to_datetime(
+        pd.Series(values),
+        errors="coerce",
+        utc=False,
+        format="mixed",
+        cache=True,
+    )
+    return int(parsed.notna().sum())
+
+
+def _to_jsonable(value):
+    if pd.isna(value):
+        return None
+    if isinstance(value, (np.integer, np.floating, np.bool_)):
+        return value.item()
+    if isinstance(value, pd.Timestamp):
+        return value.isoformat()
+    return value
+
+
+def _build_viewer_from_df(
+    df: pd.DataFrame,
+    image_columns: Sequence[str],
+    output: str | Path,
+    thumb_size: int,
+    batch: int,
+    launch: bool,
+    type_hints: Mapping[str, str] | None,
+    chunk_size: int,
+) -> Path:
+    out = Path(output)
+    out.mkdir(parents=True, exist_ok=True)
+    img_dir = out / "images"
+    thumb_dir = out / "thumbs"
+    if image_columns:
+        img_dir.mkdir(parents=True, exist_ok=True)
+        thumb_dir.mkdir(parents=True, exist_ok=True)
+
+    records: list[dict] = []
+    chunk_index = 0
+    chunk_paths: list[Path] = []
+    columns = list(df.columns)
+    for i, row in enumerate(df.reset_index(drop=True).itertuples(index=False, name=None)):
+        row_map = dict(zip(columns, row))
+        img_map: dict[str, str | None] = {}
+        for col in image_columns:
+            raw_path = row_map[col]
+            img_id = None
+            if pd.notna(raw_path):
+                raw_text = str(raw_path)
+                if raw_text.startswith("http://") or raw_text.startswith("https://"):
+                    img_id = None
+                else:
+                    img_path = Path(raw_text)
+                    ext = img_path.suffix.lower() if img_path.suffix else ".jpg"
+                    name = f"{i:06d}_{col}{ext}"
+                    if img_path.exists():
+                        shutil.copy(img_path, img_dir / name)
+                        make_thumbnail(img_path, thumb_dir / name, thumb_size)
+                        img_id = name
+            img_map[col] = img_id
+
+        record = {"__img_id__": img_map}
+        for col in columns:
+            record[col] = _to_jsonable(row_map[col])
+        records.append(record)
+
+        if chunk_size > 0 and len(records) >= chunk_size:
+            chunk_path = out / f"meta_{chunk_index:04d}.js"
+            write_meta_chunk_js(chunk_path, records)
+            chunk_paths.append(chunk_path)
+            records = []
+            chunk_index += 1
+
+    if records or not chunk_paths:
+        chunk_path = out / f"meta_{chunk_index:04d}.js"
+        write_meta_chunk_js(chunk_path, records)
+        chunk_paths.append(chunk_path)
+    column_types = _infer_column_types(df, image_columns=image_columns, type_hints=type_hints)
+    write_viewer(
+        out / "viewer.html",
+        columns=columns,
+        column_types=column_types,
+        image_column=image_columns[0] if image_columns else "",
+        image_columns=list(image_columns),
+        batch_size=batch,
+        chunk_count=len(chunk_paths),
+    )
+    html_path = out / "viewer.html"
+    if launch:
+        import webbrowser
+
+        webbrowser.open(html_path.resolve().as_uri())
+    return html_path

viscsv-0.1.0/src/viscsv/meta.py

@@ -0,0 +1,18 @@
+import json
+from pathlib import Path
+from typing import Iterable
+
+
+def write_meta_jsonl(meta_path: Path, records: Iterable[dict]) -> None:
+    with meta_path.open("w", encoding="utf-8") as f:
+        for r in records:
+            f.write(json.dumps(r, ensure_ascii=False) + "\n")
+
+
+def write_meta_chunk_js(meta_path: Path, records: list[dict]) -> None:
+    payload = (
+        "window.__VISCSV_LAST_CHUNK__ = "
+        + json.dumps(records, ensure_ascii=False)
+        + ";"
+    )
+    meta_path.write_text(payload, encoding="utf-8")

viscsv-0.1.0/src/viscsv/thumbnail.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+from PIL import Image, ImageDraw
+
+
+def _save_image(img: Image.Image, dst: Path, quality: int) -> None:
+    ext = dst.suffix.lower()
+    if ext == ".png":
+        img.save(dst, "PNG", optimize=True)
+    else:
+        img.save(dst, "JPEG", quality=quality)
+
+
+def make_thumbnail(src: Path, dst: Path, size: int, quality: int = 85) -> bool:
+    try:
+        img = Image.open(src)
+        img.thumbnail((size, size))
+        _save_image(img, dst, quality)
+        return True
+    except Exception:
+        img = Image.new("RGB", (size, size), (235, 235, 235))
+        draw = ImageDraw.Draw(img)
+        draw.rectangle([(0, 0), (size - 1, size - 1)], outline=(190, 190, 190))
+        draw.line([(0, 0), (size - 1, size - 1)], fill=(200, 200, 200), width=2)
+        draw.line([(0, size - 1), (size - 1, 0)], fill=(200, 200, 200), width=2)
+        _save_image(img, dst, quality)
+        return False