tkexcel.py 技術ドキュメント
このドキュメントは、Pythonライブラリ tkexcel.py の技術的な側面について解説します。
ライブラリの機能や目的
tkexcel.py ライブラリは、Microsoft Excel (.xlsx, .xlsm) ファイル、CSVファイル、および一般的なテキストファイルを操作するための高レベルなインターフェースを提供します。openpyxl や msoffcrypto といった下位レベルのライブラリをラップすることで、開発者はより直感的かつ簡潔なコードでExcelファイルを扱うことができます。
主な機能:
Excelファイルの読み書きと作成: 新規Excelファイルの作成、既存ファイルの読み込み、データ追記（アペンド）、保存。
パスワード保護されたExcelファイルのサポート:
msoffcrypto-toolを使用して、パスワードで保護されたExcelファイルの復号と読み込み。CSV/テキストファイルの統合: CSVファイルや区切り文字で区切られたテキストファイルを、内部的にExcelワークブックとして読み込み、Excelファイルと同様の操作を可能にします。
シートとセルの操作: 特定のセルへの値の書き込み/読み込み、行/列の挿入/削除、シート名の変更、シートのコピー。
書式設定: セルのフォント（色、太字、斜体など）、塗りつぶし、罫線などのスタイル設定。
列の表示設定: 列幅の取得/設定、列の表示/非表示の切り替え。
データ構造の柔軟性: セルデータを行列、リスト、辞書の形式で取得する機能。
チャートの作成: スキャッターチャートの作成と、軸ラベル、タイトル、凡例、データ系列などの設定。
解決する課題:
tkexcel.py は、openpyxl などの低レベルなExcel操作ライブラリを直接使用する際の複雑さを軽減し、以下のような課題を解決します。
簡素化されたAPI: ファイルのオープン、読み書き、クローズといった一連の操作を、より少ないコードで実行できるよう抽象化します。
パスワード付きExcelのハンドリング: パスワード保護されたファイルを扱うための複雑な手順を内部で処理し、ユーザーは簡単な引数指定で利用できます。
多様なファイル形式への対応: Excelファイルだけでなく、CSVやテキストファイルを同じインターフェースで扱えるようにすることで、データ処理の柔軟性を高めます。
データの抽出と整理: Excelシートから特定の列や行のデータをリストや辞書形式で簡単に抽出できる機能を提供し、データ解析の前処理を効率化します。
importする方法
tkexcel.py ライブラリの主要なクラスである tkExcel を他のPythonプログラムで利用するには、以下のように tklib.tkexcel モジュールからインポートします。
from tklib.tkexcel import tkExcel
また、チャート機能を利用する場合は tkExcelChart もインポートします。
from tklib.tkexcel import tkExcel, tkExcelChart
必要な非標準ライブラリとインストール方法
tkexcel.py は、いくつかの非標準ライブラリに依存しています。これらのライブラリは pip コマンドを使用してインストールできます。
openpyxl: Microsoft Excel 2010 xlsx/xlsm/xltx/xltm ファイルを読み書きするためのライブラリです。
pip install openpyxl
chardet: 文字エンコーディングを検出するためのライブラリです。
tkexcel.pyではテキストファイルやCSVファイルのエンコーディングを自動判別するために使用されます。pip install chardet
msoffcrypto-tool: パスワードで保護されたOfficeファイルを復号化するためのライブラリです。
tkexcel.pyでは、パスワード付きExcelファイルの読み込みに使用されます。pip install msoffcrypto-tool
msoffcrypto-toolがインストールされていない場合、パスワード保護されたExcelファイルを開こうとするとエラーメッセージが表示され、プログラムが終了する可能性があります（ただし、allow_no_password=Trueかつパスワードが指定されていない場合はパスワードなしで開く試行が行われます）。
importできる変数と関数
tkexcel.py から直接インポートして利用できる主要なクラスは tkExcel と tkExcelChart です。いくつかの補助関数も定義されていますが、これらは主に内部的に使用されます。
関数
convert_color(color)指定された色名をExcelのカラーコード（16進数文字列）に変換します。辞書に定義されていない色名や#始まりのコードはそのまま返されます。引数:
color(str): 変換したい色名（例: "red", "black", "FF0000"）。
戻り値:
str: Excelのカラーコード（例: "FF0000"）。
convert_linestyle(linestyle)線種名（例: "dashed"）をExcelの線種定数に変換します。引数:
linestyle(str): 変換したい線種名。
戻り値:
str: Excelの線種定数（例: "lgDash"）。
convert_size(s)ポイント (pt) 単位のサイズをEMU (English Metric Unit) に変換します。Excel内部ではサイズはEMUで管理されます。 1インチ = 914400 EMU、\(1 \text{ pt} = \frac{1}{72} \text{ inch}\) であるため、 \(1 \text{ pt} = \frac{1}{72} \cdot 914400 \text{ EMU} = 12700 \text{ EMU}\) となります。引数:
s(数値): ポイント単位のサイズ。
戻り値:
int: EMU単位に変換されたサイズ。
クラス
tkExcel_sheet(openpyxl.worksheet.worksheet.Worksheet)
openpyxl の Worksheet クラスを継承していますが、このクラスは tkExcel クラスの内部でワークシートオブジェクトをラップするために使用されます。ユーザーが直接インスタンス化して操作することは想定されていません。
tkExcelChart()
Excelシートにチャート（グラフ）を追加・設定するためのクラスです。
__init__(self, style = 'scatter')チャートオブジェクトを初期化します。引数:
style(str, optional): チャートのスタイル。現在のところ 'scatter' のみがサポートされています。デフォルトは 'scatter'。
戻り値: なし
add_chart(self, ws, position = "A1")ワークシートにチャートを追加します。引数:
ws(openpyxl.worksheet.worksheet.Worksheet): チャートを追加するワークシートオブジェクト。position(str, optional): チャートを配置する左上隅のセル位置（例: "A1"）。デフォルトは "A1"。
戻り値: なし
set_figsize(self, width, height)チャートのサイズ（幅と高さ）を設定します。引数:
width(数値): チャートの幅。height(数値): チャートの高さ。
戻り値: なし
set_title(self, title)チャートのタイトルを設定します。引数:
title(str): チャートのタイトル。
戻り値: なし
set_xlabel(self, label)X軸のラベルを設定します。引数:
label(str): X軸のラベル。
戻り値: なし
set_ylabel(self, label)Y軸のラベルを設定します。引数:
label(str): Y軸のラベル。
戻り値: なし
set_legend(self, style = '')凡例の表示スタイルを設定します。Noneを指定すると凡例を非表示にします。引数:
style(str or None, optional): 凡例のスタイル。デフォルトは ''（空文字列で、通常は凡例が表示されます）。Noneを指定すると凡例は表示されません。
戻り値: なし
add_plot(self, ws, xrange, yrange, title_from_data = False, title = None, width = None, color = "000000", linestyle = "-")チャートにデータ系列を追加します。引数:
ws(openpyxl.worksheet.worksheet.Worksheet): データが含まれるワークシートオブジェクト。xrange(tuple): X軸データの範囲 (min_col, min_row, max_row)。yrange(tuple): Y軸データの範囲 (min_col, min_row, max_row)。title_from_data(bool, optional): データからタイトルを取得するかどうか。デフォルトはFalse。title(str, optional): データ系列のタイトル。title_from_dataがFalseの場合に有効。width(数値, optional): データ系列の線の太さ（ポイント単位）。color(str, optional): データ系列の線の色（Excelカラーコード）。デフォルトは "000000" (黒)。linestyle(str, optional): データ系列の線種（例: "-", "dashed"）。デフォルトは "-"。
戻り値: なし
set_xlim(self, range)X軸の表示範囲を設定します。引数:
range(tuple): X軸の最小値と最大値のタプル (min_val, max_val)。
戻り値: なし
set_ylim(self, range)Y軸の表示範囲を設定します。引数:
range(tuple): Y軸の最小値と最大値のタプル (min_val, max_val)。
戻り値: なし
set_xgrid(self, style = None)X軸の主グリッド線の表示スタイルを設定します。引数:
style(object, optional): グリッド線のスタイルオブジェクト。Noneを指定するとデフォルトのスタイルになる場合があります。
戻り値: なし
set_ygrid(self, style = None)Y軸の主グリッド線の表示スタイルを設定します。引数:
style(object, optional): グリッド線のスタイルオブジェクト。Noneを指定するとデフォルトのスタイルになる場合があります。
戻り値: なし
set_xticks(self, style = "none")X軸の主目盛りの表示スタイルを設定します。引数:
style(str, optional): 目盛りのスタイル（例: "none"）。デフォルトは "none"。
戻り値: なし
set_xticks(self, style = "none")(※注: 同じメソッド名が2回定義されており、2番目は minorTickMark を設定する。これはコード上の誤りである可能性が高い。) X軸の副目盛りの表示スタイルを設定します。引数:
style(str, optional): 目盛りのスタイル（例: "none"）。デフォルトは "none"。
戻り値: なし
tkExcel(tkDataFile)
Excelファイル、CSVファイル、テキストファイルを操作するための主要なクラスです。tklib.tkdatafile.tkDataFile を継承しています。
__init__(self, path = None, mode = 'r', password = None, allow_no_password = False, tmp_file = None, OpenFile = True, CloseFile = False, try_text = False, data_only = True, keep_vbas = False, try_text_file = False, encoding = None, split_from = 1, IsPrint = False, **args)tkExcelオブジェクトを初期化し、指定されたファイルを開きます。引数:
path(str, optional): 操作するファイルのパス。mode(str, optional): ファイルのオープンモード ('r': 読み込み, 'w': 書き込み, 'a': 追記)。デフォルトは 'r'。password(str, optional): パスワード保護されたファイルを開くためのパスワード。allow_no_password(bool, optional): パスワード指定時に開けなかった場合に、パスワードなしでのオープンを試みるか。デフォルトはFalse。tmp_file(str, optional): パスワード保護されたファイルを開く際に使用される一時ファイルのパス。passwordが指定されている場合は必須。デフォルトはNone（内部で 'tmp.xlsx' に設定される）。OpenFile(bool, optional): コンストラクタでファイルを開くかどうか。デフォルトはTrue。CloseFile(bool, optional): コンストラクタ完了後にファイルを閉じるかどうか。デフォルトはFalse。try_text(bool, optional): (未使用)data_only(bool, optional):openpyxlのdata_only引数に渡されます。セルに数式がある場合、数式ではなく計算済みの値を取得するかどうか。デフォルトはTrue。keep_vbas(bool, optional):openpyxlのkeep_vba引数に渡されます。VBAマクロを保持するかどうか。デフォルトはFalse。try_text_file(bool, optional):.txt拡張子のファイルをテキストファイルとして開くかどうか。デフォルトはFalse。encoding(str, optional): テキストファイルやCSVファイルを開く際のエンコーディング。Noneの場合は自動検出を試みます。split_from(int, optional): テキストファイルやCSVファイルを開く際に、指定行までをヘッダーとしてスキップし、それ以降をデータとして読み込む開始行 (1-based)。デフォルトは 1。IsPrint(bool, optional): 処理中にメッセージを出力するかどうか。デフォルトはFalse。**args:tkDataFileのコンストラクタに渡される追加引数。
戻り値: なし
initialize(self, **args)オブジェクトの状態を初期化します。開いているファイルやワークブックを閉じ、内部変数をリセットします。引数:
**args: 内部変数を更新するための追加引数。
戻り値: なし
open_text(self, path = None, mode = 'r', encoding = None, split_from = None, separator = ' ', IsPrint = True)テキストファイルをExcelワークブックとして開きます。指定された区切り文字でデータをセルに分割します。引数:
path(str, optional): テキストファイルのパス。mode(str, optional): ファイルのオープンモード。デフォルトは 'r'。encoding(str, optional): ファイルのエンコーディング。Noneの場合は自動検出を試みます。split_from(int, optional): ヘッダーとしてスキップする行数 (1-based)。Noneの場合はオブジェクトのself.split_fromを使用。separator(str, optional): データを分割する区切り文字。デフォルトは ' '（スペース）。IsPrint(bool, optional): 処理中にメッセージを出力するかどうか。デフォルトはTrue。
戻り値:
openpyxl.workbook.workbook.WorkbookまたはNone: ワークブックオブジェクト。開けなかった場合はNone。
open_csv(self, path = None, mode = 'r', encoding = None, split_from = None, IsPrint = True)CSVファイルをExcelワークブックとして開きます。引数:
path(str, optional): CSVファイルのパス。mode(str, optional): ファイルのオープンモード。デフォルトは 'r'。encoding(str, optional): ファイルのエンコーディング。Noneの場合は自動検出を試みます。split_from(int, optional): ヘッダーとしてスキップする行数 (1-based)。Noneの場合はオブジェクトのself.split_fromを使用。IsPrint(bool, optional): 処理中にメッセージを出力するかどうか。デフォルトはTrue。
戻り値:
openpyxl.workbook.workbook.WorkbookまたはNone: ワークブックオブジェクト。開けなかった場合はNone。
open(self, path = None, mode = None, data_only = True, keep_vbas = False, password = None, allow_no_password = False, tmp_file = "tmp.xlsx", try_text_file = False, encoding = None, split_from = None, IsPrint = True)Excelファイル（.xlsx, .xlsm）、CSVファイル、またはテキストファイルを開きます。パスワード付きファイルの場合はopen_encryptedが内部的に呼び出されます。引数:
__init__と同様。戻り値:
openpyxl.workbook.workbook.WorkbookまたはNone: ワークブックオブジェクト。開けなかった場合はNone。
Open(self, ...)openメソッドのエイリアスです。open_encrypted(self, path = None, mode = None, password = None, allow_no_password = False, tmp_file = 'tmp.xlsx', try_text_file = False, data_only = True, keep_vbas = False, encoding = None, split_from = None, IsPrint = True)パスワード保護されたExcelファイルを開きます。msoffcrypto-toolが必要です。復号化のための一時ファイルを作成し、処理後に削除します。引数:
openメソッドと同様。tmp_fileがNoneだとエラーになります。戻り値:
openpyxl.workbook.workbook.WorkbookまたはNone: ワークブックオブジェクト。開けなかった場合はNone。
close(self)開いているファイルを閉じ、変更があった場合は保存します。引数: なし
戻り値: なし
Close(self)closeメソッドのエイリアスです。set_path(self, path = None, mode = None)オブジェクトのファイルパスとモードを設定します。引数:
path(str, optional): 設定するファイルのパス。mode(str, optional): 設定するモード。
戻り値: なし
SetPath(self, ...)set_pathメソッドのエイリアスです。max_row(self)現在のワークシートの最大行番号を取得します。引数: なし
戻り値:
intまたはNone: 最大行番号 (1-based)。ワークシートが開かれていない場合はNone。
max_column(self)現在のワークシートの最大列番号を取得します。引数: なし
戻り値:
intまたはNone: 最大列番号 (1-based)。ワークシートが開かれていない場合はNone。
update_cell(self, cell_name, val)指定された名前付き範囲のセル値を更新します。引数:
cell_name(str): 更新するセルが含まれる名前付き範囲。val(any): 設定する値。
戻り値:
bool: 更新が成功した場合はTrue、名前付き範囲が見つからない場合はFalse。
set(self, row, column, val, ws = None)指定されたセル（1-basedインデックス）に値を設定します。引数:
row(int): 行番号 (1-based)。column(int): 列番号 (1-based)。val(any): 設定する値。ws(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値: なし
set_val(self, irow, icol, val, ws = None)指定されたセル（0-basedインデックス）に値を設定します。引数:
irow(int): 行インデックス (0-based)。icol(int): 列インデックス (0-based)。val(any): 設定する値。ws(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値: なし
get(self, row, column, def_val = None, ws = None)指定されたセル（1-basedインデックス）の値を取得します。引数:
row(int): 行番号 (1-based)。column(int): 列番号 (1-based)。def_val(any, optional): セルが空だった場合のデフォルト値。ws(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値:
any: セルの値。
get_val(self, irow, icol, def_val = None, ws = None)指定されたセル（0-basedインデックス）の値を取得します。引数:
irow(int): 行インデックス (0-based)。icol(int): 列インデックス (0-based)。def_val(any, optional): セルが空だった場合のデフォルト値。ws(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値:
any: セルの値。
Get(self, irow, icol)get_valメソッドのエイリアスです。get_labels(self, ws = None, irow_origin = 1, icol_origin = 1)指定された行からラベル（ヘッダー）のリストを取得します。引数:
ws(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。irow_origin(int, optional): ラベルの取得を開始する行 (1-based)。デフォルトは 1。icol_origin(int, optional): ラベルの取得を開始する列 (1-based)。デフォルトは 1。
戻り値:
list: ラベルのリスト。
append_data(self, data, print_level = 0)データ辞書をワークシートの最終行に追記します。キーが既存のラベルにない場合は新しい列として追加されます。引数:
data(dict): 追記するデータ（キー: ラベル, 値: データ）。print_level(int, optional): メッセージ出力レベル。デフォルトは 0。
戻り値: なし
get_column_letter(self, i)列の数値インデックス（1-based）からExcelの列文字（例: 1 -> 'A'）を取得します。引数:
i(int): 列の数値インデックス (1-based)。
戻り値:
str: Excelの列文字。
get_icol_from_letter(self, s)Excelの列文字（例: 'A'）から列の数値インデックス（1-based）を取得します。引数:
s(str): Excelの列文字。
戻り値:
int: 列の数値インデックス (1-based)。
get_irow_from_label(self, label, column_org = 1, row_org = 1, sheet = None)指定された列内で特定のラベルを持つ行（1-based）を検索します。引数:
label(any): 検索するラベル。column_org(int, optional): 検索を開始する列 (1-based)。デフォルトは 1。row_org(int, optional): 検索を開始する行 (1-based)。デフォルトは 1。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値:
intまたはNone: 見つかった行番号 (1-based)。見つからない場合はNone。
get_icolumn_from_label_regex(self, label, column_org = 1, row_org = 1, sheet = None, flags = 0)指定された行内で正規表現に一致するラベルを持つ列（1-based）を検索します。引数:
label(str): 検索する正規表現パターン。column_org(int, optional): 検索を開始する列 (1-based)。デフォルトは 1。row_org(int, optional): 検索を開始する行 (1-based)。デフォルトは 1。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。flags(int, optional):reモジュールのフラグ（例:re.IGNORECASE）。デフォルトは 0。
戻り値:
intまたはNone: 見つかった列番号 (1-based)。見つからない場合はNone。
get_icolumn_from_label1(self, label, column_org = 1, row_org = 1, sheet = None)指定された行内で特定のラベルを持つ列（1-based）を検索します（正規表現なし）。引数:
get_icolumn_from_label_regexと同様 (flags引数を除く)。戻り値:
intまたはNone: 見つかった列番号 (1-based)。見つからない場合はNone。
get_icolumn_from_label(self, label, column_org = 1, row_org = 1, sheet = None)単一のラベルまたはラベルのリストを指定して、対応する列インデックス（1-based）を取得します。ラベルがリストの場合、結果もリストで返されます。引数:
label(str or list or tuple): 検索するラベルまたはラベルのリスト。column_org(int, optional): 検索を開始する列 (1-based)。デフォルトは 1。row_org(int, optional): 検索を開始する行 (1-based)。デフォルトは 1。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値:
intまたはlistまたはNone: 見つかった列番号 (1-based) またはそのリスト。見つからない場合はNone。
find_data_array(self, regexp, flags = 0, convert_type = None, def_val = None)正規表現または列インデックスで指定された列からデータを抽出します。引数:
regexp(str or int): 検索する正規表現パターン、または列インデックス (1-based)。flags(int, optional):reモジュールのフラグ。デフォルトは 0。convert_type(type, optional): 抽出したデータを変換する型（例:float,int）。def_val(any or str, optional): セルが空だった場合のデフォルト値。'input' の場合、元の値がデフォルト値として使用されます。
戻り値:
tuple(str,list): (列ラベル, データリスト) のタプル。見つからない場合は (None,None)。
read_data(self, idata = None, flags = '', convert_type = None, def_val = None, is_print = True)複数の列からデータを読み込みます。引数:
idata(list of int or str, optional): 読み込む列のインデックス（1-based）またはラベルのリスト。Noneの場合はすべての列を読み込みます。flags(str, optional):find_data_arrayに渡される正規表現フラグ。convert_type(type, optional): データを変換する型。def_val(any, optional):find_data_arrayに渡されるデフォルト値。is_print(bool, optional): 処理中にメッセージを出力するかどうか。デフォルトはTrue。
戻り値:
tuple(list,list): (ラベルのリスト, データのリストのリスト) のタプル。
get_row_data(self, irow, def_val = None, ws = None)指定された行（1-based）のすべてのセルデータをリストで取得します。引数:
irow(int): 取得する行番号 (1-based)。def_val(any, optional): セルが空だった場合のデフォルト値。ws(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値:
list: 行データのリスト。
get_col_data(self, icol, def_val = None, ws = None)指定された列（1-basedインデックスまたは列文字）のすべてのセルデータをリストで取得します。ヘッダー行（1行目）はスキップされます。引数:
icol(int or str): 取得する列番号 (1-based) または列文字。def_val(any, optional): セルが空だった場合のデフォルト値。ws(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値:
list: 列データのリスト。
get_specified_data(self, indexes = None, rows = None, convert_label = True)指定された列と行の範囲のデータを取得します。引数:
indexes(list of int, optional): 取得する列インデックス (0-based) のリスト。Noneの場合はすべての列。rows(list of int, optional): 取得する行インデックス (0-based) のリスト。Noneの場合はすべての行。convert_label(bool, optional): ラベルに使えない文字を '_' に変換するかどうか。デフォルトはTrue。
戻り値:
tuple(list,list): (ラベルのリスト, データのリストのリスト) のタプル。
get_sheet_by_name(self, title)指定された名前のワークシートを取得します。引数:
title(str): 取得したいワークシートの名前。
戻り値:
openpyxl.worksheet.worksheet.Worksheet: ワークシートオブジェクト。
find_isheet(self, name, reg_exp = False)ワークシートのインデックス、名前、オブジェクトを検索します。引数:
name(str or int): 検索するシートの名前またはインデックス。reg_exp(bool, optional):nameを正規表現として扱うかどうか。デフォルトはFalse。
戻り値:
tuple(int,str,openpyxl.worksheet.worksheet.Worksheet): (シートインデックス, シート名, ワークシートオブジェクト) のタプル。見つからない場合は (None,None,None)。
create_sheet(self, index = 0, title = None)新しいワークシートを作成します。引数:
index(int, optional): シートを作成する位置（インデックス）。デフォルトは 0（先頭）。title(str, optional): 新しいシートのタイトル。
戻り値: なし
remove_sheet(self, title)指定されたタイトルのワークシートを削除します。引数:
title(str): 削除するワークシートのタイトル。
戻り値: なし
set_sheet_name(self, title, sheet = None)ワークシートの名前を変更します。引数:
title(str): 新しいシートのタイトル。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値: なし
get_sheet(self, index)指定されたインデックスまたは名前のワークシートオブジェクトを取得します。引数:
index(int or str oropenpyxl.worksheet.worksheet.Worksheet): シートのインデックス、名前、または既存のシートオブジェクト。Noneの場合は現在のワークシート (self.ws) を返します。
戻り値:
openpyxl.worksheet.worksheet.Worksheet: ワークシートオブジェクト。
get_column_width(self, icolumn, sheet = None)指定された列の幅を取得します。引数:
icolumn(int or str): 列番号 (1-based) または列文字。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値:
float: 列の幅。
set_column_width(self, icolumn, width = None, sheet = None)指定された列の幅を設定します。引数:
icolumn(int or str): 列番号 (1-based) または列文字。width(float, optional): 設定する幅。Noneの場合は何もしません。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値: なし
get_column_hidden(self, icolumn, sheet = None)指定された列が非表示かどうかを取得します。引数:
icolumn(int or str): 列番号 (1-based) または列文字。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値:
bool: 列が非表示であればTrue、そうでなければFalse。
set_column_hidden(self, icolumn, hidden = None, sheet = None)指定された列の表示/非表示を設定します。引数:
icolumn(int or str): 列番号 (1-based) または列文字。hidden(bool, optional):Trueで非表示、Falseで表示。Noneの場合は何もしません。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。Noneの場合は現在のワークシート (self.ws) を使用。
戻り値: なし
set_cell_font(self, row, column, sheet = None, font_color = '000000', italic = False, bold = False, strike = False, underline = None, size = None, font_name = None, vertAlign = 'baseline')指定されたセルのフォントプロパティを設定します。引数:
row(int): 行番号 (1-based)。column(int): 列番号 (1-based)。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。font_color(str, optional): フォントの色（Excelカラーコード）。デフォルトは '000000' (黒)。italic(bool, optional): 斜体にするかどうか。デフォルトはFalse。bold(bool, optional): 太字にするかどうか。デフォルトはFalse。strike(bool, optional): 取り消し線を引くかどうか。デフォルトはFalse。underline(str or None, optional): 下線のスタイル（例: "single", "double"）。size(int, optional): フォントサイズ。font_name(str, optional): フォント名。vertAlign(str, optional): 垂直方向の配置（例: 'baseline', 'superscript', 'subscript'）。
戻り値: なし
set_cell_fill(self, row, column, sheet = None, fgcolor = 'FFFFFF', bgcolor = 'FFFFFF', pattern = 'solid')指定されたセルの塗りつぶしプロパティを設定します。引数:
row(int): 行番号 (1-based)。column(int): 列番号 (1-based)。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。fgcolor(str, optional): 前景色のExcelカラーコード。デフォルトは 'FFFFFF' (白)。bgcolor(str, optional): 背景色のExcelカラーコード。デフォルトは 'FFFFFF' (白)。pattern(str, optional): 塗りつぶしのパターン（例: 'solid'）。
戻り値: なし
find_val_in_row(self, val, irow, column_org = 1, sheet = None)指定された行内で特定の値を検索し、見つかった列番号（1-based）を返します。引数:
val(any): 検索する値。irow(int): 検索する行番号 (1-based)。column_org(int, optional): 検索を開始する列 (1-based)。デフォルトは 1。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。
戻り値:
intまたはNone: 見つかった列番号 (1-based)。見つからない場合はNone。
find_val_in_column(self, val, icolumn, row_org = 1, sheet = None, auto_add = False)指定された列内で特定の値を検索し、見つかった行番号（1-based）を返します。auto_addがTrueの場合、見つからなければ最終行に値を追加します。引数:
val(any): 検索する値。icolumn(int): 検索する列番号 (1-based)。row_org(int, optional): 検索を開始する行 (1-based)。デフォルトは 1。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。auto_add(bool, optional): 見つからない場合に値を追加するかどうか。デフォルトはFalse。
戻り値:
intまたはNone: 見つかった行番号 (1-based)。見つからない場合はNone（auto_add=Falseの場合）。
freeze_panes(self, cell = 'A1', sheet = None)指定されたセル位置でウィンドウ枠を固定します。'A1' を指定すると固定を解除します。引数:
cell(str, optional): 固定するセル位置（例: "B2"）。デフォルトは 'A1'。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。
戻り値: なし
store_column_widths(self, sheet = None, column_org = 1, row_org = 1)現在のワークシートの列幅を内部に保存します。ラベルとインデックスの両方で保存されます。引数:
sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。column_org(int, optional): 取得を開始する列 (1-based)。デフォルトは 1。row_org(int, optional): ラベルを取得する行 (1-based)。デフォルトは 1。
戻り値:
tuple(list,dict): (列幅のリスト, ラベルをキーとする列幅の辞書) のタプル。
restore_column_widths(self, sheet = None, column_org = 1, row_org = 1, by_label = True)保存された列幅をワークシートに復元します。引数:
sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。column_org(int, optional): 処理を開始する列 (1-based)。デフォルトは 1。row_org(int, optional): ラベルを取得する行 (1-based)。デフォルトは 1。by_label(bool, optional): ラベルに基づいて復元するか、インデックスに基づいて復元するか。デフォルトはTrue。
戻り値: なし
store_column_hidden(self, sheet = None, column_org = 1, row_org = 1)現在のワークシートの列の非表示状態を内部に保存します。ラベルとインデックスの両方で保存されます。引数:
sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。column_org(int, optional): 取得を開始する列 (1-based)。デフォルトは 1。row_org(int, optional): ラベルを取得する行 (1-based)。デフォルトは 1。
戻り値:
tuple(list,dict): (列の非表示状態のリスト, ラベルをキーとする非表示状態の辞書) のタプル。
restore_column_hidden(self, sheet = None, column_org = 1, row_org = 1, by_label = True)保存された列の非表示状態をワークシートに復元します。引数:
sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。column_org(int, optional): 処理を開始する列 (1-based)。デフォルトは 1。row_org(int, optional): ラベルを取得する行 (1-based)。デフォルトは 1。by_label(bool, optional): ラベルに基づいて復元するか、インデックスに基づいて復元するか。デフォルトはTrue。
戻り値: なし
insert_rows(self, irow)指定された行に新しい行を挿入します。引数:
irow(int): 挿入する行番号 (1-based)。
戻り値: なし
insert_cols(self, icol, sheet = None, label = None, check_exist = False, return_if_exist = False, column_org = 1, row_org = 1, font = None, alignment = None, fill = None, border = None, width = None, restore_width = True, restore_hidden = True)指定された列に新しい列を挿入し、オプションでラベルや書式を設定します。既存の列と重複しないようにチェックすることも可能です。引数:
icol(int): 挿入する列番号 (1-based)。sheet(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。label(str, optional): 新しい列のヘッダーラベル。check_exist(bool, optional): ラベルが既存の列にあるかチェックするかどうか。デフォルトはFalse。return_if_exist(bool, optional):check_existがTrueでラベルが既存の場合、列を挿入せずにその列のインデックスを返すか。デフォルトはFalse。column_org(int, optional): ラベル検索を開始する列 (1-based)。デフォルトは 1。row_org(int, optional): ラベルが存在する行 (1-based)。デフォルトは 1。font(openpyxl.styles.fonts.Font or int or None, optional): 適用するフォントスタイル。整数の場合、その列のフォントをコピーします。alignment(openpyxl.styles.alignment.Alignment or int or None, optional): 適用する配置スタイル。整数の場合、その列の配置をコピーします。fill(openpyxl.styles.fills.Fill or str or int or None, optional): 適用する塗りつぶしスタイル。文字列の場合、その色で塗りつぶします。整数の場合、その列の塗りつぶしをコピーします。border(openpyxl.styles.borders.Border or int or None, optional): 適用する罫線スタイル。整数の場合、その列の罫線をコピーします。width(float, optional): 新しい列の幅。restore_width(bool, optional): 挿入前後の列幅を復元するかどうか。デフォルトはTrue。restore_hidden(bool, optional): 挿入前後の列の非表示状態を復元するかどうか。デフォルトはTrue。
戻り値:
int: 挿入された列の番号 (1-based)、または既存の列の番号（return_if_exist=Trueの場合）。
delete_rows(self, irow, irow2 = None)指定された範囲の行を削除します。引数:
irow(int): 削除を開始する行番号 (1-based)。irow2(int, optional): 削除を終了する行番号 (1-based)。Noneの場合はirowの1行のみ削除。
戻り値: なし
delete_cols(self, idx, amount = None)指定された列または範囲の列を削除します。引数:
idx(int): 削除を開始する列番号 (1-based)。amount(int, optional): 削除する列の数。Noneの場合はidxの1列のみ削除。
戻り値: なし
get_row(self, irow, ws = None)指定された行（0-based）のセルオブジェクトのタプルを取得し、内部の現在行 (self.cur_row) を更新します。引数:
irow(int): 取得する行インデックス (0-based)。ws(openpyxl.worksheet.worksheet.Worksheet, optional): 対象のワークシート。
戻り値:
tuple: セルオブジェクトのタプル。
copy_cell_format(self, ws_source = None, irow_source = None, icol_source = None, ws_target = None, irow_target = None, icol_target = None, format = 'value|fill|font|border')ソースセルからターゲットセルへ、指定された書式（値、塗りつぶし、フォント、罫線）をコピーします。引数:
ws_source(openpyxl.worksheet.worksheet.Worksheet, optional): ソースワークシート。irow_source(int, optional): ソース行番号 (1-based)。icol_source(int, optional): ソース列番号 (1-based)。ws_target(openpyxl.worksheet.worksheet.Worksheet, optional): ターゲットワークシート。irow_target(int, optional): ターゲット行番号 (1-based)。icol_target(int, optional): ターゲット列番号 (1-based)。format(str, optional): コピーする書式を指定するパイプ区切りの文字列（例: 'value|font'）。デフォルトは 'value|fill|font|border'。
戻り値: なし
copy_worksheet2(self, ws_source = None, title = None)異なるワークブックのシートを、セルごとに書式をコピーして現在のワークブックにコピーします。引数:
ws_source(openpyxl.worksheet.worksheet.Worksheet, optional): コピー元のワークシート。title(str, optional): コピー先のシートのタイトル。Noneの場合はコピー元シートのタイトルを使用。
戻り値:
openpyxl.worksheet.worksheet.Worksheet: 新しく作成されたワークシートオブジェクト。
copy_worksheet(self, ws_source = None, title = None)同じワークブック内のワークシートをコピーします。openpyxlのcopy_worksheetメソッドを利用します。それが失敗した場合はcopy_worksheet2を使ってセルごとにコピーします。引数:
ws_source(openpyxl.worksheet.worksheet.Worksheet, optional): コピー元のワークシート。title(str, optional): コピー先のシートのタイトル。Noneの場合はコピー元シートのタイトルを使用。
戻り値:
openpyxl.worksheet.worksheet.Worksheet: 新しく作成されたワークシートオブジェクト。
append(self, datas)現在のワークシートの最終行にデータを追記します。引数:
datas(list or tuple): 追記するデータ（行データ）。
戻り値: なし
Append(self, datas)appendメソッドのエイリアスです。save(self, path = None, workbook = None)ワークブックをファイルに保存します。引数:
path(str, optional): 保存するファイルのパス。Noneの場合はオブジェクトのself.pathを使用。workbook(openpyxl.workbook.workbook.Workbook, optional): 保存するワークブックオブジェクト。Noneの場合はオブジェクトのself.wbを使用。
戻り値:
objectまたはNone:openpyxl.workbook.workbook.WorkbookオブジェクトまたはNone（保存失敗時）。
write(self, irow, icol, val)指定されたセル（0-basedインデックス）に値を書き込みます。辞書形式のvalを受け取り、値、数値フォーマット、水平アラインメントを設定できます。引数:
irow(int): 行インデックス (0-based)。icol(int): 列インデックス (0-based)。val(any or dict): 書き込む値。辞書の場合、{"val": "値", "number_format": "0.00", "horizontal_allignment": "<"}の形式。
戻り値: なし
Write(self, irow, icol, val)writeメソッドのエイリアスです。print(self, *vals, end = '\n')現在の行と列に値を順次書き込みます。end='\n'の場合、書き込み後に次の行の先頭に移動します。引数:
*vals(any): 書き込む値。リストまたはタプルで複数の値を一度に指定することも可能。end(str, optional): 書き込み後の動作を制御します。'\n'(デフォルト) の場合、次の行に移動。それ以外の場合、同じ行の次の列に留まります。
戻り値: なし
Print(self, *vals, end = '\n')printメソッドのエイリアスです。load_workbook(self, path = None)指定されたパスのワークブックを読み込みます。引数:
path(str, optional): 読み込むファイルのパス。Noneの場合はオブジェクトのself.pathを使用。
戻り値:
openpyxl.workbook.workbook.Workbook: 読み込まれたワークブックオブジェクト。
sheetnames(self, path = None)指定されたファイル内のすべてのシート名を取得します。引数:
path(str, optional): シート名を取得するファイルのパス。Noneの場合はオブジェクトのself.pathを使用。
戻り値:
list: シート名のリスト。
read_sheet(self, path = None, sheet_name = None, mode = 'r', data_only = True, password = None, allow_no_password = False, irow_origin = 1, icol_origin = 1)指定されたシートのすべてのセルオブジェクトを2次元リスト（行と列）として読み込みます。引数:
path(str, optional): 読み込むファイルのパス。sheet_name(str or int, optional): 読み込むシートの名前またはインデックス。Noneの場合はアクティブシート。mode(str, optional): ファイルのオープンモード。デフォルトは 'r'。data_only(bool, optional): セルに数式がある場合、数式ではなく計算済みの値を取得するかどうか。デフォルトはTrue。password(str, optional): パスワード保護されたファイルを開くためのパスワード。allow_no_password(bool, optional): パスワード指定時に開けなかった場合に、パスワードなしでのオープンを試みるか。irow_origin(int, optional): 読み込みを開始する行 (1-based)。デフォルトは 1。icol_origin(int, optional): 読み込みを開始する列 (1-based)。デフォルトは 1。
戻り値:
list of list of openpyxl.cell.cell.CellまたはNone: セルオブジェクトの2次元リスト。開けなかった場合はNone。
Read_sheet(self, ...)read_sheetメソッドのエイリアスです。get_list_from_cells(self, cells = None, debug = False)read_sheetで取得したセルオブジェクトのリストから、ヘッダーとデータリスト（列ごとのリストのリスト）を取得します。引数:
cells(list of list of openpyxl.cell.cell.Cell, optional): セルオブジェクトの2次元リスト。Noneの場合はread_sheet()を呼び出します。debug(bool, optional): デバッグメッセージを出力するかどうか。デフォルトはFalse。
戻り値:
tuple(list,list): (ヘッダーリスト, データリストのリスト) のタプル。
read_sheet_list(self, path= None, sheet_name = None, mode = 'r', data_only = True, password = None, allow_no_password = False, irow_origin = 1, icol_origin = 1, debug = False)指定されたシートからヘッダーとデータリスト（列ごとのリストのリスト）を読み込みます。引数:
read_sheetおよびget_list_from_cellsの引数と同様。戻り値:
tuple(list,list): (ヘッダーリスト, データリストのリスト) のタプル。
Read_sheet_list(self, ...)read_sheet_listメソッドのエイリアスです。get_dict_from_datalist(self, datalist = None, keys = None, irow_origin = 1, icol_origin = 1, allow_overlapped_keys = True)データリストとキー（ヘッダー）のリストから辞書形式のデータを生成します。引数:
datalist(list of list, optional): 列ごとのデータリストのリスト。keys(list, optional): 辞書のキーとなるヘッダーのリスト。irow_origin(int, optional): 読み込みを開始する行 (1-based)。デフォルトは 1。icol_origin(int, optional): 読み込みを開始する列 (1-based)。デフォルトは 1。allow_overlapped_keys(bool, optional): キーが重複している場合に、後続の列のデータを上書きするか（Falseの場合スキップ）どうか。デフォルトはTrue。
戻り値:
dict: ヘッダーをキーとし、各列のデータを値とする辞書。
read_sheet_dict(self, path = None, sheet_name = None, allow_overlapped_keys = True, irow_origin = 1, icol_origin = 1, debug = False)指定されたシートからヘッダー（キー）、データリスト、シート名を辞書形式で読み込みます。引数:
read_sheet_listおよびget_dict_from_datalistの引数と同様。戻り値:
tuple(dict,list,list,list): (データ辞書, 全シート名のリスト, ヘッダーリスト, データリストのリスト) のタプル。
Read_sheet_dict(self, ...)read_sheet_dictメソッドのエイリアスです。get_matrix_from_cells(self, cells = None)セルオブジェクトのリストからヘッダーとデータ行列を生成します。引数:
cells(list of list of openpyxl.cell.cell.Cell, optional): セルオブジェクトの2次元リスト。Noneの場合はread_sheet()を呼び出します。
戻り値:
tuple(list,list): (ヘッダーリスト, データ行列) のタプル。
read_sheet_matrix(self, sheet_name = None)指定されたシートからヘッダーとデータ行列を読み込みます。引数:
sheet_name(str, optional): 読み込むシートの名前。
戻り値:
tuple(list,list): (ヘッダーリスト, データ行列) のタプル。
Read_sheet_matrix(self, sheet_name = None)read_sheet_matrixメソッドのエイリアスです。read_minimum_matrix(self, close_fp = False, force_numeric = True)最小限のデータを行列形式で読み込みます。最初の空セルまでをヘッダーとし、それ以降を数値データとして読み込みます。引数:
close_fp(bool, optional): 読み込み後にファイルを閉じるかどうか。デフォルトはFalse。force_numeric(bool, optional): データを強制的に数値（float）に変換するかどうか。変換できない場合はNone。Falseの場合は変換できない値をそのまま残します。デフォルトはTrue。
戻り値:
tuple(list,list): (ラベルリスト, データリストのリスト) のタプル。
Read_minimum_matrix(self, close_fp = False, force_numeric = True)read_minimum_matrixメソッドのエイリアスです。
main scriptとして実行したときの動作
tkexcel.py がスクリプトとして直接実行された場合（python tkexcel.py）、main() 関数が呼び出されます。この main() 関数は、ライブラリの基本的な機能を示す簡単なサンプルコードを実行します。
具体的には、以下の処理が行われます。
a.xlsxの作成と書き込み、追記:tkExcel("a.xlsx", 'w')で新規にa.xlsxファイルを作成し、書き込みモードで開きます。xls.Write(0, 0, 'a00')でセル (0, 0) に'a00'を書き込みます。xls.Write(1, 1, 'a11')でセル (1, 1) に'a11'を書き込みます。xls.Close()でファイルを保存して閉じます。再度
tkExcel("a.xlsx", 'a')でa.xlsxを追記モードで開きます。xls.Write(0, 1, 'a01')でセル (0, 1) に'a01'を書き込みます。xls.Write(1, 1, 'a22')でセル (1, 1) に'a22'を書き込みます（既存の'a11'を上書き）。xls.Close()でファイルを保存して閉じます。
a.xlsxの読み込みと出力:tkExcel("a.xlsx", 'r')でa.xlsxを読み込みモードで開きます。xls.Get(0, 0)、xls.Get(0, 1)、xls.Get(1, 0)、xls.Get(1, 1)を使って各セルの値を取得し、標準出力に表示します。00=(0,0) の値01=(0,1) の値10=(1,0) の値11=(1,1) の値
xls.Close()でファイルを閉じます。
b.xlsxの作成とprintメソッドによる書き込み:tkExcel("b.xlsx", 'w')で新規にb.xlsxファイルを作成し、書き込みモードで開きます。xls.print([0, 1, 2, 'aa'])で1行目にリストの内容を書き込み、改行します。xls.print([3, 0, 1, 2, 'bb'])で2行目にリストの内容を書き込み、改行します。xls.print([3, 'a&'], end = '')で3行目にリストの内容を書き込みますが、end=''なので改行しません。xls.print([3, 5])で前の行の続きからリストの内容を書き込み、改行します。xls.Close()でファイルを保存して閉じます。
この実行により、a.xlsx と b.xlsx の2つのExcelファイルが作成され、a.xlsx の内容の一部がコンソールに表示されます。
実行結果の例:
00= a00
01= a01
10= None
11= a22
（b.xlsx の内容はコンソールには出力されませんが、ファイルとして作成されます。）