Travel-Debugger 1.0.0

実行状態記録を用いた革命的なPythonタイムトラベルデバッグライブラリ

TimeTravelDebugger 🕐

実行状態記録を用いた革命的なPythonタイムトラベルデバッグライブラリ

🚀 特徴

• 完全実行記録: すべての変数変更、関数呼び出し、実行ステップをキャプチャ
• タイムトラベルインターフェース: プログラムの実行タイムラインをナビゲート
• 多様な使用パターン: デコレータ、コンテキストマネージャー、グローバルデバッグ
• リッチ可視化: 美しいターミナルベースのタイムラインと変数検査
• EphemeralDB統合: パフォーマンス向上のための効率的なスコープベース状態ストレージ
• セッション管理: デバッグセッションの保存、読み込み、共有
• CLIツール: スクリプトデバッグ用のコマンドラインインターフェース
• インタラクティブエクスプローラー: 実行状態をインタラクティブにナビゲート

📦 インストール

pip install Travel-Debugger

必要要件

• Python 3.8+
• ephemeraldb>=1.0.0
• rich>=13.0.0 (拡張可視化用)
• click>=8.0.0 (CLI用)

🎯 クイックスタート

1. デコレータ使用法

from time_travel_debugger import time_travel_debug

@time_travel_debug
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

result = fibonacci(5)

# デバッグデータにアクセス
session = fibonacci.get_last_session()
timeline = session.get_timeline()
variables = session.get_variables_at_time(0.5)

2. コンテキストマネージャー使用法

from time_travel_debugger import TimeTravelContext

with TimeTravelContext() as debugger:
    # あなたのコードをここに
    result = complex_calculation(10)
    
    # デバッグデータに即座にアクセス
    timeline = debugger.get_timeline()
    state = debugger.get_state_at_time(0.5)

3. グローバルデバッグ

from time_travel_debugger import start_global_debugging, stop_global_debugging

start_global_debugging()

# あなたのコードをここに
result = my_function()

stop_global_debugging()
timeline = get_global_timeline()

🔍 可視化

タイムライン可視化

from time_travel_debugger import print_timeline

print_timeline(debugger.get_timeline())

変数検査

from time_travel_debugger import print_variables_at_time

print_variables_at_time(debugger, timestamp=0.5)

インタラクティブタイムラインエクスプローラー

from time_travel_debugger import interactive_timeline_explorer

interactive_timeline_explorer(debugger)

🖥️ コマンドラインインターフェース

デバッグ付きでスクリプトを実行

ttdbg run my_script.py --timeline --summary

インタラクティブにコードをデバッグ

ttdbg debug --code "print('Hello, World!')" --interactive

保存されたセッションを読み込んで分析

ttdbg load debug_session.json --interactive

保存されたセッション一覧

ttdbg list-sessions

📊 高度な機能

カスタムフィルタリング

def my_filter(frame):
    # 私のモジュール内の関数のみをトレース
    return 'my_module' in frame.f_code.co_filename

@time_travel_debug(filter_func=my_filter)
def my_function():
    # この関数とmy_module内の呼び出しのみがトレースされます
    pass

セッション管理

# セッションを保存
debugger.export_session().export_to_file("my_debug_session.json")

# セッションを読み込み
from time_travel_debugger import load_session
session = load_session("my_debug_session.json")

検索と分析

# 特定の値を持つ変数のすべての状態を検索
states = debugger.search_variables('result', value=42)

# すべての関数呼び出しを取得
call_states = debugger.get_states_by_event('call')

# 特定の関数のすべての状態を取得
func_states = debugger.get_states_by_function('fibonacci')

🏗️ アーキテクチャ

TimeTravelDebuggerは、Pythonのsys.settrace()メカニズムを使用してプログラム実行にフックし、効率的なスコープベース状態ストレージにEphemeralDBを使用します：

1. 実行トレース: すべての行実行、関数呼び出し、リターンをキャプチャ
2. 状態記録: 変数状態とコールスタックを安全にシリアライズ
3. スコープベースストレージ: 関数コンテキスト用にEphemeralDBの階層スコープを使用
4. タイムライン管理: 時系列実行履歴を維持
5. インタラクティブ分析: キャプチャしたデータを探索するためのツールを提供

📈 パフォーマンスの考慮事項

• メモリ使用量: メモリオーバーフローを防ぐためタイムラインサイズが制限されています
• フィルタリング: 関連するコードのみをトレースするためにカスタムフィルターを使用
• セッション管理: 古いセッションは自動的にクリーンアップされます
• 安全なシリアライゼーション: シリアライズ不可能なオブジェクトは適切に処理されます

🔧 設定

環境変数

• TTDBG_MAX_TIMELINE_SIZE: キャプチャする状態の最大数 (デフォルト: 10000)
• TTDBG_USE_RICH: リッチターミナルフォーマットの有効/無効 (デフォルト: true)

プログラマティック設定

debugger = TimeTravelDebugger()
debugger.max_timeline_size = 5000  # タイムラインサイズを制限

📝 使用例

包括的な使用例については examples/ ディレクトリを参照してください：

• basic_example.py: シンプルな関数デバッグ
• fibonacci_example.py: 再帰関数分析
• recursive_example.py: 高度な再帰アルゴリズム

🤝 コントリビューション

1. リポジトリをフォーク
2. 機能ブランチを作成 (git checkout -b feature/amazing-feature)
3. 変更をコミット (git commit -m 'Add amazing feature')
4. ブランチにプッシュ (git push origin feature/amazing-feature)
5. プルリクエストを開く

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細はLICENSEファイルを参照してください。

🙏 謝辞

• 効率的な状態ストレージのために EphemeralDB を使用
• 可視化は Rich によって実装
• CLIインターフェースは Click で構築

🔗 リンク

• ドキュメント
• PyPI パッケージ
• GitHub リポジトリ
• 課題トラッカー

---

ハッピータイムトラベリング！ 🕐✨