tkinifile.py Technical Documentation
ライブラリの機能や目的
tkinifile.py は、PythonアプリケーションでINI形式の設定ファイルを効率的に読み書きするためのライブラリです。基本的なファイル操作機能を提供するtklib.tkfile.tkFileクラスを継承しており、INIファイルに特化したセクションおよびキー/値のペアの管理機能を追加します。
主な目的と機能は以下の通りです。
INIファイルの読み込み: ファイル全体、特定のセクション、または特定のキーの値を読み込むことができます。
INIファイルへの書き込み: 既存のキーの値を更新したり、新しいセクションやキー/値のペアを追加したりできます。
ファイル操作の抽象化: ファイルのオープン、クローズ、行単位の読み書き、ファイルポインタのシークといった低レベルな操作は、基底クラス
tkFileから継承・利用されます。柔軟なキー/値の検索: セクション内で特定のキーを検索し、その値を抽出する機能を提供します。
ファイル構造の保持: INIファイルを書き込む際に、既存のコメントや空白行などの構造を可能な限り保持しながら、指定されたキーを更新または追加します。
このライブラリは、アプリケーションの設定、構成、ユーザー設定などをINIファイル形式で管理する際に、煩雑なファイル解析ロジックを開発者が記述する手間を省き、より直感的かつ堅牢な方法を提供することを目指しています。
importする方法
tkinifile.py ライブラリは、Pythonプログラム内で以下のようにインポートして使用します。
from tkinifile import tkIniFile
また、デフォルトで設定されている入力ファイル名と出力ファイル名を変数として利用することも可能です。
from tkinifile import tkIniFile, infile, outfile
必要な非標準ライブラリとインストール方法
tkinifile.py は、標準ライブラリの他に以下の非標準ライブラリに依存しています。
tklib:tklib.tkutilstklib.tkfiletklib.tkre
tklibは、このライブラリが依存するカスタムライブラリであるため、通常はpipで直接インストールできるものではありません。これは同じプロジェクト内に配置されているか、事前に手動でインストールされていることを想定しています。
もし、tklib がPyPIで公開されている場合は、以下のコマンドでインストールできます。
pip install tklib
注記: chardetはソースコード内でインポートされていますが、tkinifile.pyの提供されたメソッド内では直接使用されていません。tklib.tkfile.tkFileまたはその関連機能で間接的に使用される可能性がありますが、tkinifile.pyの機能自体には直接的な影響を与えません。
importできる変数と関数
tkinifile.py からインポートできる変数とクラス、そのメソッドは以下の通りです。
変数
infile: デフォルトの入力INIファイル名。infile = 'test.ini'
outfile: デフォルトの出力INIファイル名。outfile = 'test-out.ini'
クラス
tkIniFile(tkFile)
INIファイルを操作するためのメインクラスです。tklib.tkfile.tkFile を継承しています。
コンストラクタ:
__init__(self, path = None, mode = 'r', OpenFile = 1, IsPrint = True, **args)tkIniFileオブジェクトを初期化します。動作: 指定されたパスのINIファイルを開くか、既存の
tkFileオブジェクトのパスとモードを設定します。内部変数を初期化し、UseAsIniFile,CreateIniFile,ProgramPathなどの情報をvar辞書に格納します。引数:
path(str, optional): INIファイルのパス。デフォルトはNone（親クラスtkFileのデフォルトパスを使用）。mode(str, optional): ファイルのオープンモード（例:'r'で読み込み、'w'で書き込み）。デフォルトは'r'。OpenFile(int, optional): ファイルを即座に開くかどうかを示すフラグ。1で開く、0で開かない。デフォルトは1。IsPrint(bool, optional): デバッグやエラーメッセージを出力するかどうかを示すフラグ。デフォルトはTrue。**args: 親クラスtkFileに渡される追加引数、またはKeyHead,SystemKeyHead,ProgramPath,CreateIniFile,UseAsIniFileといったtkIniFile固有の初期設定を上書きするためのキーワード引数。
戻り値: なし
メソッド:
__del__(self)tkIniFileオブジェクトが削除される際に呼び出されるデストラクタ。動作: 開いているファイルを閉じ、親クラスのデストラクタを呼び出します。
引数: なし
戻り値: なし
__str__(self)オブジェクトの文字列表現を返します。動作: 親クラス
tkFileのClassPath()メソッドを呼び出し、クラスのフルパスを返します。引数: なし
戻り値:
str- クラスのフルパス。
read_all(self, path = None, section = None, AddSection = False, ignore_keys = [], IsPrint = False, encoding = None)INIファイル全体、または特定のセクションの内容を辞書として読み込みます。動作: ファイルを開き、行ごとに解析してセクションとキー/値のペアを抽出します。コメント行と空白行はスキップされます。
引数:
path(str, optional): 読み込むINIファイルのパス。指定がない場合は、オブジェクトが初期化された際のパスを使用します。section(str, optional): 特定のセクションのみを読み込む場合にそのセクション名を指定します。Noneの場合、全セクションを読み込みます。AddSection(bool, optional): 返される辞書のキーにセクション名をプレフィックスとして追加するかどうか。Trueの場合、キーは"SectionName/Key"の形式になります。デフォルトはFalse。ignore_keys(list, optional): 読み込み時に無視するキー名のリスト。デフォルトは空のリスト。IsPrint(bool, optional): 印刷フラグ。デフォルトはFalse。encoding(str, optional): ファイルのエンコーディング。デフォルトはNone（自動検出またはシステムのデフォルト）。
戻り値:
dict- 読み込んだキー/値のペアを含む辞書。ファイルが開けない場合はNone。
ReadAll(self, path = None, AddSection = 0, ignore_keys = [], IsPrint = False, encoding = None)read_allメソッドのエイリアスです。動作:
read_allと同じ動作。引数:
read_allと同じ。戻り値:
read_allと同じ。
GetNextSection(self)現在のファイルポインタから次のセクションとその内容を読み込みます。動作: ファイルから次の
[Section]ヘッダーを見つけ、そのセクションのタイトルと、次のセクションが始まるまで（またはファイルの終わりまで）の行リストを返します。引数: なし
戻り値:
tuple-(secname, lines)の形式。secnameはセクション名（文字列）、linesはそのセクションの内容（コメント、キー/値など）を含む行のリスト。ファイル終端の場合は('', [])を返します。
FindSectionFromStr(self, section, lines = None)指定されたセクション名を行リストの中から探し、その開始位置、挿入位置、終了位置のインデックスを返します。動作: 与えられた行リスト（またはオブジェクトの内部行リスト
self.lines）を走査し、[section]という形式の行を見つけます。見つかった場合、そのセクションの開始行、セクション内の最後の非空白行（新しいキーの挿入点）、およびセクションの終了行（次のセクションの開始行の前またはファイルの末尾）のインデックスを返します。引数:
section(str): 検索するセクション名。lines(list, optional): 検索対象となる行リスト。指定がない場合はself.linesを使用します。
戻り値:
tuple-(i0, iins, i1)の形式。i0はセクションの開始行インデックス、iinsはセクション内の最後の非空白行のインデックス（新しいキーの挿入点）、i1はセクションの終了行のインデックス。セクションが見つからない場合は(None, None, None)。
FindLastNonBlankLine(self, lines = None)行リスト内の最後の非空白行のインデックスを検索します。動作: 与えられた行リスト（またはオブジェクトの内部行リスト
self.lines）を末尾から走査し、空白でない最初の行のインデックスを見つけます。引数:
lines(list, optional): 検索対象となる行リスト。指定がない場合はself.linesを使用します。
戻り値:
int- 最後の非空白行のインデックス。リストが空または全て空白行の場合は0。
FindKeyFromSectionRange(self, i0, i1, key, lines = None)指定された行範囲内で特定のキーを探し、その行インデックスを返します。動作:
i0からi1までの行インデックスの範囲で、key=の形式で始まる行を検索します。引数:
i0(int): 検索を開始する行インデックス。i1(int): 検索を終了する行インデックス。key(str): 検索するキー名。lines(list, optional): 検索対象となる行リスト。指定がない場合はself.linesを使用します。
戻り値:
int- キーが見つかった行のインデックス。見つからない場合はNone。
WriteString(self, section, key, value, outfile = None, IsPrint = False)write_stringメソッドのエイリアスです。動作:
write_stringと同じ動作。引数:
write_stringと同じ。戻り値:
write_stringと同じ。
write_from_scratch(self, outfile, section, **kwargs)新しいINIファイルをゼロから作成し、指定されたセクションとキー/値のペアを書き込みます。動作: 指定された
outfileを書き込みモードで開き、[section]ヘッダーとそれに続くkey=valueの形式の行を書き込みます。既存のファイルは上書きされます。引数:
outfile(str): 出力ファイルのパス。section(str): 書き込むセクション名。**kwargs: 書き込むキーと値のペア。値はtklib.tkutils.conv_floatで処理されます。
戻り値:
bool- 書き込みが成功した場合はTrue、失敗した場合はFalse。
write_string(self, section, key, value, outfile = None, is_print = False)INIファイルに特定のセクションとキー/値のペアを書き込みます。セクションやキーが存在しない場合は追加し、存在する場合は更新します。動作: 既存のファイルを読み込み、指定された
sectionを見つけます。そのセクション内にkeyが存在すればvalueでその行を更新し、存在しなければセクション内の適切な位置にkey=value行を追加します。section自体が存在しない場合は、ファイルの最後に新しいセクションとそのキーを追加します。更新された内容をoutfileに書き込みます。引数:
section(str): 書き込むセクション名。key(str): 書き込むキー名。value(any): キーに設定する値。tklib.tkutils.conv_floatで処理されます。outfile(str, optional): 出力ファイルパス。指定がない場合はオブジェクトが初期化された際のパス（self.path）を使用します。is_print(bool, optional): 印刷フラグ。デフォルトはFalse。
戻り値:
bool- 書き込み操作が成功した場合はTrue、失敗した場合はFalse。
GetString(self, section = None, key = None, defstr = None, IsPrint = False)get_stringメソッドのエイリアスです。動作:
get_stringと同じ動作。引数:
get_stringと同じ。戻り値:
get_stringと同じ。
get_string(self, section = None, key = None, def_val = None, is_print = False)INIファイルから特定のセクションとキーに対応する値を読み込みます。動作: ファイルを巻き戻し、指定された
sectionヘッダーまでスキップします。そのセクション内でkey=の形式の行を探し、対応する値を抽出して返します。セクションまたはキーが見つからない場合、def_valを返します。sectionのみが指定されkeyがNoneの場合、そのセクションの全行を読み込みます。引数:
section(str, optional): 読み込むセクション名。Noneの場合、ファイル全体の行リストを返します。key(str, optional): 読み込むキー名。Noneの場合、指定されたセクションの全行を返します。def_val(any, optional): セクションまたはキーが見つからなかった場合に返すデフォルト値。デフォルトはNone。is_print(bool, optional): 印刷フラグ。デフォルトはFalse。
戻り値:
str- キーに対応する値。セクションまたはキーが見つからずdef_valが指定されている場合はdef_val。sectionのみ指定された場合はセクション内の全行のリスト。それ以外はNone。
GetSection(self, section)指定されたセクション内のすべての行（キー/値ペア、コメント、空白行など）をリストとして返します。動作: ファイルを巻き戻し、指定された
sectionヘッダーまでスキップします。次のセクションヘッダーが現れるまで、またはファイルの終端まで、すべての行を読み込み、リストに格納して返します。引数:
section(str): 読み込むセクション名。
戻り値:
list- セクションの内容を含む行のリスト。セクションが見つからない場合は空の文字列''。
main scriptとして実行したときの動作
tkinifile.py を直接実行 (python tkinifile.py または python -m tkinifile) した場合、main() 関数が実行されます。この関数は、tkIniFileクラスの基本的な使用例を示しています。
実行の流れは以下の通りです。
test.iniというファイル名でtkIniFileオブジェクトを読み込みモードで作成します。ini = tkIniFile(infile, 'r')
ファイルから最初の1行を読み込み、その内容をコンソールに出力します。
first line=[...]
[Boot]セクションからTitleというキーの値を読み込み、noneをデフォルト値として設定し、その内容をコンソールに出力します。title=[...]
[Boot]セクション全体の内容（キー、値、コメント、空白行など）をリストとして読み込み、その内容をコンソールに出力します。section [Boot]=[...]
outfile（デフォルトはtest-out.ini）に対して書き込み操作を実行します。[EditFile]セクションのfname2というキーにabc.txtという値を書き込みます。もしtest-out.iniファイルが存在しない場合は新規作成され、存在する場合は[EditFile]セクション内のfname2の値が更新されるか、セクションの末尾にfname2=abc.txtが追加されます。WriteString test
最後に、開いているファイルを閉じます。
ini.close()
このmain関数は、tkinifile.pyがINIファイルの読み取り、特定のキーの値の取得、セクション全体の取得、およびキー/値の書き込み（追加・更新）を行う能力をデモンストレーションするためのものです。実行にはtest.iniファイルがカレントディレクトリに存在する必要があります。