tkdatafile.py ライブラリ技術ドキュメント

ライブラリの機能や目的

tkdatafile.py は、tklib ライブラリの一部として提供されるデータファイル操作のためのPythonライブラリです。これは主に、ラベルとそれに紐づくデータ配列を持つ構造化されたテキストデータを扱うことを目的としています。基底クラスである tkFile の機能を拡張し、データの検索、取得、変換機能を提供します。

主な機能は以下の通りです。

データ格納: labelarray (ラベルのリスト) と datalistarray (データ配列のリスト) を内部に保持し、構造化されたデータを取り扱います。
ラベル/インデックス検索: 正規表現または数値インデックスを使用して、特定のデータセットのラベルインデックスを効率的に検索します。この際、空白や括弧の違いを吸収し、大文字小文字を無視した検索も可能です。
データ配列の取得: 検索したラベルインデックスに基づいて、対応するデータ配列とそのラベルをペアで取得します。
データ型変換: 取得したデータ配列の各要素を、float や int などの指定された型に一括で変換する機能を提供します。
複数データの一括読み込み: 複数のラベルやインデックスに対応するデータセットを一度に取得できます。

このライブラリは、実験データ、設定ファイル、ログファイルなど、特定のヘッダー（ラベル）の下に数値データが並ぶ形式のファイルをプログラム的に解析し、必要なデータ要素を柔軟に抽出する場面で特に有用です。

importする方法

tkdatafile.py を他のPythonプログラムから利用するには、tkDataFile クラスをインポートします。

from tkdatafile import tkDataFile

必要な非標準ライブラリとインストール方法

このライブラリは、tklib というカスタムライブラリに依存しています。tklib は標準ライブラリではないため、別途インストールが必要です。

現在、tklib のインストール方法は明示されていませんが、一般的には pip を使ってインストールできる形式で提供されていることが多いです。もしtklibがPyPIに登録されていれば、以下のコマンドでインストールできます。

pip install tklib

もし tklib がローカルファイルまたは特定のバージョン管理システムからインストールする必要がある場合は、その指示に従ってください。tkdatafile.py と同じディレクトリ、またはPythonの検索パスが通っているディレクトリに tklib パッケージが配置されている必要があります。

tklib の内部モジュールである tklib.tkutils、tklib.tkfile、tklib.tkinifile、tklib.tkre がこのライブラリで使用されています。

importできる変数と関数

tkdatafile.py ライブラリは、tkDataFile クラスを主要なインターフェースとして提供します。直接インポートできる変数はありません。

クラス

`tkDataFile`

tklib.tkfile.tkFile を継承するデータファイル操作クラスです。内部的に self.labelarray と self.datalistarray というリストを保持し、それぞれデータファイルのラベル（ヘッダー）とそれに対応するデータ配列を格納します。

メソッド:

__init__(self, path=None, mode='r', OpenFile=True, **args)
- 動作: tkDataFile オブジェクトを初期化します。基底クラス tkFile のコンストラクタを呼び出し、labelarray と datalistarray を空のリストとして初期化します。
- 引数:
  - path (str, optional): 扱うファイルのパス。デフォルトは None。
  - mode (str, optional): ファイルを開くモード（例: 'r' 読み込み、'w' 書き込み）。デフォルトは 'r'。
  - OpenFile (bool, optional): オブジェクト初期化時にファイルを開くかどうか。デフォルトは True。
  - **args: tkFile のコンストラクタに渡される追加のキーワード引数。
- 戻り値: なし
__del__(self)
- 動作: オブジェクトが破棄される際に呼び出されるデストラクタです。開いているファイルがあれば閉じ、基底クラスのデストラクタを呼び出します。
- 引数: なし
- 戻り値: なし
__str__(self)
- 動作: オブジェクトの文字列表現を返します。
- 引数: なし
- 戻り値: str。クラスのパスを示す文字列。
sort(self, lists)
- 動作: 入力されたリストのリストをソートします。tklib.tkutils.sort_lists 関数へのラッパーです。
- 引数:
  - lists (list of list): ソートする対象のリストのリスト。
- 戻り値: list of list。ソートされたリストのリスト。
find_label_index(self, regexp, flag=None, flags='')
- 動作: self.labelarray に格納されているラベルの中から、指定された正規表現 regexp または直接インデックス（整数）に一致するラベルのインデックスを検索します。このメソッドは、検索時に空白文字や括弧 []() の違いを吸収し、flags='i' を指定することで大文字小文字を無視した検索も可能です。内部で re モジュールと tkre.Search を利用します。
- 引数:
  - regexp (str or int): 検索する正規表現文字列、または直接指定するインデックス（整数）。
  - flag (int, optional): re モジュールで使用されるフラグ（例: re.IGNORECASE）。flags 引数の古い形式であり、非推奨です。
  - flags (str or int, optional): re モジュールで使用されるフラグ。文字列 'i' を指定すると re.IGNORECASE と同等に扱われます。
- 戻り値: int。一致したラベルのインデックス。見つからない場合は None。
find_data_array(self, regexp, flag=None, flags='', convert_type=None, def_val=None)
- 動作: find_label_index メソッドを使ってラベルのインデックスを特定し、そのインデックスに対応するラベル (self.labelarray から) とデータ配列 (self.datalistarray から) を返します。convert_type が指定された場合、データ配列の各要素をその型に変換します（float や int など）。変換には tklib.tkutils.pfloat や tklib.tkutils.pint が使用されます。
- 引数:
  - regexp (str or int): 検索する正規表現文字列、または直接指定するインデックス（整数）。
  - flag (int, optional): find_label_index に渡される re フラグ。
  - flags (str or int, optional): find_label_index に渡される re フラグ。
  - convert_type (type, optional): データの要素を変換する型（例: float, int）。変換しない場合は None。
  - def_val (any, optional): 変換に失敗した場合に使用するデフォルト値。現在の実装では convert_type が指定された場合、元の値をそのまま返すため、この引数は実質的に影響しない可能性があります。
- 戻り値: tuple。(label, data_array) の形式。label は見つかったラベル（str）、data_array は対応するデータリスト（list）。ラベルが見つからない場合は (None, None)。
FindLabelIndex(self, regexp, flag=None, flags='')
- 動作: find_label_index メソッドのエイリアス（別名）です。
- 引数: find_label_index と同じ。
- 戻り値: find_label_index と同じ。
FindDataArray(self, regexp, flag=None, flags='')
- 動作: find_data_array メソッドのエイリアス（別名）です。
- 引数: find_data_array と同じ。
- 戻り値: find_data_array と同じ。
read_data(self, idata=[], flags='', convert_type=None, def_val=None, is_print=True)
- 動作: 複数のインデックスまたは正規表現のリスト idata に基づいて、複数のラベルと対応するデータリストをまとめて読み込みます。リストの各要素について find_data_array を呼び出し、結果をリストに集約して返します。
- 引数:
  - idata (list of str or int, optional): 取得したいラベルの正規表現またはインデックスのリスト。デフォルトは空リスト。
  - flags (str or int, optional): find_data_array に渡される re フラグ。
  - convert_type (type, optional): データの要素を変換する型。find_data_array に渡される。
  - def_val (any, optional): 変換失敗時のデフォルト値。find_data_array に渡される。
  - is_print (bool, optional): 現在のコードではこの引数は使用されていません。デフォルトは True。
- 戻り値: tuple。(labels, data_list) の形式。labels は見つかったラベルのリスト（list of str）、data_list は対応するデータリストのリスト（list of list）。

main scriptとして実行したときの動作

tkdatafile.py のソースコードには、if __name__ == '__main__': ブロックが存在しません。したがって、このファイルを直接Pythonインタプリタで実行しても、特別なスクリプトとしての動作は行われません。通常、ライブラリファイルとして他のプログラムからインポートされ、その機能が利用されることを想定しています。