tkutils マニュアル

1. 役割

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

  • 数値文字列の安全な変換: pfloat, pint

  • stdout/stderrのteeとredirect: Tee, redirect_output

  • minimum-matrix形式の表読込: read_data_table と関連dataclass

2. 推奨import

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

3. 数値変換

from tkutils import pfloat, pint

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

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

4. 表読込

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

列検索:

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辞書:

meta = table.metadata_dict()

6. redirect / tee

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