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

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

tkdebug.py は、Pythonプログラムにおけるデバッグ出力を簡素化し、その方法を柔軟に切り替えるための軽量なライブラリです。主な目的は、開発者がデバッグメッセージを print 関数のような感覚で記述できるAPI (dbg) を提供しつつ、その出力を標準出力（コンソール）へ行うか、ログファイルへ行うかを簡単に設定できるようにすることです。

このライブラリは以下の課題を解決します。

デバッグ出力の切り替え: デバッグレベルの設定一つで、デバッグメッセージをコンソールに出力するか、ログファイルに出力するかを瞬時に切り替えられます。
情報付加: デバッグメッセージに、呼び出し元のファイル名、行番号、および現在の時刻を自動的に付加し、デバッグ作業の効率を高めます。
簡易API: 標準の print 関数と類似したAPI (dbg) を提供することで、デバッグコードの記述を直感的で簡単なものにします。

importする方法

tkdebug.py ファイルをプロジェクトの適切なディレクトリに配置し、標準的なPythonモジュールとしてインポートします。

# ライブラリ全体をインポートする場合
import tkdebug

# 特定の関数のみをインポートする場合
from tkdebug import dbg, set_debug

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

tkdebug.py はPythonの標準ライブラリのみを使用しており、inspect, logging, os, sys, datetime, typing などは全てPythonに標準で含まれています。

したがって、別途 pip コマンドなどを用いた非標準ライブラリのインストールは不要です。

importできる変数と関数

変数

DEBUG_LEVEL: int
- デバッグ出力のレベルを制御するグローバル変数です。
- 0: デバッグ出力を無効にします。dbg 関数を呼び出しても何も出力されません。
- 1: デバッグ出力を標準出力（コンソール）に行います。print 関数と同様の動作をします。
- 2: デバッグ出力をログファイルに行います。logging モジュールを通じて LOG_FILE で指定されたファイルに書き込まれます。
- 初期値は 1 です。
LOG_FILE: str
- DEBUG_LEVEL が 2 （logging出力）に設定されている場合に使用されるログファイルのパスです。
- 初期値は "debug.log" です。

関数

set_debug(level: int | None = None, log_file: str | None = None) -> None
- 動作: デバッグ出力の設定（DEBUG_LEVEL と LOG_FILE）を変更します。log_file が変更された場合、logging モジュールの設定を再初期化し、新しいログファイルへの出力が有効になるようにします。logging.basicConfig は通常最初の呼び出ししか有効ではないため、この関数では既存のハンドラを閉じて削除し、再度 basicConfig を呼び出すことで設定を更新しています。
- 引数:
  - level (int | None): 新しいデバッグレベルを設定するための整数値 (0, 1, 2)。None が指定された場合は、現在の DEBUG_LEVEL の設定が維持されます。
  - log_file (str | None): 新しいログファイルのパスを設定するための文字列。None が指定された場合は、現在の LOG_FILE の設定が維持されます。ログファイル名が変更された場合のみ、logging の設定が再ロードされます。
- 戻り値: None。
dbg(*msgs: Any, sep: str = " ", end: str = "\n", flush: bool = False) -> None
- 動作: print 関数に似た形式でデバッグメッセージを出力します。DEBUG_LEVEL の設定に応じて、標準出力またはログファイルに出力先が切り替わります。メッセージの前に、現在の時刻、呼び出し元のファイル名、および行番号が自動的に付加されます。DEBUG_LEVEL が 0 以下の場合、この関数は何も出力しません。また、inspect.currentframe() を使用したフレーム参照は、循環参照を防ぐために明示的に解放されます。
- 引数:
  - *msgs (Any): 出力する任意の数のオブジェクト。print と同様に複数の値を渡すことができます。これらのオブジェクトは文字列に変換され、sep で指定された区切り文字で結合されます。
  - sep (str): 複数のメッセージを結合する際に使用される区切り文字。デフォルトは半角スペース (" ") です。
  - end (str): メッセージの末尾に追加される文字列。デフォルトは改行文字 ("\n") です。DEBUG_LEVEL が 2 （logging出力）の場合、ログシステムが改行を処理するため、この引数は内部的に吸収されます。
  - flush (bool): DEBUG_LEVEL が 1 （print出力）の場合にのみ有効です。True に設定すると、出力バッファが強制的にフラッシュされます。デフォルトは False です。logging 出力には影響しません。
- 戻り値: None。

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

tkdebug.py が直接Pythonインタープリタによって実行された場合 (python tkdebug.py)、以下のデモンストレーションコードが実行されます。このコードは、set_debug と dbg 関数の基本的な使用方法と、異なるデバッグレベルでの動作を示します。

初期設定: まず、set_debug(level=1) が呼び出され、DEBUG_LEVEL が 1 (print出力モード) に設定されます。
printモードでの出力:
- dbg("start") により、start というメッセージがコンソールに出力されます。
- 変数 x=10 と y=3.14 が定義され、dbg("x =", x, "y =", y) により x = 10 y = 3.14 のように、時刻、ファイル名、行番号のプレフィックスと共にコンソールに出力されます。
- dbg("i=", 5, " j=", 9, sep="") により、sep="" の指定が適用され、i=5 j=9 のように区切り文字なしで結合されたメッセージがコンソールに出力されます。
- dbg("done", flush=True) により、done メッセージが出力され、出力バッファが強制的にフラッシュされます。
loggingモードへの切り替え: set_debug(level=2, log_file="debug.log") が呼び出され、DEBUG_LEVEL が 2 (logging出力モード) に、LOG_FILE が "debug.log" に設定されます。この際、logging モジュールの設定が更新され、既存のログハンドラが閉じられて新しいログファイルに紐付けられます。
loggingモードでの出力: dbg("これは logging に出ます") が呼び出され、"debug.log" ファイルに [時刻ファイル名:行番号] これは logging に出ます という形式でログが記録されます。

この実行により、コンソールには最初の dbg 呼び出し群の結果が表示され、同時に debug.log ファイルが生成され、最後の dbg 呼び出しの結果が記録されます。

# コンソール出力例 (時刻とファイル名は実行環境により異なる)
[HH:MM:SS tkdebug.py:64] start
[HH:MM:SS tkdebug.py:65] x = 10 y = 3.14
[HH:MM:SS tkdebug.py:66] i=5 j=9
[HH:MM:SS tkdebug.py:67] done

# debug.log の内容例 (時刻とファイル名は実行環境により異なる)
YYYY-MM-DD HH:MM:SS,ms DEBUG [HH:MM:SS tkdebug.py:71] これは logging に出ます

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