exonware-xwnode 0.0.1.22__py3-none-any.whl → 0.0.1.24__py3-none-any.whl

exonware/xwnode/nodes/strategies/{node_persistent_tree.py → persistent_tree.py}

@@ -1,12 +1,24 @@
-#exonware\xnode\strategies\impls\node_persistent_tree.py
+#exonware/xwnode/src/exonware/xwnode/nodes/strategies/persistent_tree.py
 """
 Persistent Tree Node Strategy Implementation
 
+Status: Production Ready
+True Purpose: Immutable functional tree with structural sharing and versioning
+Complexity: O(log n) operations with structural sharing
+Production Features: ✓ Immutability, ✓ Structural Sharing, ✓ Version Management, ✓ Snapshots
+
 This module implements the PERSISTENT_TREE strategy for immutable functional
 trees with structural sharing and lock-free concurrency.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.24
+Generation Date: October 12, 2025
 """
 
 from typing import Any, Iterator, List, Dict, Optional, Tuple
+import time
 from .base import ANodeTreeStrategy
 from .contracts import NodeType
 from ...defs import NodeMode, NodeTrait
@@ -53,7 +65,7 @@ sharing unchanged nodes.
     """
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
-        """Initialize the persistent tree strategy."""
+        """Initialize the persistent tree strategy with version management."""
         super().__init__(NodeMode.PERSISTENT_TREE, traits, **options)
         
         self.case_sensitive = options.get('case_sensitive', True)
@@ -64,6 +76,11 @@ sharing unchanged nodes.
         self._size = 0
         self._version = 0
         
+        # Version management
+        self._version_history: List[Tuple[int, PersistentTreeNode, float]] = []  # version, root, timestamp
+        self._max_versions = options.get('max_versions', 100)  # Retention limit
+        self._version_retention_policy = options.get('retention_policy', 'keep_recent')  # or 'keep_all'
+        
         # Statistics
         self._total_allocations = 0
         self._total_shares = 0
@@ -261,10 +278,14 @@ sharing unchanged nodes.
     # ============================================================================
     
     def put(self, key: Any, value: Any = None) -> None:
-        """Store a key-value pair, returning new tree."""
+        """Store a key-value pair, creating new version."""
         if not isinstance(key, str):
             key = str(key)
         
+        # Save current version to history before modification
+        if self._root is not None:
+            self._save_version()
+        
         new_root, inserted = self._insert_node(self._root, key, value)
         self._root = new_root
         
@@ -313,6 +334,14 @@ sharing unchanged nodes.
         """Get number of key-value pairs."""
         return self._size
     
+    def __len__(self) -> int:
+        """Get number of key-value pairs."""
+        return self._size
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert to native Python dict."""
+        return dict(self.items())
+    
     def is_empty(self) -> bool:
         """Check if tree is empty."""
         return self._root is None
@@ -343,17 +372,17 @@ sharing unchanged nodes.
     # PERSISTENT TREE SPECIFIC OPERATIONS
     # ============================================================================
     
-    def snapshot(self) -> 'xPersistentTreeStrategy':
+    def snapshot(self) -> 'PersistentTreeStrategy':
         """Create a snapshot of the current tree."""
-        snapshot = xPersistentTreeStrategy(self.traits, **self.options)
+        snapshot = PersistentTreeStrategy(self.traits, **self.options)
         snapshot._root = self._root  # Share root (structural sharing)
         snapshot._size = self._size
         snapshot._version = self._version
         return snapshot
     
-    def merge(self, other: 'xPersistentTreeStrategy') -> 'xPersistentTreeStrategy':
+    def merge(self, other: 'PersistentTreeStrategy') -> 'PersistentTreeStrategy':
         """Merge with another persistent tree."""
-        result = xPersistentTreeStrategy(self.traits, **self.options)
+        result = PersistentTreeStrategy(self.traits, **self.options)
         
         # Copy all items from both trees
         for key, value in self.items():
@@ -363,21 +392,132 @@ sharing unchanged nodes.
         
         return result
     
+    # ============================================================================
+    # VERSION MANAGEMENT (Production Feature)
+    # ============================================================================
+    
+    def _save_version(self) -> None:
+        """Save current version to history."""
+        if self._root is None:
+            return
+        
+        # Add current state to version history
+        self._version_history.append((
+            self._version,
+            self._root,
+            time.time()
+        ))
+        
+        # Apply retention policy
+        if self._version_retention_policy == 'keep_recent':
+            # Keep only last N versions
+            if len(self._version_history) > self._max_versions:
+                self._version_history = self._version_history[-self._max_versions:]
+    
     def get_version(self) -> int:
         """Get current version number."""
         return self._version
     
+    def get_version_history(self) -> List[Tuple[int, float]]:
+        """Get list of available versions with timestamps."""
+        return [(v, ts) for v, _, ts in self._version_history]
+    
+    def restore_version(self, version: int) -> bool:
+        """
+        Restore to a specific version.
+        
+        Args:
+            version: Version number to restore
+            
+        Returns:
+            True if version was found and restored
+        """
+        for v, root, _ in self._version_history:
+            if v == version:
+                self._root = root  # Structural sharing
+                self._version = version
+                self._size = len(list(self._inorder_traversal(root)))
+                return True
+        return False
+    
+    def compare_versions(self, version1: int, version2: int) -> Dict[str, Any]:
+        """
+        Compare two versions and return differences.
+        
+        Args:
+            version1: First version number
+            version2: Second version number
+            
+        Returns:
+            Dict with added, removed, and modified keys
+        """
+        # Find roots for both versions
+        root1 = None
+        root2 = None
+        
+        for v, root, _ in self._version_history:
+            if v == version1:
+                root1 = root
+            if v == version2:
+                root2 = root
+        
+        if root1 is None or root2 is None:
+            return {'error': 'Version not found'}
+        
+        # Get items from both versions
+        items1 = dict(self._inorder_traversal(root1))
+        items2 = dict(self._inorder_traversal(root2))
+        
+        # Calculate differences
+        keys1 = set(items1.keys())
+        keys2 = set(items2.keys())
+        
+        return {
+            'added': list(keys2 - keys1),
+            'removed': list(keys1 - keys2),
+            'modified': [k for k in (keys1 & keys2) if items1[k] != items2[k]],
+            'unchanged': [k for k in (keys1 & keys2) if items1[k] == items2[k]]
+        }
+    
+    def cleanup_old_versions(self, keep_count: int = 10) -> int:
+        """
+        Clean up old versions, keeping only most recent.
+        
+        Args:
+            keep_count: Number of versions to keep
+            
+        Returns:
+            Number of versions removed
+        """
+        if len(self._version_history) <= keep_count:
+            return 0
+        
+        removed = len(self._version_history) - keep_count
+        self._version_history = self._version_history[-keep_count:]
+        return removed
+    
     def get_stats(self) -> Dict[str, Any]:
-        """Get performance statistics."""
+        """Get performance statistics with version management."""
         return {
             'size': self._size,
             'height': self._get_height(self._root),
             'max_height': self._max_height,
             'version': self._version,
+            'version_history_size': len(self._version_history),
+            'max_versions': self._max_versions,
+            'retention_policy': self._version_retention_policy,
             'total_allocations': self._total_allocations,
             'total_shares': self._total_shares,
             'sharing_ratio': self._total_shares / max(1, self._total_allocations),
             'strategy': 'PERSISTENT_TREE',
-            'backend': 'Immutable AVL tree with structural sharing',
+            'backend': 'Immutable AVL tree with structural sharing and version management',
+            'production_features': [
+                'Immutability',
+                'Structural Sharing',
+                'Version History',
+                'Version Comparison',
+                'Version Restoration',
+                'Automatic Retention Policy'
+            ],
             'traits': [trait.name for trait in NodeTrait if self.has_trait(trait)]
         }