tkfile.py 技術ドキュメント
ライブラリの機能や目的
tkfile.py は、Pythonの標準的なファイル操作を拡張し、特にファイルエンコーディングの自動検出と、正規表現に基づく高度なファイル内容の検索・操作を容易にするためのユーティリティライブラリです。tklib フレームワークの一部として設計されており、tkObject クラスを継承することで、共通のエラーハンドリングや汎用的なユーティリティ機能を共有しています。
このライブラリの主な目的は以下の課題を解決することです。
エンコーディングの自動検出: Pythonでテキストファイルを扱う際に頻繁に問題となる、エンコーディングの不一致を自動的に検出し、適切なエンコーディングでファイルを開くことを可能にします。
ファイル内容の高度な検索とナビゲーション: 特定の正規表現パターンにマッチする行までファイルを読み飛ばしたり、ブロック単位で内容を読み込んだりする機能を提供し、大規模な設定ファイルやログファイルの解析を効率化します。
ファイル操作の共通化: ファイルのオープン、クローズ、読み書き、シークなどの基本的な操作をラップし、一貫したインターフェースで提供します。
正規表現との統合: ファイル操作と密接に関連する正規表現を用いた検索・置換・分割処理を、
tkreモジュールを介して提供します。
主な機能は tkFile クラスによって提供され、ファイルの読み書き、ポインタ操作、そして正規表現を用いたコンテンツベースのファイルナビゲーションを可能にします。
importする方法
このライブラリを他のPythonプログラムから利用するには、以下の方法で必要な関数やクラスをインポートします。
# ファイルエンコーディング検出関数をインポート
from tkfile import get_encoding
# エンコーディング自動検出機能付きファイルオープン関数をインポート
from tkfile import open_chardet
# 高度なファイル操作クラスをインポート
from tkfile import tkFile
# すべてをインポートする場合
import tkfile
必要な非標準ライブラリとインストール方法
tkfile.py は、以下の非標準ライブラリに依存しています。
chardet: ファイルのエンコーディングを自動検出するために使用されます。
インストール方法
chardet は pip を使ってインストールできます。コマンドラインで以下を実行してください。
pip install chardet
補足: tkfile.py は tklib というカスタムライブラリの一部であり、tklib.tkobject.tkObject および tklib.tkutils.is_file、tklib.tkre に依存しています。これらはPython標準ライブラリや pip でインストールできるものではないため、tkfile.py を利用する際には、tklib ディレクトリ全体がPythonのパスが通っている場所、または tkfile.py と同じ階層に適切に配置されている必要があります。
importできる変数と関数
変数
path:テスト用のファイルパスとして
'test.ini'が初期値として設定されています。この変数はライブラリ内部でのみ使用され、外部からインポートして利用することを想定していません。
関数
get_encoding(path, defval='utf-8')指定されたファイルのエンコーディングを
chardetライブラリを使用して検出します。引数:
path(str): エンコーディングを検出するファイルのパス。defval(str, 省略可能): エンコーディングの検出に失敗した場合に返されるデフォルト値。デフォルトは'utf-8'です。
戻り値:
検出されたエンコーディング名 (例:
'CP932','utf-8') を文字列で返します。ファイルが開けない場合は
Noneを返します。検出されたエンコーディングが
'SHIFT_JIS'または'Windows-1254'の場合は'CP932'に変換されます。検出結果が
Noneの場合はdefvalを返します。
open_chardet(path=None, mode=None, encoding=None, def_encoding=None)ファイルのエンコーディングを自動検出した上でファイルを開き、ファイルオブジェクトを返します。
引数:
path(str, 省略可能): 開くファイルのパス。mode(str, 省略可能): ファイルを開くモード (例:'r','w')。デフォルトは'r'です。encoding(str, 省略可能): 明示的に指定するエンコーディング。これが指定された場合、自動検出は行われません。def_encoding(str, 省略可能):get_encodingでエンコーディング検出に失敗した場合のデフォルトエンコーディング。
戻り値:
開かれたファイルオブジェクトを返します。
encodingが指定されていない場合、get_encodingを呼び出してエンコーディングを検出します。エンコーディングが検出されない場合や指定されない場合は、
'shift_jis'で開こうとします。
クラス
class tkFile(tkObject)ファイル操作を拡張したクラスです。
tklib.tkobject.tkObjectを継承しており、基本的なオブジェクト管理とエラーハンドリング機能を利用できます。__init__(self, path=None, mode='r', encoding='utf-8', OpenFile=True, IsPrint=True, **args)tkFileオブジェクトのコンストラクタです。引数:
path(str, 省略可能): 操作対象のファイルパス。mode(str, 省略可能): ファイルを開くデフォルトモード (例:'r','w')。デフォルトは'r'です。encoding(str, 省略可能): デフォルトのエンコーディング。デフォルトは'utf-8'です。OpenFile(bool, 省略可能): インスタンス作成時にファイルを自動的に開くかどうか。デフォルトはTrueです。IsPrint(bool, 省略可能): エラーメッセージを標準出力に表示するかどうか。デフォルトはTrueです。**args:tkObjectのコンストラクタに渡される追加のキーワード引数。
__del__(self)デストラクタです。オブジェクトが破棄される際にファイルを自動的に閉じます。
__str__(self)オブジェクトの文字列表現を返します。
ClassPath()メソッドの結果（クラスのフルパス）を返します。
SetPath(self, path=None, mode=None)オブジェクトの
pathとmode属性を設定します。引数:
path(str, 省略可能): 新しいファイルパス。Noneの場合は現在の値を保持します。mode(str, 省略可能): 新しいモード。Noneの場合は現在の値を保持します。
open(self, path=None, mode=None, IsPrint=True, encoding=None)ファイルをオープンします。ファイルが存在しない場合や開けない場合はエラーメッセージを出力し
Noneを返します。引数:
path(str, 省略可能): 開くファイルのパス。Noneの場合はオブジェクトに設定されているパスを使用します。mode(str, 省略可能): ファイルを開くモード。Noneの場合は'r'を使用します。IsPrint(bool, 省略可能): エラーメッセージを標準出力に表示するかどうか。デフォルトはTrueです。encoding(str, 省略可能): 明示的に指定するエンコーディング。Noneの場合、自動検出を試みます。
戻り値:
開かれたファイルオブジェクト (
_io.TextIOWrapper) を返します。開けなかった場合は
Noneを返します。
動作:
modeに'r'が含まれ、かつファイルが存在しない場合はエラー。encodingが指定されない場合、UniversalDetectorを使用してエンコーディングを自動検出します。検出結果が'SHIFT_JIS'または'MacRoman'の場合は'CP932'に変換します。自動検出に失敗した場合や
encodingがNoneの場合、最終的に'utf-8'を使用します。
Open(self, path=None, mode=None, IsPrint=True, encoding=None)openメソッドのエイリアスです。
close(self)開いているファイルを閉じます。ファイルが閉じられていない場合は何もしません。
Close(self)closeメソッドのエイリアスです。
read(self)ファイルの内容をすべて読み込み、文字列として返します。
戻り値: ファイルの内容を示す文字列。
Read(self)readメソッドのエイリアスです。
readline(self)ファイルから1行読み込みます。
戻り値: 読み込まれた行（末尾に改行文字を含む可能性あり）。ファイル終端に達した場合は空文字列
''を返します。ファイルがオープンされていない場合はNoneを返します。
ReadLine(self)readlineメソッドのエイリアスです。
ReadLineList(self)ファイルの内容をすべての行のリストとして読み込みます。
戻り値: 各行を要素とする文字列のリスト。ファイルがオープンされていない場合は
Noneを返します。
ReadCharList(self)ファイルの内容をすべての文字のリストとして読み込みます。
戻り値: 各文字を要素とする文字列のリスト。ファイルがオープンされていない場合は
Noneを返します。
ReadLines(self)ファイルの内容をすべて読み込み、行を結合した単一の文字列として返します。
戻り値: ファイルの内容を示す文字列。ファイルがオープンされていない場合は
Noneを返します。
write(self, s)指定された文字列
sをファイルに書き込みます。引数:
s(str): ファイルに書き込む文字列。
戻り値: 成功した場合
True、ファイルがオープンされていない場合はFalse。
Write(self, s)writeメソッドのエイリアスです。
write_lines(self, lines)指定された行のリストをファイルに書き込みます。
引数:
lines(list): 書き込む文字列のリスト。
戻り値: 全ての書き込みが成功した場合
True、途中で失敗した場合またはファイルがオープンされていない場合はFalse。
WriteLines(self, lines)write_linesメソッドのエイリアスです。
CopyUntil(self, out, reg=None)現在のファイルポインタから読み込みを開始し、指定された正規表現
regにマッチする行が見つかるまで、読み込んだ各行を別のファイルオブジェクトoutに書き込みます。regにマッチする行が見つかった場合、その行の読み込みは行われますが、outには書き込まれません。ファイルポインタはその行の直後になります。引数:
out(tkFileオブジェクト): 読み込んだ行を書き込む先のtkFileオブジェクト。reg(str, 省略可能): 読み込みを停止する正規表現パターン。Noneの場合、現在の行を読み込んだら終了します。
戻り値:
正規表現にマッチした場合、そのマッチオブジェクトを返します。
ファイル終端に達した場合、
Noneを返します。
eof(self)ファイルポインタがファイルの終端に達しているかどうかを判定します。
戻り値: ファイルの終端に達している場合
True、そうでない場合False。ファイルがオープンされていない場合もTrueを返します。
rewind(self)ファイルポインタをファイルの先頭に戻します (オフセット 0)。
Rewind(self)rewindメソッドのエイリアスです。
seek(self, offset, whence=os.SEEK_SET)ファイルポインタを指定された位置に移動します。
引数:
offset(int): 基準位置からのオフセット。whence(int, 省略可能): 基準位置。os.SEEK_SET(先頭から、デフォルト),os.SEEK_CUR(現在位置から),os.SEEK_END(終端から)。
Seek(self, offset, whence=os.SEEK_SET)seekメソッドのエイリアスです。
tell(self)現在のファイルポインタの位置（ファイルの先頭からのバイトオフセット）を返します。
戻り値: 現在のファイルポインタの位置を示す整数。ファイルがオープンされていない場合は
0を返します。
Tell(self)tellメソッドのエイリアスです。
skip_to(self, pattern, origin=None, re_flag=None, max_lines=-1)指定された正規表現
patternにマッチする行が見つかるまでファイルを読み飛ばします。引数:
pattern(str): 検索する正規表現パターン。origin(int, 省略可能): 検索を開始するファイルポインタのオフセット。Noneの場合、現在の位置から検索を開始します。re_flag(int, 省略可能): 正規表現フラグ (例:re.IGNORECASE)。Noneの場合、re.IGNORECASEを使用します。max_lines(int, 省略可能): 検索する最大行数。-1の場合、制限なし。
戻り値:
マッチした行から改行文字を削除した文字列を返します。
マッチが見つからなかった場合、
Noneを返します。
副作用: マッチオブジェクトは
self.last_matchに保存されます。
SkipTo(self, pattern, origin=None, re_flag=None, max_lines=-1)skip_toメソッドのエイリアスです。
search_to(self, pattern, origin=None, defval=None, max_lines=-1)指定された正規表現
patternにマッチする行が見つかるまでファイルを検索し、マッチオブジェクトを返します。引数:
pattern(str): 検索する正規表現パターン。origin(int, 省略可能): 検索を開始するファイルポインタのオフセット。Noneの場合、現在の位置から検索を開始します。defval(any, 省略可能): マッチが見つからなかった場合に返されるデフォルト値。max_lines(int, 省略可能): 検索する最大行数。-1の場合、制限なし。
戻り値:
マッチした場合、
tkre.Searchが返すマッチオブジェクト（またはリスト形式のタプル）を返します。マッチが見つからなかった場合、
defvalが指定されていればdefvalを返します。そうでない場合はNoneを返します。
SearchTo(self, pattern, origin=None, defval=None, max_lines=-1)search_toメソッドのエイリアスです。defvalのデフォルトがoriginになっていますが、これは誤植の可能性があります（通常はNoneや空リストなどを指定）。
Match(self, reg, str, flag='', defval=None)文字列の先頭から正規表現
regにマッチするかどうかを調べます（re.matchに相当）。tkre.Matchのラッパーです。引数:
reg(str): 正規表現パターン。str(str): 検索対象の文字列。flag(str, 省略可能): 正規表現フラグ（例:'i'はre.IGNORECASE）。defval(any, 省略可能): マッチしなかった場合に返されるデフォルト値。
戻り値: マッチオブジェクト、または
defval。
Search(self, reg, str, flag='', defval=None)文字列全体で正規表現
regにマッチするかどうかを調べます（re.searchに相当）。tkre.Searchのラッパーです。引数:
reg(str): 正規表現パターン。str(str): 検索対象の文字列。flag(str, 省略可能): 正規表現フラグ。defval(any, 省略可能): マッチしなかった場合に返されるデフォルト値。
戻り値: マッチオブジェクト、または
defval。
ReadBlock(self, end_regexp=r'^\s*$')ファイルから行を読み込み、指定された正規表現
end_regexpにマッチする行が見つかるまでを一つのブロックとしてリストに格納して返します。ブロックの終端と見なされた行は読み戻されます（ファイルポインタは終端行の開始位置に戻る）。引数:
end_regexp(str, 省略可能): ブロックの終端を示す正規表現パターン。デフォルトは空白行 (r'^\s*$') です。
戻り値: ブロック内の行のリスト。ファイル終端に達した場合、空のリストまたは残りの行のリスト。
Split(self, reg, str)正規表現
regを区切り文字として文字列strを分割します（re.splitに相当）。tkre.Splitのラッパーです。引数:
reg(str): 正規表現パターン。str(str): 分割対象の文字列。
戻り値: 分割された文字列のリスト。
shSplit(self, reg, str)tkre.shSplitのラッパーです。シェルライクな分割処理（引用符を考慮した分割など）を行うと推測されます。引数:
reg(str): 正規表現パターン。str(str): 分割対象の文字列。
戻り値: 分割された文字列のリスト。
Sub(self, reg, target, str, n=0)文字列
str内で正規表現regにマッチする部分をtargetに置換します（re.subに相当）。tkre.Subのラッパーです。引数:
reg(str): 検索する正規表現パターン。target(str): 置換後の文字列。str(str): 置換対象の文字列。n(int, 省略可能): 置換する最大回数。0の場合、すべてのマッチを置換。
戻り値: 置換後の文字列。
SubN(self, reg, target, str, n=0)tkre.SubNのラッパーです。re.subnに相当し、置換後の文字列と置換回数のタプルを返すと推測されます。引数:
reg(str): 検索する正規表現パターン。target(str): 置換後の文字列。str(str): 置換対象の文字列。n(int, 省略可能): 置換する最大回数。0の場合、すべてのマッチを置換。
戻り値:
(置換後の文字列, 置換回数)のタプル。
DelCRLF(self, str)文字列の末尾から改行文字 (CR, LF) を削除します。
引数:
str(str): 処理対象の文字列。
戻り値: 改行文字が削除された文字列。
DelSpace(self, str)文字列の先頭と末尾から空白文字を削除します（
str.strip()に相当）。引数:
str(str): 処理対象の文字列。
戻り値: 先頭と末尾の空白文字が削除された文字列。
DelTopSpace(self, str)文字列の先頭から空白文字を削除します（
str.lstrip()に相当）。引数:
str(str): 処理対象の文字列。
戻り値: 先頭の空白文字が削除された文字列。
DelLastSpace(self, str)文字列の末尾から空白文字を削除します（
str.rstrip()に相当）。引数:
str(str): 処理対象の文字列。
戻り値: 末尾の空白文字が削除された文字列。
main scriptとして実行したときの動作
tkfile.py がメインスクリプトとして直接実行された場合 (python tkfile.py のように)、以下の動作を行います。
if __name__ == "__main__":ブロックが実行されます。スクリプト冒頭で定義されているグローバル変数
path('test.ini') を引数としてmain()関数が呼び出されます。main()関数内で、tkFileクラスのインスタンスがpathで指定されたファイル ('test.ini') に対して作成されます。この際、OpenFile=Trueのため、ファイルは自動的に開かれます。開かれたファイルオブジェクト
fp(tkFileインスタンス) のfp属性（内部のファイルハンドル）の型が表示されます。fp.Rewind()が呼び出され、ファイルポインタがファイルの先頭に戻されます。fp.ReadLine()を使用してファイルから最初の1行が読み込まれ、その内容が "ReadLine=" のプレフィックスとともに表示されます。再度
fp.Rewind()が呼び出されます。fp.ReadLines()を使用してファイルの内容全体がすべての行を結合した文字列として読み込まれ、その内容が "ReadLines=" のプレフィックスとともに表示されます。再度
fp.Rewind()が呼び出されます。fp.ReadCharList()を使用してファイルの内容全体が文字のリストとして読み込まれ、その内容が "Chars=" のプレフィックスとともに表示されます。最後に
fp.Close()が呼び出され、ファイルが閉じられます。
この main 関数は、tkFile クラスの基本的なファイル読み込み機能（行単位、全内容、文字リスト）のデモンストレーションとテストを目的としています。実行するためには、test.ini という名前のファイルがスクリプトと同じディレクトリに存在している必要があります。存在しない場合、tkFile の open メソッドでエラーが表示され、ファイルが開けません。