normalize-tabular-data 0.1.0__tar.gz → 0.1.2__tar.gz

{normalize_tabular_data-0.1.0 → normalize_tabular_data-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: normalize-tabular-data
-Version: 0.1.0
+Version: 0.1.2
 Summary: TUI for normalizing tabular data with polars
 Author: David Mertz, Ph.D.
 Author-email: David Mertz, Ph.D. <mertz@gnosis.cx>
@@ -26,6 +26,8 @@ Load a file, see a preview, build up a pipeline of normalization operations
 combine/split columns, drop columns), then save the
 cleaned result.
 
+![TUI preview](https://raw.githubusercontent.com/SEIU-Tech/normalize-tabular-data/main/docs/screenshot.png)
+
 ## Running
 
 ### Persistent install
@@ -43,56 +45,83 @@ uv tool upgrade normalize-tabular-data
 ```bash
 uvx normalize-tabular-data
 # pin a specific version:
-uvx normalize-tabular-data==0.1.0
+uvx normalize-tabular-data==0.1.1
 ```
 
-### Straight from a checkout
+### From a git checkout
+
+Within the directory of the cloned repository:
 
 ```bash
 uv run normalize-tabular-data
 ```
 
-### The TestPyPI sandbox
+## Command line
+
+An optional `FILE` argument names a table to open at startup, as if you
+had picked it from the in-app dialog.
+
+```bash
+normalize-tabular-data data/members.csv      # or with uvx/uv run
+uvx normalize-tabular-data data/members.tsv
+```
+
+If the file is missing or its format cannot be read, the TUI still
+starts — it shows an alert toast and you can open something else.
+
+### Open with a script
+
+With `--script/-s`, an `.ntd` script is played on `FILE` as soon as it
+loads (same flow as the `p` key, same stop-and-rollback on a step that
+does not fit the file):
+
+```bash
+uvx normalize-tabular-data data/members.csv -s data/members.ntd
+```
+
+### Headless run (`-x`, `--run`)
 
-The test build (uploaded via `make testpypi`) is not on PyPI; point uv
-at TestPyPI first and PyPI as the fallback index — the tool itself is
-found on TestPyPI, its dependencies (`textual`, `polars`, …) on PyPI:
+`--run/-x` skips the TUI: it opens `FILE`, plays `SCRIPT` step by step,
+saves the result and exits. Each operation prints to stdout as it is
+applied; anything else — including a failing step, named and rolled
+back exactly as the interactive player would — goes to stderr with a
+nonzero exit code.
 
 ```bash
-uvx \
-  --index-url https://test.pypi.org/simple/ \
-  --extra-index-url https://pypi.org/simple/ \
-  normalize-tabular-data==0.1.0
-
-# or installed persistently:
-uv tool install \
-  --index-url https://test.pypi.org/simple/ \
-  --extra-index-url https://pypi.org/simple/ \
-  normalize-tabular-data==0.1.0
+# saves data/members-normalized.csv next to the original
+uvx normalize-tabular-data members.csv -s members.ntd -x
+
+# choose the destination (format taken from its extension):
+uvx normalize-tabular-data members.csv -s members.ntd -x -o out/members.parquet
+
+# write the CSV to a pipe instead:
+uvx normalize-tabular-data members.csv -s members.ntd -x -o - | gzip > clean.csv.gz
 ```
 
-uv caches resolved packages aggressively: after a TestPyPI re-upload of
-the same version, add `--refresh-package normalize-tabular-data` so it
-re-consults the index rather than reusing the cached artifact.
+With `-o -` (attached `-o-` works too), the transformed table is written
+to stdout itself and the step lines are suppressed, so stdout carries
+only the data. After a successful run the confirmation line goes to
+stderr.
 
 ## Usage
 
 Launch with `normalize-tabular-data`. Keys:
 
-| Key | Action                      |
-|-----|-----------------------------|
-| `f` | (F)ile — open a file        |
-| `o` | (O)peration — choose an op  |
-| `p` | (P)lay script — reapply a saved `.ntd` sequence |
-| `u` | (U)ndo last applied step    |
-| `r` | (R)edo                      |
-| `s` | (S)ave the data in a format |
-| `q` | (Q)uit                      |
+| Key | Action                       |
+|-----|------------------------------|
+| `f` | (F)ile — open a file         |
+| `o` | (O)peration — choose an op   |
+| `p` | (P)lay script — apply `.ntd` |
+| `u` | (U)ndo last applied step     |
+| `r` | (R)edo                       |
+| `s` | (S)ave the data in a format  |
+| `q` | (Q)uit                       |
 
 ## Operations
 
 - **Normalize dates** — parse a messy date column of *any* input format into
-  canonical UTC datetimes; unparseable values become null.
+  canonical UTC `year-month-dayThh:mm:ss` values (second resolution;
+  fractional parts are truncated); unparseable values become null.
 - **Trim whitespace** — strip edges and collapse internal whitespace runs,
   per selected columns.
 - Rename a column — click its header in the preview and type the new name.
@@ -121,24 +150,26 @@ The script is plain ASCII text, one operation per line, e.g.:
 
 ```
 # normalize-tabular-data script
-# source: employees.csv
-# table: /data/employees-normalized.csv
+# source: worksite.csv
+# table: /data/worksite-normalized.csv
 # saved: 2026-10-05T12:30:11
-trim_collapse(columns=["Dept", "Name"])
-date_normalize(column="Hired Date")
+date_normalize(column="Signed Up")
+trim_collapse(columns=["Full Name", "Worksite", "Job Class"])
+split_column(column="Full Name", delimiter="")
+rename_single(column="Full Name_1", new_name="First Name")
+rename_single(column="Full Name_2", new_name="Last Name")
 ```
 
 ## Playing a script back
 
 Press `p` (available while a file is loaded) to pick a script file: the
 dialog previews the highlighted `.ntd` file (syntax-highlighted, first 40
-lines) before you confirm. Its operations are applied, in order, to the table you have open. If any step
-cannot be performed against the currently loaded file — a column it
-renames, trims or splits is missing, the operation is unknown — playing
-stops with an alert naming the failing step, and every step the script had
-already applied is rolled back, so the table is left exactly as it was.
-
-![TUI preview](docs/screenshot.png)
+lines) before you confirm. Its operations are applied, in order, to the table 
+you have open. If any step cannot be performed against the currently loaded 
+file — a column it renames, trims or splits is missing, the operation is 
+unknown — playing stops with an alert naming the failing step, and every step
+the script had already applied is rolled back, so the table is left exactly as 
+it was.
 
 ## Publishing
 

{normalize_tabular_data-0.1.0 → normalize_tabular_data-0.1.2}/README.md

@@ -10,6 +10,8 @@ Load a file, see a preview, build up a pipeline of normalization operations
 combine/split columns, drop columns), then save the
 cleaned result.
 
+![TUI preview](https://raw.githubusercontent.com/SEIU-Tech/normalize-tabular-data/main/docs/screenshot.png)
+
 ## Running
 
 ### Persistent install
@@ -27,56 +29,83 @@ uv tool upgrade normalize-tabular-data
 ```bash
 uvx normalize-tabular-data
 # pin a specific version:
-uvx normalize-tabular-data==0.1.0
+uvx normalize-tabular-data==0.1.1
 ```
 
-### Straight from a checkout
+### From a git checkout
+
+Within the directory of the cloned repository:
 
 ```bash
 uv run normalize-tabular-data
 ```
 
-### The TestPyPI sandbox
+## Command line
+
+An optional `FILE` argument names a table to open at startup, as if you
+had picked it from the in-app dialog.
+
+```bash
+normalize-tabular-data data/members.csv      # or with uvx/uv run
+uvx normalize-tabular-data data/members.tsv
+```
+
+If the file is missing or its format cannot be read, the TUI still
+starts — it shows an alert toast and you can open something else.
+
+### Open with a script
+
+With `--script/-s`, an `.ntd` script is played on `FILE` as soon as it
+loads (same flow as the `p` key, same stop-and-rollback on a step that
+does not fit the file):
+
+```bash
+uvx normalize-tabular-data data/members.csv -s data/members.ntd
+```
+
+### Headless run (`-x`, `--run`)
 
-The test build (uploaded via `make testpypi`) is not on PyPI; point uv
-at TestPyPI first and PyPI as the fallback index — the tool itself is
-found on TestPyPI, its dependencies (`textual`, `polars`, …) on PyPI:
+`--run/-x` skips the TUI: it opens `FILE`, plays `SCRIPT` step by step,
+saves the result and exits. Each operation prints to stdout as it is
+applied; anything else — including a failing step, named and rolled
+back exactly as the interactive player would — goes to stderr with a
+nonzero exit code.
 
 ```bash
-uvx \
-  --index-url https://test.pypi.org/simple/ \
-  --extra-index-url https://pypi.org/simple/ \
-  normalize-tabular-data==0.1.0
-
-# or installed persistently:
-uv tool install \
-  --index-url https://test.pypi.org/simple/ \
-  --extra-index-url https://pypi.org/simple/ \
-  normalize-tabular-data==0.1.0
+# saves data/members-normalized.csv next to the original
+uvx normalize-tabular-data members.csv -s members.ntd -x
+
+# choose the destination (format taken from its extension):
+uvx normalize-tabular-data members.csv -s members.ntd -x -o out/members.parquet
+
+# write the CSV to a pipe instead:
+uvx normalize-tabular-data members.csv -s members.ntd -x -o - | gzip > clean.csv.gz
 ```
 
-uv caches resolved packages aggressively: after a TestPyPI re-upload of
-the same version, add `--refresh-package normalize-tabular-data` so it
-re-consults the index rather than reusing the cached artifact.
+With `-o -` (attached `-o-` works too), the transformed table is written
+to stdout itself and the step lines are suppressed, so stdout carries
+only the data. After a successful run the confirmation line goes to
+stderr.
 
 ## Usage
 
 Launch with `normalize-tabular-data`. Keys:
 
-| Key | Action                      |
-|-----|-----------------------------|
-| `f` | (F)ile — open a file        |
-| `o` | (O)peration — choose an op  |
-| `p` | (P)lay script — reapply a saved `.ntd` sequence |
-| `u` | (U)ndo last applied step    |
-| `r` | (R)edo                      |
-| `s` | (S)ave the data in a format |
-| `q` | (Q)uit                      |
+| Key | Action                       |
+|-----|------------------------------|
+| `f` | (F)ile — open a file         |
+| `o` | (O)peration — choose an op   |
+| `p` | (P)lay script — apply `.ntd` |
+| `u` | (U)ndo last applied step     |
+| `r` | (R)edo                       |
+| `s` | (S)ave the data in a format  |
+| `q` | (Q)uit                       |
 
 ## Operations
 
 - **Normalize dates** — parse a messy date column of *any* input format into
-  canonical UTC datetimes; unparseable values become null.
+  canonical UTC `year-month-dayThh:mm:ss` values (second resolution;
+  fractional parts are truncated); unparseable values become null.
 - **Trim whitespace** — strip edges and collapse internal whitespace runs,
   per selected columns.
 - Rename a column — click its header in the preview and type the new name.
@@ -105,24 +134,26 @@ The script is plain ASCII text, one operation per line, e.g.:
 
 ```
 # normalize-tabular-data script
-# source: employees.csv
-# table: /data/employees-normalized.csv
+# source: worksite.csv
+# table: /data/worksite-normalized.csv
 # saved: 2026-10-05T12:30:11
-trim_collapse(columns=["Dept", "Name"])
-date_normalize(column="Hired Date")
+date_normalize(column="Signed Up")
+trim_collapse(columns=["Full Name", "Worksite", "Job Class"])
+split_column(column="Full Name", delimiter="")
+rename_single(column="Full Name_1", new_name="First Name")
+rename_single(column="Full Name_2", new_name="Last Name")
 ```
 
 ## Playing a script back
 
 Press `p` (available while a file is loaded) to pick a script file: the
 dialog previews the highlighted `.ntd` file (syntax-highlighted, first 40
-lines) before you confirm. Its operations are applied, in order, to the table you have open. If any step
-cannot be performed against the currently loaded file — a column it
-renames, trims or splits is missing, the operation is unknown — playing
-stops with an alert naming the failing step, and every step the script had
-already applied is rolled back, so the table is left exactly as it was.
-
-![TUI preview](docs/screenshot.png)
+lines) before you confirm. Its operations are applied, in order, to the table 
+you have open. If any step cannot be performed against the currently loaded 
+file — a column it renames, trims or splits is missing, the operation is 
+unknown — playing stops with an alert naming the failing step, and every step
+the script had already applied is rolled back, so the table is left exactly as 
+it was.
 
 ## Publishing
 

{normalize_tabular_data-0.1.0 → normalize_tabular_data-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "normalize-tabular-data"
-version = "0.1.0"
+version = "0.1.2"
 description = "TUI for normalizing tabular data with polars"
 readme = "README.md"
 license = "BSD-2-Clause"

{normalize_tabular_data-0.1.0 → normalize_tabular_data-0.1.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "normalize-tabular-data"
-version = "0.1.0"
+version = "0.1.2"
 description = "TUI for normalizing tabular data with polars"
 readme = "README.md"
 license = "BSD-2-Clause"

normalize_tabular_data-0.1.2/src/normalize_tabular_data/__init__.py

@@ -0,0 +1,152 @@
+"""normalize-tabular-data: TUI for normalizing tabular data with polars."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+__version__ = "0.1.2"
+
+
+def _run_script(path: Path, script_path: Path, output: Path | None) -> int:
+    """`--run` mode: play SCRIPT against FILE and save the result, no TUI.
+
+    Operation steps print to STDOUT as they are applied (suppressed when
+    STDOUT itself is the output, so the only thing there is the table);
+    every other message, including any step failure, goes to STDERR and
+    exits nonzero. A failed script leaves nothing written."""
+    from normalize_tabular_data import io
+    from normalize_tabular_data.ops import Pipeline, apply_script_steps
+
+    try:
+        steps = io.read_script(script_path)
+    except Exception as exc:
+        print(f"Could not read {script_path.name}: {exc}", file=sys.stderr)
+        return 1
+    if not steps:
+        print(f"{script_path.name} contains no operations", file=sys.stderr)
+        return 1
+    try:
+        fmt = io.detect_format(path)
+        table = io.read_table(path, fmt)
+    except Exception as exc:
+        print(f"Could not read {path.name}: {exc}", file=sys.stderr)
+        return 1
+
+    pipeline = Pipeline(source=table)
+    op_log: list[tuple[str, dict]] = []
+    to_stdout = output is not None and str(output) == "-"
+    if not to_stdout:
+        for key, params in steps:
+            print(io.step_line(key, params))
+
+    def fail(reason: str) -> None:
+        print(reason, file=sys.stderr)
+
+    if not apply_script_steps(steps, pipeline, op_log, fail):
+        return 1
+    # the transformed frame lives in the pipeline; the `table` variable
+    # still holds the raw source
+    table = pipeline.current()
+
+    out_path = (
+        None if to_stdout else (output or path.with_stem(path.stem + "-normalized"))
+    )
+    try:
+        if out_path is None:
+            if fmt not in ("csv", "tsv", "jsonl"):
+                print(
+                    f"{fmt!r} is not a text format: it cannot be written to "
+                    "STDOUT. Name an --output file with a csv/tsv/jsonl "
+                    "extension instead.",
+                    file=sys.stderr,
+                )
+                return 1
+            if fmt == "csv":
+                table.write_csv(sys.stdout)
+            elif fmt == "tsv":
+                table.write_csv(sys.stdout, separator="\t")
+            else:
+                table.write_ndjson(sys.stdout)
+        else:
+            out_fmt = io.detect_format(out_path)
+            if out_path.suffix.lower() == ".xls":
+                print(
+                    ".xls cannot be written; use --output <name>.xlsx", file=sys.stderr
+                )
+                return 1
+            io.write_table(table, out_path, out_fmt)
+    except Exception as exc:
+        print(f"Save failed: {exc}", file=sys.stderr)
+        return 1
+
+    count = len(steps)
+    landing = "STDOUT" if out_path is None else str(out_path)
+    print(
+        f"Applied {count} step{'s' if count != 1 else ''} from "
+        f"{script_path.name} -> {landing}",
+        file=sys.stderr,
+    )
+    return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="normalize-tabular-data",
+        description="A terminal UI for normalizing tabular data with polars.",
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        type=Path,
+        metavar="FILE",
+        help="table file to open at startup (csv, tsv, jsonl, parquet, xlsx)",
+    )
+    parser.add_argument(
+        "-s",
+        "--script",
+        type=Path,
+        metavar="SCRIPT",
+        help="an .ntd operation script to play on FILE after opening it",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        metavar="PATH",
+        help="where --run saves the transformed table: a path whose format "
+        "is its extension, or - for STDOUT (default: the FILE stem plus "
+        "-normalized, same directory and extension)",
+    )
+    parser.add_argument(
+        "-x",
+        "--run",
+        action="store_true",
+        help="open FILE, play SCRIPT step by step, save the result and "
+        "exit (no UI; requires FILE and --script)",
+    )
+    argv = sys.argv[1:]
+    args = parser.parse_args(argv)
+
+    if args.script is not None and args.file is None:
+        parser.error("--script needs a FILE to open")
+    if args.output is not None and not args.run:
+        parser.error("--output only applies with --run")
+    if args.run:
+        if args.file is None:
+            parser.error("--run needs a FILE to open")
+        if args.script is None:
+            parser.error("--run needs --script (there would be nothing to play)")
+        raise SystemExit(_run_script(args.file, args.script, args.output))
+
+    try:
+        from normalize_tabular_data.app import NormalizeApp
+    except ImportError as exc:  # helpful message if an optional engine is missing
+        print(
+            f"normalize-tabular-data is missing a dependency ({exc}).\n"
+            "Reinstall with: uv tool install --force --reinstall normalize-tabular-data",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+    NormalizeApp(initial_file=args.file, initial_script=args.script).run()

{normalize_tabular_data-0.1.0 → normalize_tabular_data-0.1.2}/src/normalize_tabular_data/app.py

@@ -28,6 +28,7 @@ from normalize_tabular_data.ops import (
     Operation,
     Pipeline,
     analyze_column,
+    apply_script_steps as ops_apply_script_steps,
 )
 from normalize_tabular_data.screens import (
     ModalDialog,
@@ -270,8 +271,22 @@ class NormalizeApp(App[None]):
     }
     """
 
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        initial_file: str | Path | None = None,
+        initial_script: str | Path | None = None,
+    ) -> None:
         super().__init__()
+        # filesystem path to open when the app starts (the optional file
+        # named on the command line); loaded like a file chosen in-app
+        self.initial_file: Path | None = (
+            Path(initial_file) if initial_file is not None else None
+        )
+        # .ntd script played automatically once that file is loaded (the
+        # optional --script named on the command line); requires a file
+        self.initial_script: Path | None = (
+            Path(initial_script) if initial_script is not None else None
+        )
         self.path: Path | None = None
         self.pipeline: Pipeline | None = None
         self.analyzed: dict[str, Any] = {}
@@ -341,6 +356,11 @@ class NormalizeApp(App[None]):
     def on_mount(self) -> None:
         self.push_screen(MainScreen())
         self._refresh_steps()
+        # the command line's file, if any, is opened once the main screen
+        # is composed; load_path toasts a readable alert instead of
+        # crashing if it is unreadable or has an unsupported format
+        if self.initial_file is not None:
+            self.call_after_refresh(self.load_path, self.initial_file)
 
     # --- data plumbing ---------------------------------------------------
 
@@ -386,6 +406,11 @@ class NormalizeApp(App[None]):
         # pipeline is now set: re-evaluate the footer's enabled keys
         self.screen.refresh_bindings()
         self.notify(f"Loaded {path.name} ({df.height:,} rows x {df.width} columns)")
+        # --script named on the command line: play it as soon as its file
+        # is on screen (same flow as the P key, with the same rollback)
+        if self.initial_script is not None:
+            self.play_script_file(self.initial_script)
+            self.initial_script = None
 
     def analyze_columns(self) -> None:
         if self.pipeline is None:
@@ -499,50 +524,27 @@ class NormalizeApp(App[None]):
             return
         started_applied = len(self.pipeline.applied)
         started_log = len(self.op_log)
-        for index, (key, params) in enumerate(steps, 1):
-            op = PLAY_REGISTRY.get(key)
-            if op is None:
-                self._rollback_script(
-                    index,
-                    started_applied,
-                    started_log,
-                    f"Step {index}: {key!r} is not a known operation",
-                )
-                return
-            try:
-                self.pipeline.apply(op, params)
-                # the pipeline refolds lazily; fold now so an op-specific
-                # error (e.g. unparseable dates) rolls back this step too
-                self.pipeline.current()
-            except Exception as exc:
-                self._rollback_script(
-                    index,
-                    started_applied,
-                    started_log,
-                    f"Step {index} of {len(steps)} ({op.title}) failed: {exc}",
-                )
-                return
-            self.op_log.append((key, dict(params)))
+
+        def alert(reason: str) -> None:
+            # same alert the player has always shown: step description plus
+            # how much of the script had to be rolled back
+            undid = len(self.pipeline.applied) - started_applied
+            detail = (
+                f" — rolled back {undid} step{'s' if undid != 1 else ''}"
+                if undid
+                else ""
+            )
+            self.refresh_all()
+            self.notify(f"{reason}{detail}", severity="error")
+
+        if not ops_apply_script_steps(steps, self.pipeline, self.op_log, alert):
+            return
         self.refresh_all()
         count = len(steps)
         self.notify(
             f"Applied {count} step{'s' if count != 1 else ''} from {script_path.name}"
         )
 
-    def _rollback_script(
-        self, step: int, started_applied: int, started_log: int, reason: str
-    ) -> None:
-        """Undo everything a partially played script applied, then alert."""
-        undid = len(self.pipeline.applied) - started_applied
-        del self.pipeline.applied[started_applied:]
-        self.pipeline.redo_stack.clear()
-        del self.op_log[started_log:]
-        self.refresh_all()
-        detail = (
-            f" — rolled back {undid} step{'s' if undid != 1 else ''}" if undid else ""
-        )
-        self.notify(f"{reason}{detail}", severity="error")
-
     def _apply_now(self, op: Operation, params: dict[str, Any]) -> None:
         try:
             self.pipeline.apply(op, params)

{normalize_tabular_data-0.1.0 → normalize_tabular_data-0.1.2}/src/normalize_tabular_data/io.py

@@ -104,21 +104,21 @@ def write_table(
 SCRIPT_SUFFIX = ".ntd"
 
 
+def step_line(key: str, params: dict) -> str:
+    """One operation description: `<key>(<param>=<json value>, ...)`."""
+    return f"{key}({', '.join(f'{p}={json.dumps(v)}' for p, v in params.items())})"
+
+
 def script_text(steps: list[tuple[str, dict]], header_fields: dict[str, str]) -> str:
     """Human-readable ASCII text, one operation description per line.
 
-    Every operation is `<key>(<param>=<json value>, ...)` so the lines stay
-    readable while remaining mechanically parseable for a future
-    "apply a script" capability. `header_fields` become leading `#`
+    Every operation is `step_line()`'s `<key>(<param>=<json value>, ...)`
+    so the lines stay readable while remaining mechanically parseable for a
+    future "apply a script" capability. `header_fields` become leading `#`
     comment lines (source file, save time, ...)"""
     lines = ["# normalize-tabular-data script"]
     lines += [f"# {text}" for text in header_fields.values() if text]
-    lines += [
-        f"{key}("
-        + ", ".join(f"{param}={json.dumps(value)}" for param, value in params.items())
-        + ")"
-        for key, params in steps
-    ]
+    lines += [step_line(key, params) for key, params in steps]
     return "\n".join(lines) + "\n"
 
 

{normalize_tabular_data-0.1.0 → normalize_tabular_data-0.1.2}/src/normalize_tabular_data/ops.py

@@ -48,8 +48,17 @@ def _apply_date_normalize(df: pl.DataFrame, p: dict[str, Any]) -> pl.DataFrame:
     series = df.get_column(col)
     if series.dtype != pl.String:
         series = series.cast(pl.String)
-    # Datetime("ns"), unparseable -> null
-    return df.with_columns(date_parser.parse_series(series).alias(col))
+    # canonical UTC at second resolution: polars has no second-unit
+    # Datetime (ns/us/ms only, all of which print sub-second digits in
+    # every export), so the normalized column is the truncated
+    # `year-month-dayThh:mm:ss` string; fractional parts are dropped and
+    # unparseable values become null
+    return df.with_columns(
+        date_parser.parse_series(series)
+        .dt.truncate("1s")
+        .dt.to_string("%Y-%m-%dT%H:%M:%S")
+        .alias(col)
+    )
 
 
 def _apply_trim_collapse(df: pl.DataFrame, p: dict[str, Any]) -> pl.DataFrame:
@@ -224,6 +233,47 @@ RENAME_OP = Operation(
 PLAY_REGISTRY: dict[str, Operation] = {**OP_REGISTRY, RENAME_OP.key: RENAME_OP}
 
 
+def apply_script_steps(
+    steps: list[tuple[str, dict]],
+    pipeline: Pipeline,
+    op_log: list[tuple[str, Any]],
+    on_failure: Callable[[str], None],
+) -> bool:
+    """Apply a played script's steps to `pipeline`, all-or-nothing.
+
+    Each step is resolved against PLAY_REGISTRY, applied, and logged to
+    `op_log` (the same keys the interactive player records). On the first
+    step that is impossible for the currently loaded file the work done so
+    far is rolled back — `pipeline.applied` and `op_log` truncated to where
+    the script started and the redo stack cleared — and the failure reason
+    is passed to `on_failure`. Returns False when a step failed, in which
+    case `pipeline` is left exactly as it was before the call."""
+    started_applied = len(pipeline.applied)
+    started_log = len(op_log)
+
+    def give_up(reason: str) -> None:
+        del pipeline.applied[started_applied:]
+        pipeline.redo_stack.clear()
+        del op_log[started_log:]
+        on_failure(reason)
+
+    for index, (key, params) in enumerate(steps, 1):
+        op = PLAY_REGISTRY.get(key)
+        if op is None:
+            give_up(f"Step {index}: {key!r} is not a known operation")
+            return False
+        try:
+            pipeline.apply(op, params)
+            # the pipeline refolds lazily; fold now so an op-specific error
+            # (e.g. unparseable dates) rolls back this step too
+            pipeline.current()
+        except Exception as exc:
+            give_up(f"Step {index} of {len(steps)} ({op.title}) failed: {exc}")
+            return False
+        op_log.append((key, dict(params)))
+    return True
+
+
 # --- pipeline ---------------------------------------------------------------
 
 

normalize_tabular_data-0.1.0/src/normalize_tabular_data/__init__.py

@@ -1,18 +0,0 @@
-"""normalize-tabular-data: TUI for normalizing tabular data with polars."""
-
-__version__ = "0.1.0"
-
-
-def main() -> None:
-    try:
-        from normalize_tabular_data.app import NormalizeApp
-    except ImportError as exc:  # helpful message if an optional engine is missing
-        import sys
-
-        print(
-            f"normalize-tabular-data is missing a dependency ({exc}).\n"
-            "Reinstall with: uv tool install --force --reinstall normalize-tabular-data",
-            file=sys.stderr,
-        )
-        raise SystemExit(1)
-    NormalizeApp().run()