Metadata-Version: 2.4
Name: tha-dt-runner
Version: 0.1.3
Summary: A Tabular Helper API library that auto-detects date string formats and reformats them across 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
Classifier: Typing :: Typed
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 ThaDT

formatter = ThaDT()

# Single value — auto-detects input format
formatter.format_date("2024-04-15", "%m/%d")             # "04/15"
formatter.format_date("04/15/2024", "%Y-%m-%d")          # "2024-04-15"
formatter.format_date("April 15, 2024", "%m/%d/%y")      # "04/15/24"
formatter.format_date("2024-04-15T13:30:00Z", "%m/%d")   # "04/15"

# 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 = formatter.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-15T13:30:00.000Z` | ISO 8601 datetime with milliseconds |
| `2024-04-15T13:30:00Z` | ISO 8601 datetime |
| `2024-04-15T13:30:00` | ISO 8601 datetime (no Z) |
| `2024-04-15` | ISO 8601 date |
| `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

### `ThaDT`

```python
ThaDT()
```

### `formatter.now()`

```python
ThaDT.now(fmt="%Y-%m-%dT%H:%M:%S") -> str
```

Returns the current local timestamp formatted as *fmt* (a [strftime](https://strftime.org/) string). Defaults to ISO 8601. Also callable as `ThaDT.now()` without instantiation.

```python
ThaDT.now()                  # "2026-05-16T09:31:00"
ThaDT.now("%m/%d/%Y")        # "05/16/2026"
ThaDT.now("%Y-%m-%d %H:%M")  # "2026-05-16 09:31"
```

### `formatter.format_date()`

```python
formatter.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. Also callable as `ThaDT.format_date(value, to_fmt)` without instantiation.

### `formatter.format_date_rows()`

```python
formatter.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]
```

Results are also stored in `formatter.rows`.

#### `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 ThaDT

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

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

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

## License

MIT
