modify-csv 2026.10.4__py3-none-any.whl

modify_csv/__init__.py

@@ -0,0 +1,5 @@
+"""Tools for applying Python transformations to CSV files."""
+
+from .transform import CellEvaluator, transform_csv
+
+__all__ = ["CellEvaluator", "transform_csv"]

modify_csv/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

modify_csv/cli.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from .errors import ModifyCsvError
+from .script import load_evaluator, load_evaluator_file
+from .transform import Target, transform_csv
+
+EVAL_SIGNATURE = "def eval(content: Any, row: int, col: int) -> Any:"
+TEMPLATE = f'''"""CSV cell transformation."""
+
+from typing import Any
+
+
+{EVAL_SIGNATURE}
+    """Return the transformed cell content."""
+    return content
+'''
+
+
+def _parser_description() -> str:
+    return f"Required script function:\n  {EVAL_SIGNATURE}"
+
+
+def _column(value: str) -> int | str:
+    try:
+        index = int(value)
+    except ValueError:
+        return value
+    if index < 0:
+        raise argparse.ArgumentTypeError("column index must be zero or greater")
+    return index
+
+
+def _row(value: str) -> int:
+    try:
+        index = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("row must be a zero-based integer") from exc
+    if index < 0:
+        raise argparse.ArgumentTypeError("row index must be zero or greater")
+    return index
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="modify-csv",
+        description="Apply a Python eval function to one CSV row, column, or cell.",
+        epilog=_parser_description(),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    apply_parser = commands.add_parser(
+        "apply",
+        help="apply a script to a CSV target",
+        description="Apply a Python eval function to one CSV row, column, or cell.",
+        epilog=_parser_description(),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    apply_parser.add_argument("input", type=Path, help="input CSV file")
+    apply_parser.add_argument("output", type=Path, help="output CSV file")
+
+    scripts = apply_parser.add_mutually_exclusive_group(required=True)
+    scripts.add_argument("--script-file", type=Path, help="path to a Python script")
+    scripts.add_argument("--script", help="inline Python script text")
+
+    targets = apply_parser.add_mutually_exclusive_group(required=True)
+    targets.add_argument("--row", type=_row, help="zero-based data row index")
+    targets.add_argument(
+        "--column", type=_column, help="zero-based column index or exact header name"
+    )
+    targets.add_argument(
+        "--cell",
+        nargs=2,
+        metavar=("ROW", "COLUMN"),
+        help="zero-based data row and a column index or header name",
+    )
+    apply_parser.add_argument(
+        "--force", action="store_true", help="overwrite the output file if it exists"
+    )
+
+    template_parser = commands.add_parser(
+        "template",
+        help="generate a script template",
+        description="Generate a Python script implementing the required contract.",
+        epilog=_parser_description(),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    template_parser.add_argument("output", type=Path, help="template output path")
+    template_parser.add_argument(
+        "--force", action="store_true", help="overwrite the output file if it exists"
+    )
+    return parser
+
+
+def _target_from_args(args: argparse.Namespace, parser: argparse.ArgumentParser) -> Target:
+    if args.row is not None:
+        return ("row", args.row, None)
+    if args.column is not None:
+        return ("column", args.column, None)
+
+    row_text, column_text = args.cell
+    try:
+        row = _row(row_text)
+        column = _column(column_text)
+    except argparse.ArgumentTypeError as exc:
+        parser.error(str(exc))
+    return ("cell", row, column)
+
+
+def _write_template(output: Path, overwrite: bool) -> None:
+    if output.exists() and not overwrite:
+        raise ModifyCsvError(
+            f"output file already exists: {output} (use --force to overwrite)"
+        )
+    try:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(TEMPLATE, encoding="utf-8")
+    except OSError as exc:
+        raise ModifyCsvError(f"could not write template {output}: {exc}") from exc
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    # Preserve the original invocation while steering new usage toward subcommands.
+    if arguments and arguments[0] not in {"apply", "template", "-h", "--help"}:
+        arguments.insert(0, "apply")
+    args = parser.parse_args(arguments)
+
+    try:
+        if args.command == "template":
+            _write_template(args.output, args.force)
+            return 0
+
+        target = _target_from_args(args, parser)
+        evaluator = (
+            load_evaluator_file(args.script_file)
+            if args.script_file is not None
+            else load_evaluator(args.script)
+        )
+        transform_csv(
+            args.input,
+            args.output,
+            target,
+            evaluator,
+            overwrite=args.force,
+        )
+    except ModifyCsvError as exc:
+        print(f"modify-csv: error: {exc}", file=sys.stderr)
+        return 1
+    return 0

modify_csv/errors.py

@@ -0,0 +1,6 @@
+class ModifyCsvError(Exception):
+    """Base class for expected modify-csv errors."""
+
+
+class ScriptContractError(ModifyCsvError):
+    """Raised when a supplied script does not implement the required contract."""

modify_csv/script.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import inspect
+from pathlib import Path
+from typing import Any, Callable
+
+from .errors import ScriptContractError
+
+CellEvaluator = Callable[[Any, int, int], Any]
+
+
+def load_evaluator(source: str, source_name: str = "<inline script>") -> CellEvaluator:
+    """Execute source and return its contract-compliant ``eval`` function."""
+    namespace: dict[str, Any] = {"__name__": "__modify_csv_script__"}
+    try:
+        code = compile(source, source_name, "exec")
+        exec(code, namespace)
+    except Exception as exc:
+        raise ScriptContractError(f"could not load {source_name}: {exc}") from exc
+
+    evaluator = namespace.get("eval")
+    if not callable(evaluator):
+        raise ScriptContractError(
+            "script must define a callable named eval with signature "
+            "eval(content: Any, row: int, col: int) -> Any"
+        )
+
+    signature = inspect.signature(evaluator)
+    parameters = list(signature.parameters.values())
+    expected_names = ["content", "row", "col"]
+    valid_kinds = {
+        inspect.Parameter.POSITIONAL_ONLY,
+        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+    }
+    if (
+        len(parameters) != 3
+        or [parameter.name for parameter in parameters] != expected_names
+        or any(parameter.kind not in valid_kinds for parameter in parameters)
+        or any(parameter.default is not inspect.Parameter.empty for parameter in parameters)
+    ):
+        raise ScriptContractError(
+            f"eval has signature {signature}; expected "
+            "(content: Any, row: int, col: int) -> Any"
+        )
+
+    return evaluator
+
+
+def load_evaluator_file(path: Path) -> CellEvaluator:
+    try:
+        source = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ScriptContractError(f"could not read script {path}: {exc}") from exc
+    return load_evaluator(source, str(path))

modify_csv/transform.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import csv
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Callable, TypeAlias
+
+from .errors import ModifyCsvError
+
+CellEvaluator: TypeAlias = Callable[[Any, int, int], Any]
+Target: TypeAlias = tuple[str, int | str, int | str | None]
+
+
+def _resolve_column(column: int | str, header: list[str]) -> int:
+    if isinstance(column, int):
+        index = column
+    else:
+        matches = [index for index, value in enumerate(header) if value == column]
+        if not matches:
+            raise ModifyCsvError(f"column header not found: {column!r}")
+        if len(matches) > 1:
+            raise ModifyCsvError(f"column header is ambiguous: {column!r}")
+        index = matches[0]
+
+    if not 0 <= index < len(header):
+        raise ModifyCsvError(
+            f"column index {index} is out of range for {len(header)} columns"
+        )
+    return index
+
+
+def _apply_target(
+    rows: list[list[str]],
+    header: list[str],
+    target: Target,
+    evaluator: CellEvaluator,
+) -> None:
+    kind, first, second = target
+
+    if kind == "row":
+        row_index = int(first)
+        if not 0 <= row_index < len(rows):
+            raise ModifyCsvError(
+                f"row index {row_index} is out of range for {len(rows)} data rows"
+            )
+        for col_index, content in enumerate(rows[row_index]):
+            rows[row_index][col_index] = evaluator(content, row_index, col_index)
+        return
+
+    if kind == "column":
+        col_index = _resolve_column(first, header)
+        for row_index, row in enumerate(rows):
+            row[col_index] = evaluator(row[col_index], row_index, col_index)
+        return
+
+    row_index = int(first)
+    if not 0 <= row_index < len(rows):
+        raise ModifyCsvError(
+            f"row index {row_index} is out of range for {len(rows)} data rows"
+        )
+    col_index = _resolve_column(second if second is not None else -1, header)
+    rows[row_index][col_index] = evaluator(
+        rows[row_index][col_index], row_index, col_index
+    )
+
+
+def transform_csv(
+    input_path: Path,
+    output_path: Path,
+    target: Target,
+    evaluator: CellEvaluator,
+    *,
+    overwrite: bool = False,
+) -> None:
+    """Transform the selected CSV cells and atomically write the result."""
+    if output_path.exists() and not overwrite:
+        raise ModifyCsvError(
+            f"output file already exists: {output_path} (use --force to overwrite)"
+        )
+
+    try:
+        with input_path.open("r", encoding="utf-8-sig", newline="") as stream:
+            records = list(csv.reader(stream))
+    except (OSError, csv.Error) as exc:
+        raise ModifyCsvError(f"could not read CSV {input_path}: {exc}") from exc
+
+    if not records:
+        raise ModifyCsvError("input CSV is empty and has no header")
+
+    header, rows = records[0], records[1:]
+    if not header:
+        raise ModifyCsvError("input CSV has an empty header")
+    malformed = next(
+        (index for index, row in enumerate(rows) if len(row) != len(header)), None
+    )
+    if malformed is not None:
+        raise ModifyCsvError(
+            f"data row {malformed} has {len(rows[malformed])} columns; "
+            f"expected {len(header)}"
+        )
+
+    try:
+        _apply_target(rows, header, target, evaluator)
+    except ModifyCsvError:
+        raise
+    except Exception as exc:
+        raise ModifyCsvError(f"eval failed: {exc}") from exc
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    temporary_name: str | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            newline="",
+            dir=output_path.parent,
+            prefix=f".{output_path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as stream:
+            temporary_name = stream.name
+            writer = csv.writer(stream)
+            writer.writerow(header)
+            writer.writerows(rows)
+        os.replace(temporary_name, output_path)
+    except (OSError, csv.Error) as exc:
+        if temporary_name is not None:
+            Path(temporary_name).unlink(missing_ok=True)
+        raise ModifyCsvError(f"could not write CSV {output_path}: {exc}") from exc

modify_csv-2026.10.4.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: modify-csv
+Version: 2026.10.4
+Summary: Apply a user-supplied Python function to a CSV row, column, or cell.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# modify-csv
+
+Apply a user-provided Python function to every cell in one CSV data row, every
+cell in one column, or one cell. The CSV's first record is treated as its header
+and is never modified. Row and column indexes are zero-based; columns can also
+be addressed by their exact header text.
+
+## Install
+
+Install a published release from PyPI:
+
+```sh
+python -m pip install modify-csv
+```
+
+Or install a tagged version directly from the private GitHub repository using
+SSH authentication:
+
+```sh
+python -m pip install "git+ssh://git@github.com/martinjose/modify-csv.git@v0.1.0"
+```
+
+Git and access to the private repository are required for the second form. Each
+GitHub Release also provides a universal wheel and source archive.
+
+For local development, install an editable copy:
+
+```sh
+python -m pip install -e .
+```
+
+This installs the `modify-csv` command. You can also run the package without an
+installation using `PYTHONPATH=src python -m modify_csv`.
+
+## Script contract
+
+The supplied script must define exactly this callable shape:
+
+```python
+from typing import Any
+
+
+def eval(content: Any, row: int, col: int) -> Any:
+    return content
+```
+
+`Any` is provided by Python's standard-library `typing` module. The function
+name, parameter names, and three-argument shape are enforced.
+
+`content` is the current CSV field (initially a string), while `row` and `col`
+are zero-based numeric indexes into the data records and columns. The returned
+value is passed to Python's CSV writer. The script is ordinary trusted Python
+and executes with the same permissions as the command.
+
+## Examples
+
+Apply a script file to a column selected by header:
+
+```sh
+modify-csv apply input.csv output.csv --script-file normalize.py --column email
+```
+
+Apply inline code to data row 2:
+
+```sh
+modify-csv apply input.csv output.csv \
+  --script 'def eval(content, row, col): return content.strip()' \
+  --row 2
+```
+
+Apply inline code to the cell at data row 0 and column 1:
+
+```sh
+modify-csv apply input.csv output.csv \
+  --script 'def eval(content, row, col): return int(content) * 2' \
+  --cell 0 1
+```
+
+Exactly one of `--script` or `--script-file`, and exactly one of `--row`,
+`--column`, or `--cell`, is required. Existing output files are protected;
+pass `--force` to replace one.
+
+Generate a ready-to-edit transformation script:
+
+```sh
+modify-csv template transform.py
+```
+
+Use `--force` to replace an existing template. Run `modify-csv --help` or the
+help for either subcommand to see the required function signature. The original
+form without the `apply` subcommand remains supported for compatibility.
+
+## Releasing
+
+Versions follow `YYYY.M.RELEASE`, where `RELEASE` starts at `1` each month. For
+example, the first release in October 2026 is `2026.10.1`.
+
+Preview the next version without changing the repository:
+
+```sh
+python scripts/release.py next
+```
+
+To update `pyproject.toml`, create the release commit, and create an annotated
+tag locally for inspection:
+
+```sh
+python scripts/release.py prepare
+```
+
+The command prints the exact push command to use after reviewing the commit and
+tag. To prepare and push both atomically in one step instead, run:
+
+```sh
+python scripts/release.py release
+```
+
+Release preparation requires a clean `main` branch. The package version in
+`pyproject.toml` remains the release source of truth. Pushing the generated tag
+starts the GitHub Actions release process:
+
+```sh
+git push --atomic origin main v2026.10.1
+```
+
+The tag-triggered release workflow tests Python 3.10 and 3.13 on Linux, macOS,
+and Windows. It then builds and validates a platform-independent wheel and
+source archive, publishes them to TestPyPI through trusted publishing, verifies
+that the package installs and runs from TestPyPI, and stages the exact artifacts
+in a draft GitHub Release.
+
+After reviewing the successful run, open **Actions**, select **Release**, choose
+**Run workflow**, and enter the tag. This explicit manual action verifies and
+publishes the staged artifacts to PyPI, then publishes the draft GitHub Release.
+A mismatched version and tag, missing draft release, or changed artifact causes
+the production run to fail.
+
+Trusted publishers must be configured independently on TestPyPI and PyPI. Both
+use owner `martinjose`, repository `modify-csv`, and workflow `release.yml`.
+The TestPyPI publisher uses environment `testpypi`; the production publisher
+uses environment `pypi`. The manually dispatched production run serves as the
+approval gate for private repositories without environment reviewer support.

modify_csv-2026.10.4.dist-info/RECORD

@@ -0,0 +1,11 @@
+modify_csv/__init__.py,sha256=6vHqQECPhZA56nXpai3qh33V_Bfnyu8Le5j6Ey6C9sw,161
+modify_csv/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+modify_csv/cli.py,sha256=YT1zD8r71uwYJVn4zPdGKh5t1Ut8tKVlIfolLMQcZ0o,5171
+modify_csv/errors.py,sha256=cUY7TeD5Xqgn8TzL-DDy1pBwgA7HGc8joD6AjCiHIZc,213
+modify_csv/script.py,sha256=JtrZO2knEkeOMIMuYmwuFgrTRiEUtUBkURynic007Kk,1890
+modify_csv/transform.py,sha256=BI-tJWyaelutF6pvUcwarFuYC0ILQxydmut6NdMDE9M,4216
+modify_csv-2026.10.4.dist-info/METADATA,sha256=KNwhX1K0_t2W8URWE2euIRHGHpO3dw_4Sng7zRrAALA,4731
+modify_csv-2026.10.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+modify_csv-2026.10.4.dist-info/entry_points.txt,sha256=3tNZwsCtDepnc9plRykrjXruU1rY_mPBpNdWPFwVfuQ,51
+modify_csv-2026.10.4.dist-info/top_level.txt,sha256=8wrCNZWfgQaxZh5pvc291H5DjJEJIv0Cu2R7ms0M3sM,11
+modify_csv-2026.10.4.dist-info/RECORD,,

modify_csv-2026.10.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

modify_csv-2026.10.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+modify-csv = modify_csv.cli:main

modify_csv-2026.10.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+modify_csv