tha-csv-runner 0.2.2__tar.gz → 0.2.4__tar.gz

{tha_csv_runner-0.2.2 → tha_csv_runner-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tha-csv-runner
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -47,8 +47,8 @@ def process(row: dict) -> None:
 
 runner = ThaCSV()
 
-rows = runner.read("Step 1 of 1", "data.csv", ["name", "email"], process)
-runner.write("Step 1 of 1", "output.csv")
+rows = runner.read("Step 1 of 2", "data.csv", ["name", "email"], process)
+runner.write("Step 2 of 2", "output.csv")
 ```
 
 ## How it works
@@ -57,6 +57,7 @@ runner.write("Step 1 of 1", "output.csv")
 2. Iterates every row with a `tqdm` progress bar labelled with `desc`
 3. Calls your `validator(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`
+   - `row number` starts at 2 (row 1 is the header)
    - 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
@@ -73,7 +74,7 @@ ThaCSV()
 
 ```python
 runner.read(
-    "Step 2 of 10",          # progress bar label — pass None to use the filename
+    "Step 1 of 2",           # progress bar label — pass None to use the filename
     "data.csv",              # path to input CSV
     ["a", "b"],              # columns that must exist — raises ConfigError if missing
     validator=my_func,       # optional: callable(row: dict) -> None
@@ -89,17 +90,30 @@ When `enrich=False`, validator exceptions are re-raised instead of captured.
 
 ```python
 runner.write(
-    "Step 10 of 10",                   # progress bar label — pass None to use the output filename
+    "Step 2 of 2",                     # progress bar label — pass None for "Writing {stem} CSV"
     output_path="output.csv",          # optional — auto-named input_processed_TIMESTAMP.csv if omitted
+    rows=my_rows,                      # optional — use these rows instead of runner.rows
     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)
+    chunk_size=1000,                   # optional — split output into files of this many rows
 )
 ```
 
-Returns the `Path` that was written.
+Prints `:white_check_mark: Done! CSV was written to: {path}` on completion. Override by setting `runner.status_cb = my_fn`.
+
+Returns the `Path` that was written, or a `list[Path]` when `chunk_size` is set.
+
+#### `chunk_size`
+
+When provided, `write()` splits the output into multiple files named `output_001.csv`, `output_002.csv`, etc. and returns a `list[Path]`.
+
+```python
+paths = runner.write("Step 2 of 2", "output.csv", chunk_size=1000)
+# ["output_001.csv", "output_002.csv", ...]
+```
 
 ## License
 

{tha_csv_runner-0.2.2 → tha_csv_runner-0.2.4}/README.md

@@ -22,8 +22,8 @@ def process(row: dict) -> None:
 
 runner = ThaCSV()
 
-rows = runner.read("Step 1 of 1", "data.csv", ["name", "email"], process)
-runner.write("Step 1 of 1", "output.csv")
+rows = runner.read("Step 1 of 2", "data.csv", ["name", "email"], process)
+runner.write("Step 2 of 2", "output.csv")
 ```
 
 ## How it works
@@ -32,6 +32,7 @@ runner.write("Step 1 of 1", "output.csv")
 2. Iterates every row with a `tqdm` progress bar labelled with `desc`
 3. Calls your `validator(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`
+   - `row number` starts at 2 (row 1 is the header)
    - 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
@@ -48,7 +49,7 @@ ThaCSV()
 
 ```python
 runner.read(
-    "Step 2 of 10",          # progress bar label — pass None to use the filename
+    "Step 1 of 2",           # progress bar label — pass None to use the filename
     "data.csv",              # path to input CSV
     ["a", "b"],              # columns that must exist — raises ConfigError if missing
     validator=my_func,       # optional: callable(row: dict) -> None
@@ -64,17 +65,30 @@ When `enrich=False`, validator exceptions are re-raised instead of captured.
 
 ```python
 runner.write(
-    "Step 10 of 10",                   # progress bar label — pass None to use the output filename
+    "Step 2 of 2",                     # progress bar label — pass None for "Writing {stem} CSV"
     output_path="output.csv",          # optional — auto-named input_processed_TIMESTAMP.csv if omitted
+    rows=my_rows,                      # optional — use these rows instead of runner.rows
     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)
+    chunk_size=1000,                   # optional — split output into files of this many rows
 )
 ```
 
-Returns the `Path` that was written.
+Prints `:white_check_mark: Done! CSV was written to: {path}` on completion. Override by setting `runner.status_cb = my_fn`.
+
+Returns the `Path` that was written, or a `list[Path]` when `chunk_size` is set.
+
+#### `chunk_size`
+
+When provided, `write()` splits the output into multiple files named `output_001.csv`, `output_002.csv`, etc. and returns a `list[Path]`.
+
+```python
+paths = runner.write("Step 2 of 2", "output.csv", chunk_size=1000)
+# ["output_001.csv", "output_002.csv", ...]
+```
 
 ## License
 

{tha_csv_runner-0.2.2 → tha_csv_runner-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tha-csv-runner"
-version = "0.2.2"
+version = "0.2.4"
 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" }

{tha_csv_runner-0.2.2 → tha_csv_runner-0.2.4}/src/tha_csv_runner/__init__.py

@@ -3,5 +3,5 @@
 from .errors import ConfigError
 from .runner import ThaCSV
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 __all__ = ["ConfigError", "ThaCSV"]

{tha_csv_runner-0.2.2 → tha_csv_runner-0.2.4}/src/tha_csv_runner/runner.py

@@ -1,5 +1,6 @@
 import csv
 import functools
+import shutil
 from collections.abc import Callable
 from datetime import datetime
 from pathlib import Path
@@ -9,6 +10,10 @@ from tqdm import tqdm
 from .errors import ConfigError
 
 
+def tqdm_ncols(max_cols: int = 85) -> int:
+    return min(shutil.get_terminal_size(fallback=(max_cols, 24)).columns, max_cols)
+
+
 def _sort_key(val: object) -> tuple:
     try:
         return (0, float(val))  # type: ignore[arg-type]
@@ -16,11 +21,24 @@ def _sort_key(val: object) -> tuple:
         return (1, str(val))
 
 
+def _write_chunk(path: Path, rows: list[dict], cols: list[str], label: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "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 tqdm(rows, desc=label, ncols=tqdm_ncols())
+            )
+
+
 class ThaCSV:
     def __init__(self) -> None:
         self.rows: list[dict] = []
         self._read: bool = False
         self._input_path: Path | None = None
+        self.status_cb = print
 
     def read(
         self,
@@ -44,8 +62,8 @@ class ThaCSV:
         self.rows = []
         self._read = True
 
-        label = desc if desc is not None else self._input_path.name
-        for i, row in enumerate(tqdm(raw_rows, desc=label), start=1):
+        label = desc if desc is not None else f"Reading {self._input_path.stem} CSV"
+        for i, row in enumerate(tqdm(raw_rows, desc=label, ncols=tqdm_ncols()), start=2):
             if enrich:
                 enriched = {**row, "row number": i, "row status": "", "message": ""}
             else:
@@ -67,18 +85,22 @@ class ThaCSV:
         self,
         desc: str | None,
         output_path: str | Path | None = None,
+        rows: list[dict] | 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._read:
-            raise RuntimeError("No data to write — call read() first")
+        chunk_size: int | None = None,
+    ) -> Path | list[Path]:
+        if rows is None and not self._read:
+            raise RuntimeError("No data to write — call read() first or pass rows=")
         if keep and drop:
             raise ValueError("Cannot specify both keep and drop")
+        if chunk_size is not None and chunk_size < 1:
+            raise ValueError("chunk_size must be >= 1")
 
-        rows = list(self.rows)
+        rows = list(rows) if rows is not None else list(self.rows)
 
         # --- column filtering ---
         all_cols = list(rows[0].keys()) if rows else []
@@ -120,17 +142,25 @@ class ThaCSV:
             ts = datetime.now().strftime("%Y%m%d_%H%M%S")
             output_path = Path(f"{stem}_processed_{ts}.csv")
 
-        out = Path(output_path)
-        out.parent.mkdir(parents=True, exist_ok=True)
-
-        write_label = desc if desc is not None else out.name
-        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 tqdm(rows, desc=write_label)
+        output_file = Path(output_path)
+
+        # --- chunked write ---
+        if chunk_size is not None:
+            chunks = [rows[i:i + chunk_size] for i in range(0, max(len(rows), 1), chunk_size)]
+            paths = []
+            for idx, chunk in enumerate(chunks, start=1):
+                chunk_path = output_file.parent / f"{output_file.stem}_{idx:03d}{output_file.suffix}"
+                label = (
+                    f"{desc} ({idx}/{len(chunks)})"
+                    if desc
+                    else f"Writing {output_file.stem} CSV ({idx}/{len(chunks)})"
                 )
-
-        return out
+                _write_chunk(chunk_path, chunk, cols, label)
+                paths.append(chunk_path)
+            self.status_cb(f":white_check_mark: Done! CSV was written to: {paths}")
+            return paths
+
+        write_label = desc if desc is not None else f"Writing {output_file.stem} CSV"
+        _write_chunk(output_file, rows, cols, write_label)
+        self.status_cb(f":white_check_mark: Done! CSV was written to: {output_file}")
+        return output_file

{tha_csv_runner-0.2.2 → tha_csv_runner-0.2.4}/tests/test_runner.py

@@ -33,8 +33,8 @@ def test_read_returns_rows(simple_csv: Path) -> None:
 def test_row_number_injected(simple_csv: Path) -> None:
     runner = ThaCSV()
     runner.read(None, simple_csv, ["name"])
-    assert runner.rows[0]["row number"] == 1
-    assert runner.rows[2]["row number"] == 3
+    assert runner.rows[0]["row number"] == 2
+    assert runner.rows[2]["row number"] == 4
 
 
 def test_message_and_status_columns_present(simple_csv: Path) -> None:
@@ -118,6 +118,17 @@ def test_write_before_read_raises(simple_csv: Path) -> None:
         runner.write(None)
 
 
+def test_write_rows_param_bypasses_read_guard(tmp_path: Path) -> None:
+    out = tmp_path / "out.csv"
+    rows = [{"name": "Alice", "val": "1"}, {"name": "Bob", "val": "2"}]
+    runner = ThaCSV()
+    result = runner.write(None, out, rows=rows)
+    assert isinstance(result, Path)
+    written = list(csv.DictReader(out.open()))
+    assert len(written) == 2
+    assert written[0]["name"] == "Alice"
+
+
 def test_write_sort_by_single(simple_csv: Path, tmp_path: Path) -> None:
     out = tmp_path / "out.csv"
     runner = ThaCSV()
@@ -223,3 +234,68 @@ def test_enrich_false_validator_error_still_raises(simple_csv: Path) -> None:
     runner = ThaCSV()
     with pytest.raises(ValueError, match="Bob is not allowed"):
         runner.read(None, simple_csv, ["name"], fail_on_bob, enrich=False)
+
+
+# --- chunk_size ---
+
+def test_chunk_size_returns_list(simple_csv: Path, tmp_path: Path) -> None:
+    runner = ThaCSV()
+    runner.read(None, simple_csv, ["name"])
+    result = runner.write(None, tmp_path / "out.csv", chunk_size=2)
+    assert isinstance(result, list)
+
+
+def test_chunk_size_correct_file_count(simple_csv: Path, tmp_path: Path) -> None:
+    runner = ThaCSV()
+    runner.read(None, simple_csv, ["name"])
+    paths = runner.write(None, tmp_path / "out.csv", chunk_size=2)
+    assert isinstance(paths, list)
+    assert len(paths) == 2  # 3 rows → chunks of 2, 1
+
+
+def test_chunk_size_files_exist(simple_csv: Path, tmp_path: Path) -> None:
+    runner = ThaCSV()
+    runner.read(None, simple_csv, ["name"])
+    paths = runner.write(None, tmp_path / "out.csv", chunk_size=2)
+    assert isinstance(paths, list)
+    assert all(p.exists() for p in paths)
+
+
+def test_chunk_size_naming(simple_csv: Path, tmp_path: Path) -> None:
+    runner = ThaCSV()
+    runner.read(None, simple_csv, ["name"])
+    paths = runner.write(None, tmp_path / "out.csv", chunk_size=2)
+    assert isinstance(paths, list)
+    assert paths[0].name == "out_001.csv"
+    assert paths[1].name == "out_002.csv"
+
+
+def test_chunk_size_total_rows(simple_csv: Path, tmp_path: Path) -> None:
+    runner = ThaCSV()
+    runner.read(None, simple_csv, ["name"])
+    paths = runner.write(None, tmp_path / "out.csv", chunk_size=2)
+    assert isinstance(paths, list)
+    total = sum(len(list(csv.DictReader(p.open()))) for p in paths)
+    assert total == 3
+
+
+def test_chunk_size_larger_than_rows(simple_csv: Path, tmp_path: Path) -> None:
+    runner = ThaCSV()
+    runner.read(None, simple_csv, ["name"])
+    paths = runner.write(None, tmp_path / "out.csv", chunk_size=100)
+    assert isinstance(paths, list)
+    assert len(paths) == 1
+
+
+def test_chunk_size_zero_raises(simple_csv: Path, tmp_path: Path) -> None:
+    runner = ThaCSV()
+    runner.read(None, simple_csv, ["name"])
+    with pytest.raises(ValueError, match="chunk_size"):
+        runner.write(None, tmp_path / "out.csv", chunk_size=0)
+
+
+def test_no_chunk_size_returns_path(simple_csv: Path, tmp_path: Path) -> None:
+    runner = ThaCSV()
+    runner.read(None, simple_csv, ["name"])
+    result = runner.write(None, tmp_path / "out.csv")
+    assert isinstance(result, Path)

{tha_csv_runner-0.2.2 → tha_csv_runner-0.2.4}/uv.lock

@@ -308,7 +308,7 @@ wheels = [
 
 [[package]]
 name = "tha-csv-runner"
-version = "0.2.2"
+version = "0.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "tqdm" },