Metadata-Version: 2.4
Name: tha-dt-runner
Version: 0.1.0
Summary: Auto-detect date formats and reformat them — works on single values or CSV-style row dicts.
License: MIT
License-File: LICENSE
Keywords: conversion,csv,date,datetime,format
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# tha-dt-runner

[![CI](https://github.com/tha-guy-nate/tha-dt-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/tha-guy-nate/tha-dt-runner/actions/workflows/ci.yml)

A small Python library that auto-detects date string formats and reformats them — works on single values or CSV-style row dicts.

## Install

```bash
pip install tha-dt-runner
```

## Quick start

```python
from tha_dt_runner import format_date, format_date_rows

# Single value — auto-detects input format
format_date("2024-04-15", "%m/%d")       # "04/15"
format_date("04/15/2024", "%Y-%m-%d")    # "2024-04-15"
format_date("April 15, 2024", "%m/%d/%y") # "04/15/24"

# Row dicts — integrates with tha-csv-runner
rows = [
    {"Org BK": "school-001", "Start Date": "2024-08-15"},
    {"Org BK": "school-002", "Start Date": "08/16/2024"},
]

result = format_date_rows(rows, column="Start Date", to_fmt="%m/%d")
# [{"Org BK": "school-001", "Start Date": "08/15"}, ...]
```

## Auto-detected input formats

| Example | Format |
|---|---|
| `2024-04-15` | ISO 8601 |
| `20240415` | Compact ISO |
| `2024-04` | Year-month |
| `04/15/2024` | US MM/DD/YYYY |
| `04/15/24` | US MM/DD/YY |
| `04/15` | MM/DD (no year) |
| `April 15, 2024` | Long month name |
| `Apr 15, 2024` | Short month name |

## API

### `format_date`

```python
format_date(value: str, to_fmt: str) -> str
```

Auto-detects the format of *value* and returns it reformatted as *to_fmt* (a [strftime](https://strftime.org/) string). Raises `DateError` if the input cannot be parsed.

### `format_date_rows`

```python
format_date_rows(
    rows,                              # list of row dicts
    column,                            # column containing date strings
    to_fmt,                            # strftime output format
    *,
    out_column=None,                   # write to a new column instead of overwriting
    on_error="error",                  # "error" | "skip" | "blank"
    skip_statuses=["error", "warning"],# rows with these statuses are passed through
) -> list[dict]
```

#### `on_error`

| Value | Behaviour |
|---|---|
| `"error"` | `row status="error"`, `message=...`, output column set to `""` |
| `"skip"` | Row returned unchanged |
| `"blank"` | Output column set to `""`, row status untouched |

### Composing with `tha-csv-runner`

```python
from tha_csv_runner import ThaCSV
from tha_dt_runner import format_date_rows

runner = ThaCSV()
runner.read("Step 1 of 2", "input.csv", ["Org BK", "Start Date"])

runner.rows = format_date_rows(
    rows=runner.rows,
    column="Start Date",
    to_fmt="%m/%d",
)

runner.write("Step 2 of 2", "output.csv")
```

## License

MIT
