# tkutils 生成AI投入用コンテキスト

> このファイルは `tkutils` を使うコード生成のため、マニュアルとAPIリファレンスを1ファイルへ統合したものです。API名・引数は下記APIリファレンスを優先し、存在しないAPIを推測で作らないでください。ソースコードが同時に与えられた場合はソースコードを最優先します。

---

# 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を、測定値として無条件に採用しない。


---

# tkutils APIリファレンス

> 対象ソース: `tklib2.zip`（解析日: 2026-08-03）。この文書はソースコードを静的解析して生成しています。

## APIの読み方

- **パッケージ公開API**は、原則としてトップレベルの `__all__` に含まれる名前です。
- **モジュールAPI**には、公開名（先頭が `_` でない関数・クラス・メソッド）を列挙しています。
- docstringがないAPIでは、シグネチャとソースパスを一次情報として扱ってください。
- 生成AIは、この文書に存在しない引数・戻り値・メソッドを推測で追加しないでください。

## パッケージ公開API

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

| 名前 | 推奨用途 |
|---|---|
| `pfloat` | トップレベルから安定してimportできる公開API |
| `pint` | トップレベルから安定してimportできる公開API |
| `Tee` | トップレベルから安定してimportできる公開API |
| `redirect_output` | トップレベルから安定してimportできる公開API |
| `CellRange` | トップレベルから安定してimportできる公開API |
| `DataSource` | トップレベルから安定してimportできる公開API |
| `MetadataCell` | トップレベルから安定してimportできる公開API |
| `DataTable` | トップレベルから安定してimportできる公開API |
| `read_data_table` | トップレベルから安定してimportできる公開API |

## モジュール一覧

| モジュール | ソース | 関数 | クラス |
|---|---|---:|---:|
| `tkutils` | `tkutils/__init__.py` | 0 | 0 |
| `tkutils.tkconvert` | `tkutils/tkconvert.py` | 2 | 0 |
| `tkutils.tkdata` | `tkutils/tkdata.py` | 1 | 4 |
| `tkutils.tkredirect` | `tkutils/tkredirect.py` | 1 | 1 |

## `tkutils`

ソース: `tkutils/__init__.py`

_このモジュールには静的解析で検出された公開関数・クラス・定数はありません。_

## `tkutils.tkconvert`

ソース: `tkutils/tkconvert.py`

### function `pfloat`

```python
def pfloat(value, defval = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

### function `pint`

```python
def pint(value, defval = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkutils.tkdata`

ソース: `tkutils/tkdata.py`

### class `CellRange`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**データクラス相当の初期化フィールド**

```python
CellRange(header_row: int, first_column: int, end_row: int, end_column: int)
```

**フィールド**

| 名前 | 型 | 既定値 |
|---|---|---|
| `header_row` | `int` | `必須` |
| `first_column` | `int` | `必須` |
| `end_row` | `int` | `必須` |
| `end_column` | `int` | `必須` |

**メソッド／プロパティ**

#### property `CellRange.nrows`

```python
def nrows(self) -> int
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### property `CellRange.ncolumns`

```python
def ncolumns(self) -> int
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

### class `DataSource`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**データクラス相当の初期化フィールド**

```python
DataSource(path: Path, extension: str, sheet_name: str | None = None, encoding: str | None = None, delimiter: str | None = None)
```

**フィールド**

| 名前 | 型 | 既定値 |
|---|---|---|
| `path` | `Path` | `必須` |
| `extension` | `str` | `必須` |
| `sheet_name` | `str | None` | `None` |
| `encoding` | `str | None` | `None` |
| `delimiter` | `str | None` | `None` |

### class `MetadataCell`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**データクラス相当の初期化フィールド**

```python
MetadataCell(row: int, column: int, value: Any, region: str)
```

**フィールド**

| 名前 | 型 | 既定値 |
|---|---|---|
| `row` | `int` | `必須` |
| `column` | `int` | `必須` |
| `value` | `Any` | `必須` |
| `region` | `str` | `必須` |

### class `DataTable`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**データクラス相当の初期化フィールド**

```python
DataTable(labels: list[Any], columns: list[list[Any]], metadata: list[MetadataCell], data_range: CellRange, source: DataSource, raw_rows: list[list[Any]])
```

**フィールド**

| 名前 | 型 | 既定値 |
|---|---|---|
| `labels` | `list[Any]` | `必須` |
| `columns` | `list[list[Any]]` | `必須` |
| `metadata` | `list[MetadataCell]` | `必須` |
| `data_range` | `CellRange` | `必須` |
| `source` | `DataSource` | `必須` |
| `raw_rows` | `list[list[Any]]` | `必須` |

**メソッド／プロパティ**

#### method `DataTable.find_column`

```python
def find_column(self, selector: str | int, *, ignore_case: bool = True, regex: bool = False) -> tuple[Any | None, list[Any] | None]
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `DataTable.metadata_dict`

```python
def metadata_dict(self) -> dict[str, Any]
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### property `DataTable.nrows`

```python
def nrows(self) -> int
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### property `DataTable.ncolumns`

```python
def ncolumns(self) -> int
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

### function `read_data_table`

```python
def read_data_table(path: str | Path, *, header_row: int = 1, first_column: int = 1, force_numeric: bool = True, sheet: str | int | None = None, data_only: bool = True, encoding: str | None = None, delimiter: str | None = None) -> DataTable
```

.xlsx/.xlsm/.csv/.txtからminimum-matrix形式の表を読む。

- header_row、first_columnは1始まり。
- ヘッダーはfirst_columnから最初の空セル直前まで。
- データはヘッダー直下から開始。
- 第1データ列が空になった行の直前で終了。
- 表範囲外の全非空セルをmetadataとして返す。

## `tkutils.tkredirect`

ソース: `tkutils/tkredirect.py`

### class `Tee`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
Tee(*streams)
```

**メソッド／プロパティ**

#### method `Tee.write`

```python
def write(self, text)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `Tee.flush`

```python
def flush(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

### function `redirect_output`

```python
def redirect_output(logfile, mode = 'w', encoding = 'utf-8', include_stderr = True)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_