tha-csv-runner 0.1.0__tar.gz

tha_csv_runner-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Type check
+        run: uv run mypy src/

tha_csv_runner-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tha_csv_runner-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*_processed_*.csv
+*_errors_*.csv
+output.csv

tha_csv_runner-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nate Wright
+
+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.

tha_csv_runner-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: tha-csv-runner
+Version: 0.1.0
+Summary: Run a function over every row of a CSV — with progress, header validation, and structured per-row errors.
+Project-URL: Homepage, https://github.com/tha-guy-nate/tha-csv-runner
+Project-URL: Issues, https://github.com/tha-guy-nate/tha-csv-runner/issues
+Author: Nate Wright
+License: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: tqdm>=4.66
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tha-csv-runner
+
+[![CI](https://github.com/tha-guy-nate/tha-csv-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/tha-guy-nate/tha-csv-runner/actions/workflows/ci.yml)
+
+A small Python library that runs a function against every row of a CSV — with a progress bar, required header validation, and structured error capture per row.
+
+## Install
+
+```bash
+pip install tha-csv-runner
+```
+
+## Quick start
+
+```python
+from tha_csv_runner import Runner
+
+def process(row: dict) -> None:
+    """Raise any exception to mark the row as an error. Return value is ignored."""
+    if not row["email"].endswith("@example.com"):
+        raise ValueError("invalid email domain")
+
+runner = Runner(
+    input_path="data.csv",
+    required_headers=["name", "email"],
+    processor=process,
+)
+runner.run()
+runner.write("output.csv")
+```
+
+## How it works
+
+1. Opens the CSV and validates that all `required_headers` are present — raises immediately if any are missing
+2. Iterates every row with a `tqdm` progress bar
+3. Calls your `processor(row)` function — if it raises, that row is marked as an error and processing continues
+4. Appends three columns to every row: `row_number`, `row_status`, and `message`
+   - On success: `row_status` and `message` are blank
+   - On error: `row_status = "error"`, `message = str(exception)`
+5. `write()` writes all rows (success and error) to a CSV
+
+## API
+
+### `Runner`
+
+```python
+Runner(
+    input_path="data.csv",       # path to input CSV
+    required_headers=["a", "b"], # columns that must exist — raises ConfigError if missing
+    processor=my_func,           # optional: callable(row: dict) -> None
+    sample=100,                  # optional: process only the first N rows
+)
+```
+
+### `runner.run()`
+
+Reads and processes all rows. Results are stored in `runner.rows` as a list of dicts.
+
+### `runner.write()`
+
+```python
+runner.write(
+    output_path="output.csv",          # optional — auto-named input_processed_TIMESTAMP.csv if omitted
+    sort_by="name",                    # optional — column name, or list of column names
+    ascending=True,                    # optional — bool or list of bools matching sort_by
+    column_order=["name", "email"],    # optional — listed columns come first, rest follow
+    keep=["name", "email"],            # optional — keep only these columns (mutually exclusive with drop)
+    drop=["row_number"],               # optional — remove these columns (mutually exclusive with keep)
+)
+```
+
+Returns the `Path` that was written.
+
+## CLI
+
+```bash
+tha-csv-runner run \
+    --input data.csv \
+    --processor my_module:process_row \
+    --header name \
+    --header email \
+    --sample 100
+```
+
+`--processor` uses the `module:function` convention. `--header` is repeatable. All flags are optional except `--input`.
+
+## License
+
+MIT

tha_csv_runner-0.1.0/README.md

@@ -0,0 +1,89 @@
+# tha-csv-runner
+
+[![CI](https://github.com/tha-guy-nate/tha-csv-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/tha-guy-nate/tha-csv-runner/actions/workflows/ci.yml)
+
+A small Python library that runs a function against every row of a CSV — with a progress bar, required header validation, and structured error capture per row.
+
+## Install
+
+```bash
+pip install tha-csv-runner
+```
+
+## Quick start
+
+```python
+from tha_csv_runner import Runner
+
+def process(row: dict) -> None:
+    """Raise any exception to mark the row as an error. Return value is ignored."""
+    if not row["email"].endswith("@example.com"):
+        raise ValueError("invalid email domain")
+
+runner = Runner(
+    input_path="data.csv",
+    required_headers=["name", "email"],
+    processor=process,
+)
+runner.run()
+runner.write("output.csv")
+```
+
+## How it works
+
+1. Opens the CSV and validates that all `required_headers` are present — raises immediately if any are missing
+2. Iterates every row with a `tqdm` progress bar
+3. Calls your `processor(row)` function — if it raises, that row is marked as an error and processing continues
+4. Appends three columns to every row: `row_number`, `row_status`, and `message`
+   - On success: `row_status` and `message` are blank
+   - On error: `row_status = "error"`, `message = str(exception)`
+5. `write()` writes all rows (success and error) to a CSV
+
+## API
+
+### `Runner`
+
+```python
+Runner(
+    input_path="data.csv",       # path to input CSV
+    required_headers=["a", "b"], # columns that must exist — raises ConfigError if missing
+    processor=my_func,           # optional: callable(row: dict) -> None
+    sample=100,                  # optional: process only the first N rows
+)
+```
+
+### `runner.run()`
+
+Reads and processes all rows. Results are stored in `runner.rows` as a list of dicts.
+
+### `runner.write()`
+
+```python
+runner.write(
+    output_path="output.csv",          # optional — auto-named input_processed_TIMESTAMP.csv if omitted
+    sort_by="name",                    # optional — column name, or list of column names
+    ascending=True,                    # optional — bool or list of bools matching sort_by
+    column_order=["name", "email"],    # optional — listed columns come first, rest follow
+    keep=["name", "email"],            # optional — keep only these columns (mutually exclusive with drop)
+    drop=["row_number"],               # optional — remove these columns (mutually exclusive with keep)
+)
+```
+
+Returns the `Path` that was written.
+
+## CLI
+
+```bash
+tha-csv-runner run \
+    --input data.csv \
+    --processor my_module:process_row \
+    --header name \
+    --header email \
+    --sample 100
+```
+
+`--processor` uses the `module:function` convention. `--header` is repeatable. All flags are optional except `--input`.
+
+## License
+
+MIT

tha_csv_runner-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tha-csv-runner"
+version = "0.1.0"
+description = "Run a function over every row of a CSV — with progress, header validation, and structured per-row errors."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Nate Wright" }]
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "click>=8.1",
+    "tqdm>=4.66",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+tha-csv-runner = "tha_csv_runner.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/tha-guy-nate/tha-csv-runner"
+Issues = "https://github.com/tha-guy-nate/tha-csv-runner/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tha_csv_runner"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "RUF"]
+
+[tool.mypy]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tha_csv_runner-0.1.0/src/tha_csv_runner/__init__.py

@@ -0,0 +1,7 @@
+"""tha-csv-runner: run a function over every row of a CSV."""
+
+from .errors import ConfigError
+from .runner import Runner
+
+__version__ = "0.1.0"
+__all__ = ["ConfigError", "Runner"]

tha_csv_runner-0.1.0/src/tha_csv_runner/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

tha_csv_runner-0.1.0/src/tha_csv_runner/cli.py

@@ -0,0 +1,77 @@
+import importlib
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+import click
+
+from .errors import ConfigError
+from .runner import Runner
+
+
+def _load_processor(spec: str) -> Callable[[dict], None]:
+    try:
+        module_name, func_name = spec.rsplit(":", 1)
+    except ValueError:
+        raise click.BadParameter(f"Expected format 'module:function', got: {spec!r}") from None
+
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError:
+        raise click.BadParameter(f"Cannot import module {module_name!r}") from None
+
+    if not hasattr(module, func_name):
+        raise click.BadParameter(f"Module {module_name!r} has no attribute {func_name!r}")
+
+    return getattr(module, func_name)
+
+
+@click.group()
+def main() -> None:
+    """Run a Python function over every row of a CSV."""
+
+
+@main.command()
+@click.option("--input", "input_path", required=True, help="Path to the input CSV file")
+@click.option("--header", "required_headers", multiple=True, help="Required CSV header (repeatable)")  # noqa: E501
+@click.option(
+    "--processor", "processor_spec", default=None,
+    help="Processor in 'module:function' format (optional)",
+)
+@click.option("--sample", default=None, type=int, help="Process only the first N rows")
+@click.option(
+    "--output", "output_path", default=None, help="Output CSV path (auto-named if omitted)",
+)
+def run(
+    input_path: str,
+    processor_spec: str | None,
+    required_headers: tuple[str, ...],
+    sample: int | None,
+    output_path: str | None,
+) -> None:
+    """Run a processor function over every row of a CSV."""
+    if not Path(input_path).exists():
+        click.echo(f"Error: input file not found: {input_path}", err=True)
+        sys.exit(1)
+
+    processor = None
+    if processor_spec is not None:
+        try:
+            processor = _load_processor(processor_spec)
+        except click.BadParameter as exc:
+            click.echo(f"Error: {exc}", err=True)
+            sys.exit(1)
+
+    try:
+        runner = Runner(
+            input_path=input_path,
+            required_headers=list(required_headers),
+            processor=processor,
+            sample=sample,
+        )
+        runner.run()
+        out = runner.write(output_path=output_path)
+        click.echo(f"Wrote {out}")
+    except ConfigError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)

tha_csv_runner-0.1.0/src/tha_csv_runner/errors.py

@@ -0,0 +1,2 @@
+class ConfigError(Exception):
+    """Raised for invalid Runner configuration."""

tha_csv_runner-0.1.0/src/tha_csv_runner/runner.py

@@ -0,0 +1,128 @@
+import csv
+import functools
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+
+from tqdm import tqdm
+
+from .errors import ConfigError
+
+
+def _sort_key(val: object) -> tuple:
+    try:
+        return (0, float(val))  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return (1, str(val))
+
+
+class Runner:
+    def __init__(
+        self,
+        input_path: str | Path,
+        required_headers: list[str],
+        processor: Callable[[dict], None] | None = None,
+        sample: int | None = None,
+    ) -> None:
+        self.input_path = Path(input_path)
+        self.processor = processor
+        self.required_headers = required_headers
+        self.sample = sample
+        self.rows: list[dict] = []
+        self._ran: bool = False
+
+    def _load(self) -> list[dict]:
+        with open(self.input_path, newline="", encoding="utf-8") as f:
+            reader = csv.DictReader(f)
+            if reader.fieldnames is None:
+                raise ConfigError(f"{self.input_path} appears to be empty")
+            missing = [h for h in self.required_headers if h not in reader.fieldnames]
+            if missing:
+                raise ConfigError(f"Missing required headers: {missing}")
+            rows = list(reader)
+
+        if self.sample is not None:
+            rows = rows[: self.sample]
+
+        return rows
+
+    def run(self) -> None:
+        raw_rows = self._load()
+        self.rows = []
+        self._ran = True
+
+        for i, row in enumerate(tqdm(raw_rows, desc=f"Reading {self.input_path.name}"), start=1):
+            enriched = {**row, "row_number": i, "row_status": "", "message": ""}
+            try:
+                if self.processor is not None:
+                    self.processor(enriched)
+            except Exception as exc:
+                enriched["row_status"] = "error"
+                enriched["message"] = str(exc)
+            self.rows.append(enriched)
+
+    def write(
+        self,
+        output_path: str | Path | None = None,
+        sort_by: str | list[str] | None = None,
+        ascending: bool | list[bool] = True,
+        column_order: list[str] | None = None,
+        keep: list[str] | None = None,
+        drop: list[str] | None = None,
+    ) -> Path:
+        if not self._ran:
+            raise RuntimeError("No data to write — call run() first")
+        if keep and drop:
+            raise ValueError("Cannot specify both keep and drop")
+
+        rows = list(self.rows)
+
+        # --- column filtering ---
+        all_cols = list(rows[0].keys()) if rows else []
+
+        if keep:
+            cols = [c for c in keep if c in all_cols]
+        elif drop:
+            cols = [c for c in all_cols if c not in drop]
+        else:
+            cols = all_cols
+
+        # --- column ordering: listed cols first, unlisted follow in original order ---
+        if column_order:
+            front = [c for c in column_order if c in cols]
+            rest = [c for c in cols if c not in column_order]
+            cols = front + rest
+
+        # --- sorting ---
+        if sort_by is not None:
+            sort_cols = [sort_by] if isinstance(sort_by, str) else list(sort_by)
+            asc_list = (
+                [ascending] * len(sort_cols) if isinstance(ascending, bool) else list(ascending)
+            )
+
+            def compare(a: dict, b: dict) -> int:
+                for col, asc in zip(sort_cols, asc_list, strict=True):
+                    ka, kb = _sort_key(a.get(col, "")), _sort_key(b.get(col, ""))
+                    if ka < kb:
+                        return -1 if asc else 1
+                    if ka > kb:
+                        return 1 if asc else -1
+                return 0
+
+            rows.sort(key=functools.cmp_to_key(compare))
+
+        # --- output path ---
+        if output_path is None:
+            ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+            output_path = Path(f"{self.input_path.stem}_processed_{ts}.csv")
+
+        out = Path(output_path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(out, "w", newline="", encoding="utf-8") as f:
+            if rows:
+                writer = csv.DictWriter(f, fieldnames=cols)
+                writer.writeheader()
+                writer.writerows({c: row[c] for c in cols if c in row} for row in rows)
+
+        return out

tha_csv_runner-0.1.0/tests/conftest.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+
+import pytest
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+@pytest.fixture
+def simple_csv() -> Path:
+    return FIXTURES / "simple.csv"
+
+
+@pytest.fixture
+def error_csv() -> Path:
+    return FIXTURES / "with_errors.csv"

tha_csv_runner-0.1.0/tests/fixtures/processors.py

@@ -0,0 +1,7 @@
+def noop(row: dict) -> None:
+    pass
+
+
+def fail_on_bob(row: dict) -> None:
+    if row["name"] == "Bob":
+        raise ValueError("Bob is not allowed")

tha_csv_runner-0.1.0/tests/fixtures/simple.csv

@@ -0,0 +1,4 @@
+id,name,email
+1,Alice,alice@example.com
+2,Bob,bob@example.com
+3,Carol,carol@example.com

tha_csv_runner-0.1.0/tests/fixtures/with_errors.csv

@@ -0,0 +1,4 @@
+id,name,value
+1,Alice,10
+2,Bob,bad_value
+3,Carol,30