Travel-Debugger 1.1.0
実行状態記録を用いた革命的なPythonタイムトラベルデバッグライブラリ
Requires Python: >=3.8

# TimeTravelDebugger 🕐

実行状態記録を用いた革命的なPythonタイムトラベルデバッグライブラリ

## 🚀 特徴

- **完全実行記録**: すべての変数変更、関数呼び出し、実行ステップをキャプチャ
- **タイムトラベルインターフェース**: プログラムの実行タイムラインをナビゲート
- **多様な使用パターン**: デコレータ、コンテキストマネージャー、グローバルデバッグ
- **リッチ可視化**: 美しいターミナルベースのタイムラインと変数検査
- **EphemeralDB統合**: パフォーマンス向上のための効率的なスコープベース状態ストレージ
- **セッション管理**: デバッグセッションの保存、読み込み、共有
- **CLIツール**: スクリプトデバッグ用のコマンドラインインターフェース
- **インタラクティブエクスプローラー**: 実行状態をインタラクティブにナビゲート

## 📦 インストール

```bash
pip install Travel-Debugger
```

### 必要要件

- Python 3.8+
- ephemeraldb>=1.0.0
- rich>=13.0.0 (拡張可視化用)
- click>=8.0.0 (CLI用)

## 🎯 クイックスタート

### 1. デコレータ使用法

```python
from 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. コンテキストマネージャー使用法

```python
from 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. グローバルデバッグ

```python
from Travel_Debugger import start_global_debugging, stop_global_debugging

start_global_debugging()

# あなたのコードをここに
result = my_function()

stop_global_debugging()
timeline = get_global_timeline()
```

## 🔍 可視化

### タイムライン可視化

```python
from Travel_Debugger import print_timeline

print_timeline(debugger.get_timeline())
```

### 変数検査

```python
from Travel_Debugger import print_variables_at_time

print_variables_at_time(debugger, timestamp=0.5)
```

### インタラクティブタイムラインエクスプローラー

```python
from Travel_Debugger import interactive_timeline_explorer

interactive_timeline_explorer(debugger)
```

## 🖥️ コマンドラインインターフェース

### デバッグ付きでスクリプトを実行

```bash
ttdbg run my_script.py --timeline --summary
```

### インタラクティブにコードをデバッグ

```bash
ttdbg debug --code "print('Hello, World!')" --interactive
```

### 保存されたセッションを読み込んで分析

```bash
ttdbg load debug_session.json --interactive
```

### 保存されたセッション一覧

```bash
ttdbg list-sessions
```

## 📊 高度な機能

### カスタムフィルタリング

```python
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
```

### セッション管理

```python
# セッションを保存
debugger.export_session().export_to_file("my_debug_session.json")

# セッションを読み込み
from Travel_Debugger import load_session
session = load_session("my_debug_session.json")
```

### 検索と分析

```python
# 特定の値を持つ変数のすべての状態を検索
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)

### プログラマティック設定

```python
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](https://github.com/tikipiya/EphemeralDB) を使用
- 可視化は [Rich](https://github.com/Textualize/rich) によって実装
- CLIインターフェースは [Click](https://github.com/pallets/click) で構築

## 🔗 リンク

- [ドキュメント](https://timetraveldebugger.readthedocs.io/)
- [PyPI パッケージ](https://pypi.org/project/time-travel-debugger/)
- [GitHub リポジトリ](https://github.com/timetraveldebugger/time-travel-debugger)
- [課題トラッカー](https://github.com/timetraveldebugger/time-travel-debugger/issues)

---

**ハッピータイムトラベリング！ 🕐✨**