tkexcel_db.py ライブラリドキュメント

このドキュメントは、Pythonライブラリ tkexcel_db.py の機能、使用方法、および内部構造について技術的な説明を提供します。

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

tkexcel_db.py ライブラリは、Microsoft Excelファイルをリレーショナルデータベースのように扱うためのクラス tkExcelDB を提供します。特に、Excelシート内のデータをSQLのSELECT文に似た条件で検索し、抽出する機能に重点を置いています。

このライブラリは、openpyxl を利用してExcelファイルの読み書きを行い、pandas を利用してDataFrame形式でのデータ操作を可能にします。また、親クラスである tklib.tkexcel.tkExcel の機能を継承・拡張しており、Excelファイル操作の基本的な機能に加えて、条件に基づいた高度なデータ検索ロジックを提供することで、大量のデータが格納されたExcelファイルを効率的に扱うことを目的としています。

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

Excelファイルのオープン、クローズ、シートの選択。
指定された条件（例: "カラム名 == 値" や "カラム名 like '正規表現'") に基づくデータの検索。
検索結果から特定のカラムのデータを抽出。
抽出結果をリストや辞書、またはpandas DataFrameとして取得。

importする方法

このライブラリは、通常、以下のように tkExcelDB クラスをインポートして使用します。

from tkexcel_db import tkExcelDB

# Excelファイルを開く例
# db = tkExcelDB(path='your_excel_file.xlsx', table_name='Sheet1', mode='r')
# または新規作成
# db = tkExcelDB(path='new_excel_file.xlsx', mode='w')

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

tkexcel_db.py を使用するには、以下の非標準ライブラリが必要です。

openpyxl: Excel 2010 xlsx/xlsm/xltx/xltm ファイルの読み書きを行うためのライブラリです。
```
pip install openpyxl
```
pandas: データ解析と操作のための強力なライブラリです。特にDataFrameの作成に使用されます。
```
pip install pandas
```
tklib: このライブラリは tklib.tkutils および tklib.tkexcel に依存しています。これらは一般的に pip で直接インストールされるパッケージではなく、同じプロジェクト内にあるか、別途提供されるローカルライブラリである可能性が高いです。通常、この tkexcel_db.py が属するプロジェクトの一部として提供されます。

importできる変数と関数

tkexcel_db.py ライブラリは、主に tkExcelDB クラスを提供します。このクラスのインスタンスを作成し、そのメソッドを呼び出すことで機能を利用します。直接インポートできるグローバル変数や関数は定義されていません。

クラス

`class tkExcelDB(tkExcel)`

tklib.tkexcel.tkExcel クラスを継承し、Excelファイルをデータベースのように扱うための機能を提供します。

メソッド

__init__(self, path=None, mode='r', table_name=None, password=None, allow_no_password=False, tmp_file=None, OpenFile=True, CloseFile=False, try_text_file=False, data_only=True, description='', split_from=1, **args)
- 動作: tkExcelDB オブジェクトを初期化します。Excelファイルのパスを指定し、データベースのように操作する準備をします。新規作成（mode='w') の場合は新しいワークブックが作成され、既存ファイルを開く場合は指定された table_name に合致するシートが検索されます。
- 引数:
  - path (str, optional): 操作するExcelファイルのパス。デフォルトは None。
  - mode (str, optional): ファイルのオープンモード。'r' (読み込み), 'w' (書き込み/新規作成)。デフォルトは 'r'。
  - table_name (str, optional): データベースのテーブルとして扱うシートの名前。正規表現で指定可能です。デフォルトは None。
  - password (str, optional): 暗号化されたExcelファイルのパスワード。デフォルトは None。
  - allow_no_password (bool, optional): パスワードなしのファイルも許可するかどうか。デフォルトは False。
  - tmp_file (str, optional): 一時ファイルとして使用するパス。デフォルトは None。
  - OpenFile (bool, optional): 初期化時にファイルをオープンするかどうか。デフォルトは True。
  - CloseFile (bool, optional): 初期化後にファイルをクローズするかどうか。デフォルトは False。
  - try_text_file (bool, optional): テキストファイルとして開くことを試みるか。デフォルトは False。
  - data_only (bool, optional): セルの値を取得する際に、計算式ではなく結果値を取得するかどうか。デフォルトは True。
  - description (str, optional): オブジェクトの簡単な説明。デフォルトは ''。
  - split_from (int, optional): データの読み込みを開始する行番号（1-based）。デフォルトは 1。
  - **args: 親クラス tkExcel のコンストラクタに渡される追加のキーワード引数。
- 戻り値: なし。
__del__(self)
- 動作: オブジェクトが破棄される際に呼び出されるデストラクタ。現在の実装では特に処理はありません。
- 引数: なし。
- 戻り値: なし。
__str__(self)
- 動作: オブジェクトの文字列表現を返します。親クラス tkExcel の ClassPath メソッドを呼び出します。
- 引数: なし。
- 戻り値: str - オブジェクトのクラスパス。
print_inf(self)
- 動作: 現在の tkExcelDB インスタンスに関する詳細情報（description、ファイルパス、モード、ワークシートの数と名前、現在のワークシートなど）を標準出力に表示します。
- 引数: なし。
- 戻り値: なし。
use_dataframe(self, labels, data_list)
- 動作: 指定されたカラムラベルとデータリストから pandas.DataFrame を作成し、それをインスタンスの dataframe 属性に設定します。
- 引数:
  - labels (list of str): DataFrameのカラム名となる文字列のリスト。
  - data_list (list of list): DataFrameのデータとなる行のリスト。各要素はリスト（行データ）である必要があります。
- 戻り値: pandas.DataFrame - 作成されたDataFrameオブジェクト。
add_to_list(self, irow, itargets, labels, data_list, data_dict)
- 動作: 指定された行 irow から、itargets で指定された列番号に対応するセルの値を取得し、それを data_list (リスト) と data_dict (辞書) に追加します。data_dict のキーには labels が使用されます。
- 引数:
  - irow (int): 値を読み取る対象の行番号 (1-based)。
  - itargets (list of int): 読み取る列番号のリスト (1-based)。
  - labels (list of str): itargets に対応するカラム名のリスト。data_dict のキーとして使用されます。
  - data_list (list): 抽出された値を追加するリスト（参照渡し）。
  - data_dict (dict): 抽出された値を追加する辞書（参照渡し）。
- 戻り値: なし。
evaluate(self, var1_pos, operator, str1, str2, args, irow='', def_val='', is_print=False)
- 動作: 2つの値 str1 と str2 を指定された演算子 operator で比較し、その真偽値を返します。数値比較、文字列比較、および正規表現によるマッチングをサポートします。
- 引数:
  - var1_pos (str): 変数1の位置を示す文字列（現在のロジックでは 'h' のみが想定されています）。
  - operator (str): 比較演算子。以下のいずれかです。
    - 数値比較: '==', '!=', '<', '<=', '>', '>='
    - 文字列比較: 'eq' (等しい), 'neq' (等しくない)
    - 正規表現: 'like' (マッチ), 'not like' (マッチしない)
  - str1 (str): 比較対象の1つ目の値。
  - str2 (str): 比較対象の2つ目の値。
  - args (list): 現在の評価ロジックでは直接使用されていない、将来的な拡張のための追加引数。
  - irow (str, optional): エラーメッセージ表示用の行番号。デフォルトは ''。
  - def_val (str, optional): デフォルト値（現在の評価ロジックでは直接使用されていません）。デフォルトは ''。
  - is_print (bool, optional): エラーメッセージを標準出力に出力するかどうか。デフォルトは False。
- 戻り値: bool または None - 比較結果の真偽値。演算子が無効である場合や数値変換に失敗した場合は None を返します。
select_irows(self, condition, key_column_org=1, key_row_org=1, target_row_org=2, is_print=False, first_hit_only=False)
- 動作: SQLのWHERE句に似た condition 文字列に基づいて、Excelシート内で条件に合致する行の番号を検索し、そのリストを返します。複数の条件を and や or で連結できます。
- 引数:
  - condition (str): 検索条件を示す文字列（例: "ID == 100 and Name like '山田.*'", "Status eq '完了' or Priority == 1"）。
  - key_column_org (int, optional): カラムラベルを検索する開始列番号 (1-based)。デフォルトは 1。
  - key_row_org (int, optional): カラムラベルが格納されている行番号 (1-based)。デフォルトは 1。
  - target_row_org (int, optional): データの検索を開始する行番号 (1-based)。デフォルトは 2。
  - is_print (bool, optional): 検索過程の情報を標準出力に出力するかどうか。デフォルトは False。
  - first_hit_only (bool, optional): 最初に見つかった行のみを返すか、条件に合致する全ての行を返すか。デフォルトは False。
- 戻り値: list または int または None -
  - first_hit_only=False の場合: 条件に合致する行番号のリスト。
  - first_hit_only=True の場合: 最初に見つかった行番号。
  - 条件に合致する行が見つからなかった場合: None (first_hit_only=True の場合) または空のリスト (first_hit_only=False の場合)。
select(self, condition, target_labels=None, key_column_org=1, target_row_org=2, key_row_org=1, ret_type='list', is_print=False)
- 動作: 指定された条件 condition に基づいて、Excelシートからデータを検索し、target_labels で指定されたカラムのデータを抽出して返します。戻り値の形式を ret_type で選択できます。
- 引数:
  - condition (str): 検索条件を示す文字列。select_irows メソッドと同じ形式です。
  - target_labels (list of str, optional): 抽出したいカラムのラベル名リスト。None の場合、全カラムを対象とします。デフォルトは None。
  - key_column_org (int, optional): カラムラベルを検索する開始列番号 (1-based)。デフォルトは 1。
  - target_row_org (int, optional): データの検索を開始する行番号 (1-based)。デフォルトは 2。
  - key_row_org (int, optional): カラムラベルが格納されている行番号 (1-based)。デフォルトは 1。
  - ret_type (str, optional): 戻り値の形式。以下のいずれかです。デフォルトは 'list'。
    - 'list': 各行がリストであるリスト [ [val1, val2], [val3, val4] ] を返します。
    - 'dict': 各行が辞書であるリスト [ {'label1': val1, 'label2': val2}, {'label1': val3, 'label2': val4} ] を返します。
    - 'all': ラベル、リスト形式のデータ、辞書形式のデータ、および合致した行番号を含む辞書 { "labels": [...], "list": [...], "dict": [...], "irows": [...] } を返します。
    - 'irows': ラベルのリストと、条件に合致した行番号のリストを返します。
  - is_print (bool, optional): 検索過程の情報を標準出力に出力するかどうか。デフォルトは False。
- 戻り値:
  - tuple (labels, res): ret_type が 'list' または 'dict' の場合。labels はカラム名のリスト、res は抽出されたデータ。
  - dict: ret_type が 'all' の場合。
  - tuple (labels, irows): ret_type が 'irows' の場合。

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

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

tkexcel_db.py ライブラリ ドキュメント