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

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

tkcsv.py は、CSV (Comma Separated Values) ファイルの読み書きを容易にするためのPythonライブラリです。特に、数値データの抽出や特定のフォーマットでのCSVファイル出力に特化しています。

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

CSVデータ書き込み: 特定のヘッダ ('x', 'y(raw)', 'y(smooth)') を持つCSVファイルにデータを書き出す機能を提供します。
CSVデータ読み込み: CSVファイルからヘッダ行（ラベル）とデータ行を読み込み、データ行は自動的に数値型（浮動小数点数）に変換して行列形式のデータとして取得する機能を提供します。
ファイル操作の抽象化: tklib.tkdatafile.tkDataFile クラスを継承しており、基本的なファイルパス管理、モード指定、開閉処理などのファイル操作基盤の上にCSV固有の処理を構築しています。

このライブラリは、生の csv モジュールを直接使用するよりも、特定のデータ構造（ヘッダと数値列）を扱いやすくし、CSVから行列形式のデータを抽出する際の型変換を自動化することで、開発者の手間を軽減することを目的としています。

importする方法

tkcsv.py ライブラリは、以下の方法で他のPythonプログラムからインポートできます。

ライブラリ全体をインポートする場合:
```
import tkcsv
```
特定の関数やクラスのみをインポートする場合:
```
from tkcsv import savecsv, tkCSV
```

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

tkcsv.py は、tklib というPythonパッケージに依存しています。具体的には、以下のモジュールとそこから提供される関数・クラスが必要です。

tklib.tkutils: terminate, pfloat, pint
tklib.tksci.tkmatrix: make_matrix1
tklib.tkdatafile: tkDataFile

これらのモジュールは、通常、tkcsv.py と同じプロジェクト内で提供されるか、Pythonの検索パス上に配置されている必要があります。もし tklib パッケージが pip でインストール可能な場合は、以下のコマンドでインストールできます。

pip install tklib

ただし、tklib は一般的なPyPIライブラリではない可能性があり、このライブラリを使用する環境に個別に配置する必要があるかもしれません。

importできる変数と関数

tkcsv.py をインポートした際に、外部から利用できる関数とクラスは以下の通りです。

関数

savecsv(outfile, x, y, ys)
- 動作: 指定されたパスにCSV形式でデータを書き込みます。出力ファイルには、ヘッダとして ('x', 'y(raw)', 'y(smooth)') が設定され、その後に x、y、ys の各要素が対応する列に書き込まれます。ファイル書き込み中にエラーが発生した場合は、コンソールにエラーメッセージを表示します。
- 引数:
  - outfile (str): 出力するCSVファイルのパス。
  - x (list または tuple): x 軸のデータを含むリストまたはタプル。
  - y (list または tuple): 生の y データを含むリストまたはタプル。
  - ys (list または tuple): スムーズ化された y データを含むリストまたはタプル。
- 戻り値: なし。

クラス

tkCSV(tkDataFile)
- tklib.tkdatafile.tkDataFile を継承した、CSVファイル操作のためのクラスです。
- コンストラクタ: __init__(self, path = None, mode = 'r', OpenFile = 1, data_only = True, **args)
  - 動作: tkCSV オブジェクトを初期化します。ファイルパスとモードを設定し、OpenFile が 1 の場合は指定されたファイルを自動的に開きます。**args は、親クラス tkDataFile のコンストラクタに渡されます。
  - 引数:
    - path (str, optional): 操作対象のCSVファイルのパス。デフォルトは None。
    - mode (str, optional): ファイルを開くモード（例: 'r' (読み込み), 'w' (書き込み)）。デフォルトは 'r'。
    - OpenFile (int, optional): オブジェクト初期化時にファイルを自動で開くかどうか。1 で開きます。デフォルトは 1。
    - data_only (bool, optional): 親クラス tkDataFile のコンストラクタに渡される引数。デフォルトは True。
    - **args: 親クラス tkDataFile のコンストラクタに渡される追加のキーワード引数。
  - 戻り値: なし。
- __del__(self)
  - 動作: オブジェクトが破棄される際に、開いているファイルを確実に閉じます。
  - 引数: なし。
  - 戻り値: なし。
- __str__(self)
  - 動作: tkCSV オブジェクトの文字列表現を返します。親クラス tkDataFile の ClassPath() メソッドを呼び出して、クラスの完全パスを返します。
  - 引数: なし。
  - 戻り値: クラスのパスを示す文字列。
- Read_minimum_matrix(self, close_fp = False, delimiter = ',', force_numeric = True)
  - 動作: 指定されたCSVファイルを開き、ヘッダ行とデータ行を読み込みます。ヘッダ行は文字列のリスト (labels) として、データ行は列ごとの数値リストのリスト (datalist) として返されます。force_numeric が True の場合、データセルの値は tklib.tkutils.pfloat を使用して浮動小数点数に変換されます。変換できない場合はデフォルト値（0.0 または元の文字列）が使用されます。
  - 引数:
    - close_fp (bool, optional): データ読み込み後にファイルを閉じるかどうか。デフォルトは False。
    - delimiter (str, optional): CSVファイルの区切り文字。デフォルトは ','。
    - force_numeric (bool, optional): データ列を強制的に数値（浮動小数点数）に変換するかどうか。False の場合、数値に変換できない値は元の文字列のまま保持されます。デフォルトは True。
  - 戻り値:
    - labels (list of str): CSVファイルのヘッダ行のラベルを含むリスト。
    - datalist (list of list of float or str): 列ごとのデータを含むリストのリスト。datalist[i] は i 番目の列のすべてのデータを格納します。force_numeric の設定により、要素は float または str になります。

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

tkcsv.py ソースコードには、if __name__ == '__main__': ブロックが存在しません。そのため、このファイルをPythonインタプリタで直接実行した場合でも、特別な処理は行われません。

動作: 何も実行されません。
引数: なし。
出力: なし。