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

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規則:

header_row の first_column から最初の空header直前までを列範囲とする。
データはheader直下から開始する。
第1データ列が空になった行の直前で終了する。
表範囲外の非空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向けコード生成ルール

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

tkutils APIリファレンス

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

APIの読み方

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

パッケージ公開API

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`

def pfloat(value, defval = None)

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

function `pint`

def pint(value, defval = None)

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

`tkutils.tkdata`

ソース: tkutils/tkdata.py

class `CellRange`

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

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

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`

def nrows(self) -> int

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

property `CellRange.ncolumns`

def ncolumns(self) -> int

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

class `DataSource`

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

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

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`
`encoding`	`str	None`
`delimiter`	`str	None`

class `MetadataCell`

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

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

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

フィールド

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

class `DataTable`

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

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

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`

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`

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

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

property `DataTable.nrows`

def nrows(self) -> int

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

property `DataTable.ncolumns`

def ncolumns(self) -> int

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

function `read_data_table`

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はありません。シグネチャと実装を参照してください。

コンストラクタ

Tee(*streams)

メソッド／プロパティ

method `Tee.write`

def write(self, text)

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

method `Tee.flush`

def flush(self)

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

function `redirect_output`

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

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

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

tkutils マニュアル

1. 役割

2. 推奨import

3. 数値変換

4. 表読込

5. DataTable

6. redirect / tee

7. 依存関係

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

tkutils APIリファレンス

APIの読み方

パッケージ公開API

モジュール一覧

tkutils

tkutils.tkconvert

function pfloat

function pint

tkutils.tkdata

class CellRange

property CellRange.nrows

property CellRange.ncolumns

class DataSource

class MetadataCell

class DataTable

method DataTable.find_column

method DataTable.metadata_dict

property DataTable.nrows

property DataTable.ncolumns

function read_data_table

tkutils.tkredirect

class Tee

method Tee.write

method Tee.flush

function redirect_output

5. `DataTable`

`tkutils`

`tkutils.tkconvert`

function `pfloat`

function `pint`

`tkutils.tkdata`

class `CellRange`

property `CellRange.nrows`

property `CellRange.ncolumns`

class `DataSource`

class `MetadataCell`

class `DataTable`

method `DataTable.find_column`

method `DataTable.metadata_dict`

property `DataTable.nrows`

property `DataTable.ncolumns`

function `read_data_table`

`tkutils.tkredirect`

class `Tee`

method `Tee.write`

method `Tee.flush`

function `redirect_output`