SessionSmith 0.1.0__tar.gz → 0.1.2__tar.gz

sessionsmith-0.1.2/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 YutoTAKAGI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

sessionsmith-0.1.2/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: SessionSmith
+Version: 0.1.2
+Summary: Simple session save/load utility for Jupyter notebooks using pickle
+Home-page: https://github.com/yut0takagi/SessionSmith
+Author: YutoTAKAGI
+Author-email: yutotkg.1040@gmail.com
+License: MIT
+Keywords: jupyter notebook session save load pickle serialization algorithm tracer visualization
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering
+Classifier: Framework :: Jupyter
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: visualization
+Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
+Provides-Extra: all
+Requires-Dist: matplotlib>=3.5.0; extra == "all"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# SessionSmith
+
+**SessionSmith** は、Jupyter Notebook や Python 実行時のセッション（変数・オブジェクト）を簡単に保存・復元できる軽量ライブラリです。
+
+## ⚠️ セキュリティ警告
+
+**重要**: このライブラリは`pickle`を使用しています。信頼できないソースからのセッションファイルをロードしないでください。悪意のあるpickleファイルは任意のコードを実行する可能性があります。
+
+- ✅ 信頼できるソースからのファイルのみをロードしてください
+- ✅ 不審なファイルをロードする前に、`verify_session()`で検証してください
+- ✅ 本番環境では、セッションファイルの保存場所へのアクセスを制限してください
+
+## 特徴
+
+- 🚀 **簡単**: たった2行で保存＆復元
+- 📦 **複数形式対応**: pickle（デフォルト）、JSON、MessagePack、HDF5
+- 🔍 **自動検出**: ファイル拡張子から形式を自動検出
+- 🗜️ **圧縮対応**: gzip/bz2圧縮でディスク容量を節約
+- 📊 **情報表示**: セッションの詳細情報を確認
+- 🔄 **比較機能**: 2つのセッションを比較
+- 💾 **自動バックアップ**: 定期的な自動保存
+- 🏷️ **バージョン管理**: Git風のコミット・チェックアウト機能
+- 📈 **アルゴリズムトレーサー**: 1行ごとの変数状態記録・可視化
+- 🎨 **可視化**: アルゴリズムの実行をアニメーションで表示
+
+## インストール
+
+```bash
+pip install SessionSmith
+```
+
+可視化機能を使う場合:
+
+```bash
+pip install SessionSmith[visualization]
+# または
+pip install matplotlib
+```
+
+## クイックスタート
+
+### 基本的な使い方
+
+```python
+from SessionSmith import save_session, load_session
+
+# セッション保存（pickle形式、デフォルト）
+save_session("my_session.pkl")
+
+# セッション復元
+load_session("my_session.pkl")
+
+# JSON形式で保存（安全、可読性）
+save_session("my_session.json")
+
+# MessagePack形式で保存（安全、高速）
+save_session("my_session.msgpack", format="msgpack")
+
+# HDF5形式で保存（科学計算データに最適）
+save_session("my_session.h5", format="hdf5")
+```
+
+### SessionManagerを使う
+
+```python
+from SessionSmith import SessionManager
+
+# マネージャーを作成
+manager = SessionManager()
+
+# 保存
+manager.save("session.pkl")
+
+# ロード
+manager.load("session.pkl")
+```
+
+### バージョン管理（新機能）
+
+```python
+from SessionSmith import SessionManager
+
+# バージョン管理を有効化
+manager = SessionManager(enable_version_control=True)
+
+# 保存（自動的にコミット）
+manager.save("session.pkl", commit_message="Initial state")
+
+# コミット履歴を確認
+manager.log()
+
+# 以前の状態に戻す
+manager.checkout(message="Initial state")
+```
+
+## 主な機能
+
+### 1. 基本的な保存・復元
+- 変数の選択的保存・復元
+- 圧縮サポート（gzip/bz2）
+- Jupyter Notebook内部変数の自動除外
+
+### 2. SessionManagerクラス
+- セッション管理の簡素化
+- 自動バックアップ機能
+- バージョン管理機能（Git風）
+
+### 3. セッション情報・比較
+- セッション情報の表示
+- 2つのセッションの比較
+- セッションファイルの検証
+
+### 4. アルゴリズム実行トレーサー
+- 1行ごとの変数状態記録
+- 可視化（アニメーション）
+- トレースデータの保存・読み込み
+
+### 5. カスタムシリアライザー
+- 特定の型に対するカスタムシリアライゼーション
+- 拡張可能な設計
+
+## 詳細なドキュメント
+
+詳細な使い方は以下のドキュメントを参照してください：
+
+- 📖 [基本的な使い方](docs/getting-started.md) - 保存・復元の詳細
+- 🔄 [バージョン管理](docs/version-control.md) - Git風のバージョン管理機能
+- 📈 [アルゴリズムトレーサー](docs/algorithm-tracer.md) - トレース・可視化機能
+- 📚 [APIリファレンス](docs/api-reference.md) - 全APIの詳細
+
+## 使用例
+
+### 複数形式のサポート
+
+```python
+# pickle形式（デフォルト、互換性重視）
+save_session("session.pkl")
+
+# JSON形式（安全、可読性）
+save_session("session.json")
+
+# MessagePack形式（安全、高速）
+save_session("session.msgpack", format="msgpack")
+
+# HDF5形式（科学計算データに最適）
+save_session("session.h5", format="hdf5")
+```
+
+### 圧縮保存
+
+```python
+# gzip圧縮で保存
+save_session("session.pkl", compress=True)
+```
+
+### セレクティブロード
+
+```python
+# 特定の変数のみ復元
+load_session("session.pkl", include=["data", "model"])
+```
+
+### 自動バックアップ
+
+```python
+manager = SessionManager()
+manager.auto_save(interval=300, file_path="autosave.pkl")
+```
+
+### アルゴリズム可視化
+
+```python
+from SessionSmith import AlgorithmTracer, visualize_algorithm_trace
+
+with AlgorithmTracer(target_variables=["arr"]) as tracer:
+    bubble_sort(arr)
+
+visualize_algorithm_trace(
+    trace_data=tracer.get_trace_data(),
+    output_file="animation.gif",
+    target_variables=["arr"]
+)
+```
+
+## ライセンス
+
+MIT

sessionsmith-0.1.2/SessionSmith/__init__.py

@@ -0,0 +1,33 @@
+"""
+SessionSmith - セッション保存・復元ライブラリ
+
+堅牢で寛容なセッション管理ライブラリです。
+Jupyter Notebook環境での使用に最適化されています。
+"""
+
+from .core import save_session, load_session
+from .manager import SessionManager
+from .info import get_session_info, list_session_variables, print_session_info
+from .compare import compare_sessions, print_comparison
+from .utils import verify_session
+from .serializers import CustomSerializer
+from .tracer import AlgorithmTracer
+from .visualizer import visualize_algorithm_trace, print_trace_summary
+
+__version__ = "0.1.2"
+
+__all__ = [
+    "save_session",
+    "load_session",
+    "SessionManager",
+    "get_session_info",
+    "list_session_variables",
+    "print_session_info",
+    "compare_sessions",
+    "print_comparison",
+    "verify_session",
+    "CustomSerializer",
+    "AlgorithmTracer",
+    "visualize_algorithm_trace",
+    "print_trace_summary",
+]

sessionsmith-0.1.2/SessionSmith/compare.py

@@ -0,0 +1,151 @@
+"""
+セッション比較機能
+"""
+
+from typing import Dict, List, Set, Any, Union
+from pathlib import Path
+import warnings
+from .core import load_session
+from .info import list_session_variables
+
+
+def compare_sessions(
+    file_path1: Union[str, Path],
+    file_path2: Union[str, Path],
+    detailed: bool = False
+) -> Dict[str, Any]:
+    """
+    2つのセッションファイルを比較します
+
+    Args:
+        file_path1: 最初のセッションファイルのパス
+        file_path2: 2番目のセッションファイルのパス
+        detailed: 詳細な比較情報を含めるか（値の変更を検出）
+
+    Returns:
+        dict: 比較結果（追加、削除、変更された変数のリスト）
+        
+    Raises:
+        FileNotFoundError: いずれかのファイルが存在しない場合
+        IOError: ファイルの読み込みに失敗した場合
+    """
+    def _resolve_and_check(path: Union[str, Path]) -> Path:
+        p = Path(path)
+        if not p.exists():
+            raise FileNotFoundError(f"Session file '{p}' not found.")
+        return p
+
+    file_path1 = _resolve_and_check(file_path1)
+    file_path2 = _resolve_and_check(file_path2)
+
+    def _get_variable_set(path: Path) -> Set[str]:
+        try:
+            return set(list_session_variables(path))
+        except Exception as e:
+            raise IOError(f"Failed to read session variables: {str(e)}") from e
+
+    vars1 = _get_variable_set(file_path1)
+    vars2 = _get_variable_set(file_path2)
+
+    # 共通変数、追加、削除を計算
+    common = vars1 & vars2
+    added = vars2 - vars1
+    removed = vars1 - vars2
+
+    result: Dict[str, Any] = {
+        "file1": str(file_path1),
+        "file2": str(file_path2),
+        "common_variables": sorted(list(common)),
+        "added_variables": sorted(list(added)),
+        "removed_variables": sorted(list(removed)),
+    }
+
+    # 詳細な比較（値の変更を検出）
+    if detailed:
+        changed: List[str] = []
+        # 一時的な名前空間でロードして比較
+        temp_globals1: Dict[str, Any] = {}
+        temp_globals2: Dict[str, Any] = {}
+
+        try:
+            load_session(file_path1, globals_dict=temp_globals1)
+            load_session(file_path2, globals_dict=temp_globals2)
+        except Exception as e:
+            raise IOError(f"Failed to load sessions for comparison: {str(e)}") from e
+
+        for var_name in common:
+            val1 = temp_globals1.get(var_name)
+            val2 = temp_globals2.get(var_name)
+
+            # 値が異なるかチェック（簡易的な比較）
+            try:
+                import pickle
+                # 両方の値がNoneの場合は同じとみなす
+                if val1 is None and val2 is None:
+                    continue
+                # 一方がNoneの場合は変更されたとみなす
+                if val1 is None or val2 is None:
+                    changed.append(var_name)
+                    continue
+                # pickleで比較
+                if pickle.dumps(val1) != pickle.dumps(val2):
+                    changed.append(var_name)
+            except Exception as e:
+                # 比較できない場合は変更されたとみなす
+                warnings.warn(
+                    f"Could not compare variable '{var_name}': {str(e)}",
+                    UserWarning
+                )
+                changed.append(var_name)
+
+        result["changed_variables"] = changed
+
+    return result
+
+
+def print_comparison(
+    file_path1: Union[str, Path], 
+    file_path2: Union[str, Path], 
+    detailed: bool = False
+) -> None:
+    """
+    セッション比較結果を整形して表示します
+
+    Args:
+        file_path1: 最初のセッションファイルのパス
+        file_path2: 2番目のセッションファイルのパス
+        detailed: 詳細な比較情報を含めるか
+        
+    Raises:
+        FileNotFoundError: いずれかのファイルが存在しない場合
+        IOError: ファイルの読み込みに失敗した場合
+    """
+    try:
+        result = compare_sessions(file_path1, file_path2, detailed=detailed)
+    except Exception as e:
+        print(f"Error comparing sessions: {e}")
+        raise
+
+    print(f"Comparison: {result['file1']} vs {result['file2']}\n")
+
+    if result['common_variables']:
+        print(f"Common variables ({len(result['common_variables'])}):")
+        for var in result['common_variables']:
+            print(f"  {var}")
+    else:
+        print("Common variables: None")
+
+    if result['added_variables']:
+        print(f"\nAdded variables ({len(result['added_variables'])}):")
+        for var in result['added_variables']:
+            print(f"  + {var}")
+
+    if result['removed_variables']:
+        print(f"\nRemoved variables ({len(result['removed_variables'])}):")
+        for var in result['removed_variables']:
+            print(f"  - {var}")
+
+    if detailed and result.get('changed_variables'):
+        print(f"\nChanged variables ({len(result['changed_variables'])}):")
+        for var in result['changed_variables']:
+            print(f"  ~ {var}")