# tkutils マニュアル

## 1. 役割

`tkutils` は、他パッケージから共有できる小さな汎用機能をまとめます。

- 数値文字列の安全な変換: `pfloat`, `pint`
- stdout/stderrのteeとredirect: `Tee`, `redirect_output`
- minimum-matrix形式の表読込: `read_data_table` と関連dataclass

## 2. 推奨import

```python
from tkutils import (
    pfloat,
    pint,
    Tee,
    redirect_output,
    DataTable,
    read_data_table,
)
```

## 3. 数値変換

```python
from tkutils import pfloat, pint

x = pfloat("1.23E-4")
n = pint("12")
```

空文字、変換不能文字列、全角・装置出力表記等に対する正確なfallback規則はAPIリファレンスと実装を参照してください。科学計算の入力検証で、変換失敗を黙って有効値とみなさないようにしてください。

## 4. 表読込

```python
from tkutils import read_data_table

table = read_data_table(
    "data.xlsx",
    header_row=5,
    first_column=2,
    sheet=0,
    force_numeric=True,
)

print(table.labels)
print(table.columns)
print(table.nrows, table.ncolumns)
```

`header_row` と `first_column` は**1始まり**です。

minimum-matrix規則:

1. `header_row` の `first_column` から最初の空header直前までを列範囲とする。
2. データはheader直下から開始する。
3. 第1データ列が空になった行の直前で終了する。
4. 表範囲外の非空cellを `metadata` として保存する。

対応形式は `.xlsx`, `.xlsm`, `.csv`, `.txt` です。

## 5. `DataTable`

主要field:

| field | 内容 |
|---|---|
| `labels` | header label list |
| `columns` | 列ごとのdata list |
| `metadata` | `MetadataCell` list |
| `data_range` | 1始まりcell範囲 |
| `source` | path、sheet、encoding、delimiter |
| `raw_rows` | 読み込んだ生row |

列検索:

```python
label, values = table.find_column("temperature", ignore_case=True)
label, values = table.find_column(r"^T", regex=True)
label, values = table.find_column(0)  # index
```

metadata辞書:

```python
meta = table.metadata_dict()
```

## 6. redirect / tee

```python
from tkutils import redirect_output

with redirect_output("run.log", tee=True):
    print("console and file")
```

`Tee` は複数streamへ同じ出力を書きます。長時間処理ではclose/flushと例外時の復元を確実にするため、context managerである `redirect_output()` を優先します。

## 7. 依存関係

- CSV/TXT: 標準ライブラリ
- Excel: `openpyxl`

## 8. 生成AI向けコード生成ルール

1. Excelのrow/column指定は1始まりとして扱う。
2. `DataTable.columns` はrow-majorではなく列listであることを確認する。
3. 列名選択には `find_column()` を使い、indexを固定しすぎない。
4. metadataは表外の全非空cellであり、同名キーの衝突可能性を考慮する。
5. stdoutの手動差替えより `redirect_output()` context managerを使う。
6. 数値変換失敗時のdefaultを、測定値として無条件に採用しない。