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

exonware/xwnode/nodes/strategies/{node_treap.py → treap.py}

@@ -41,15 +41,76 @@ class TreapNode:
 
 class TreapStrategy(ANodeTreeStrategy):
     """
-    Treap node strategy for randomized balanced trees.
-    
-    Combines binary search tree and heap properties with randomized
-    priorities for 
+    Treap strategy for randomized balanced binary search trees.
+    
+    WHY Treap (Tree + Heap):
+    - Simpler than AVL/Red-Black (only rotations, no complex rules)
+    - Probabilistic O(log n) expected height (randomized balancing)
+    - Combines BST property (keys) with max-heap property (priorities)
+    - No explicit height/color tracking needed (priorities handle balancing)
+    - Excellent for dynamic scenarios (frequent insert/delete)
+    
+    WHY this implementation:
+    - Random priorities assigned at insertion (1 to 1,000,000 range)
+    - BST property maintained by keys (sorted order)
+    - Max-heap property maintained by priorities (parent > children)
+    - Rotations restore heap property after insertions/deletions
+    - Parent-free implementation (simpler, less memory)
+    
+    Time Complexity:
+    - Insert: O(log n) expected, O(n) worst case (probabilistic)
+    - Search: O(log n) expected, O(n) worst case (probabilistic)
+    - Delete: O(log n) expected, O(n) worst case (probabilistic)
+    - Min/Max: O(log n) - leftmost/rightmost traversal
+    - Iteration: O(n) in sorted order (BST property)
+    
+    Space Complexity: O(n) - one node per key + priority integer
+    
+    Trade-offs:
+    - Advantage: Simpler than AVL/Red-Black (no complex rebalancing rules)
+    - Advantage: Good performance in practice (expected O(log n))
+    - Limitation: Probabilistic (no worst-case guarantees like AVL/RB)
+    - Limitation: Randomness may complicate debugging/testing
+    - Compared to Skip List: More memory efficient, but rotations overhead
+    - Compared to AVL: Simpler, but probabilistic vs deterministic
+    
+    Best for:
+    - When simplicity is valued over worst-case guarantees
+    - Dynamic scenarios with frequent insert/delete
+    - When deterministic balancing is not required
+    - Educational purposes (elegant combination of BST + heap)
+    - Randomized algorithms and Monte Carlo simulations
+    
+    Not recommended for:
+    - Hard real-time systems (probabilistic behavior)
+    - When worst-case guarantees are critical (use AVL/Red-Black)
+    - Adversarial inputs (can be exploited with known priorities)
+    - Deterministic testing environments (randomness complicates tests)
+    - Production systems requiring predictable performance
+    
+    Following eXonware Priorities:
+    1. Usability: Simplest self-balancing tree (no complex rules)
+    2. Maintainability: Clean randomized design, easy to understand
+    3. Performance: Expected O(log n) with low constant factors
+    4. Extensibility: Can support split/merge operations efficiently
+    5. Security: Input validation, random priorities prevent some attacks
+    
+    Industry Best Practices:
+    - Follows Seidel and Aragon original paper (1989)
+    - Maintains BST invariant: left < node < right (keys)
+    - Maintains max-heap invariant: parent.priority > child.priority
+    - Uses rotations to restore heap property after modifications
+    - Provides split/merge operations for advanced use cases
+    
+    Performance Note:
+    Treaps offer EXPECTED O(log n) performance, not worst-case.
+    The randomized priorities ensure good balance with high probability.
+    For guaranteed O(log n), use AVL_TREE or RED_BLACK_TREE instead.
+    Trade-off: Simplicity (Treap) vs Determinism (AVL/Red-Black).
+    """
     
     # Strategy type classification
     STRATEGY_TYPE = NodeType.TREE
-self-balancing behavior.
-    """
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
         """Initialize the treap strategy."""
@@ -267,6 +328,14 @@ self-balancing behavior.
         """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

exonware/xwnode/nodes/strategies/{node_tree_graph_hybrid.py → tree_graph_hybrid.py}

@@ -1,5 +1,5 @@
 """
-#exonware/xwnode/src/exonware/xwnode/strategies/nodes/node_tree_graph_hybrid.py
+#exonware/xwnode/src/exonware/xwnode/nodes/strategies/tree_graph_hybrid.py
 
 Tree Graph Hybrid Strategy Implementation
 
@@ -15,14 +15,17 @@ from typing import Any, Union, List, Dict, Optional, Iterator, Tuple, Callable
 from collections import OrderedDict
 
 from ...defs import NodeMode, NodeTrait
-from ...abc import iNodeStrategy, NodeTrait
-from ...errors import xNodePathError
+from ...contracts import iNodeStrategy
+from ...errors import XWNodePathError
 from exonware.xwsystem import get_logger
 
 logger = get_logger(__name__)
 
+# Import contracts
+from .contracts import NodeType
+
 # Import shared utilities
-from ..utils import (
+from ...common.utils import (
     PathParser, TrieNode, UnionFind, MinHeap,
     create_path_parser, create_performance_tracker
 )
@@ -533,10 +536,12 @@ class TreeGraphHybridStrategy(iNodeStrategy):
     STRATEGY_TYPE = NodeType.HYBRID
 
     
-    def __init__(self):
+    def __init__(self, mode=None, traits=None, **options):
         """Initialize the TreeGraphHybrid strategy."""
+        # Accept standard parameters but don't use them (for compatibility)
         self._root: Optional[TreeGraphNode] = None
         self._node_count = 0
+        self._options = options
         self._edge_count = 0
         self._cache = {}
         self._size = 0
@@ -581,6 +586,9 @@ class TreeGraphHybridStrategy(iNodeStrategy):
     def _calculate_size(self, node: TreeGraphNode) -> int:
         """Calculate the size of the tree."""
         if isinstance(node, TreeGraphValueNode):
+            # Treat None as empty (size 0)
+            if node._value is None:
+                return 0
             return 1
         elif isinstance(node, TreeGraphListNode):
             # For lists, return the number of items
@@ -1107,6 +1115,39 @@ class TreeGraphHybridStrategy(iNodeStrategy):
             return {}
         return self._root._to_native()
 
+    def size(self) -> int:
+        """Get the size/count of items in the tree."""
+        if self._root is None:
+            return 0
+        # For dict root, return number of top-level keys
+        if isinstance(self._root, TreeGraphDictNode):
+            return len(self._root._keys) if hasattr(self._root, '_keys') else len(self._root._children)
+        # For list root, return list length
+        elif isinstance(self._root, TreeGraphListNode):
+            # Check lazy-loaded source data first, then loaded children
+            if hasattr(self._root, '_source_data') and self._root._source_data is not None:
+                return len(self._root._source_data)
+            return len(self._root._children)
+        # For value node, check if it's None (empty)
+        elif isinstance(self._root, TreeGraphValueNode):
+            if hasattr(self._root, '_value') and self._root._value is None:
+                return 0
+            return 1
+        # Default: return 1
+        else:
+            return 1
+    
+    def is_empty(self) -> bool:
+        """Check if the structure is empty."""
+        return self.size() == 0
+    
+    def find(self, path: str) -> Optional[Any]:
+        """Find a value by path (facade compatibility)."""
+        result = self.get(path, default=None)
+        if result is not None and hasattr(result, 'to_native'):
+            return result.to_native()
+        return result
+    
     def get(self, path: str, default: Any = None) -> Optional['TreeGraphHybridStrategy']:
         """Get a child node by path."""
         if self._root is None:

exonware/xwnode/nodes/strategies/trie.py

@@ -19,22 +19,63 @@ class TrieNode:
         self.value: Any = None
 
 
-class xTrieStrategy(ANodeTreeStrategy):
+class TrieStrategy(ANodeTreeStrategy):
+    """
+    Trie (Prefix Tree) strategy for efficient prefix-based string operations.
+    
+    WHY Trie:
+    - O(k) operations where k = key length (independent of dataset size)
+    - Exceptional prefix matching and autocomplete
+    - Natural string organization by shared prefixes
+    - Memory-efficient for datasets with common prefixes
+    
+    WHY this implementation:
+    - Standard trie algorithm with character-by-character nodes
+    - Dictionary-based children for flexible character sets
+    - End-of-word markers for distinguishing prefixes from complete words
+    - Supports full Unicode character set
+    
+    Time Complexity:
+    - Insert: O(k) where k = key length
+    - Search: O(k) - traverse k characters
+    - Delete: O(k) - traverse and cleanup
+    - Prefix search: O(k + m) where m = matching words
+    - Autocomplete: O(k + m) where m = suggestions
+    
+    Space Complexity: O(ALPHABET_SIZE * N * K) worst case, often much better
+    
+    Trade-offs:
+    - Advantage: Time independent of dataset size
+    - Advantage: Natural prefix operations
+    - Advantage: Memory sharing for common prefixes
+    - Limitation: Higher memory than hash for unique keys
+    - Compared to Hash Map: Slower exact match, better for prefixes
+    
+    Best for:
+    - Autocomplete systems
+    - Dictionary/spell check
+    - IP routing tables
+    - String prefix matching
+    
+    Not recommended for:
+    - Non-string keys (use HASH_MAP)
+    - Exact match only (use HASH_MAP)
+    - Numeric keys (use B_TREE)
+    
+    Following eXonware Priorities:
+    1. Security: Bounded by key length
+    2. Usability: Intuitive for string operations
+    3. Maintainability: Well-known algorithm
+    4. Performance: O(k) guaranteed
+    5. Extensibility: Can add compression (Radix)
     """
-    Trie node strategy for efficient string prefix operations.
-    
-    Optimized for prefix matching, autocomplet
     
     # Strategy type classification
     STRATEGY_TYPE = NodeType.TREE
-e, and string searching.
-    """
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
         """Initialize the trie strategy."""
-        super().__init__(data=None, **options)
-        self._mode = NodeMode.TRIE
-        self._traits = traits
+        super().__init__(NodeMode.TRIE, traits, **options)
         self._root = TrieNode()
         self._size = 0
     
@@ -277,3 +318,106 @@ e, and string searching.
         if not node.children:
             return 0
         return 1 + max(self._height_helper(child) for child in node.children.values())
+    
+    # ============================================================================
+    # REQUIRED INTERFACE METHODS (iNodeStrategy)
+    # ============================================================================
+    
+    def create_from_data(self, data: Any) -> 'TrieStrategy':
+        """Create strategy instance from data."""
+        new_strategy = TrieStrategy(self._traits)
+        if isinstance(data, dict):
+            for key, value in data.items():
+                new_strategy.insert(key, value)
+        elif isinstance(data, list):
+            for item in data:
+                new_strategy.insert(item, item)
+        return new_strategy
+    
+    def get(self, path: str, default: Any = None) -> Any:
+        """Get value by path (trie uses find)."""
+        result = self.find(path)
+        return result if result is not None else default
+    
+    def has(self, key: Any) -> bool:
+        """Check if key exists."""
+        return self.find(str(key)) is not None
+    
+    def put(self, path: str, value: Any) -> 'TrieStrategy':
+        """Put value at path."""
+        self.insert(path, value)
+        return self
+    
+    def exists(self, path: str) -> bool:
+        """Check if path exists."""
+        return self.find(path) is not None
+    
+    # Container protocol
+    def __len__(self) -> int:
+        """Get length."""
+        return self._size
+    
+    def __iter__(self) -> Iterator[Any]:
+        """Iterate over values."""
+        return self.values()
+    
+    def __getitem__(self, key: Any) -> Any:
+        """Get item by key."""
+        result = self.find(key)
+        if result is None:
+            raise KeyError(str(key))
+        return result
+    
+    def __setitem__(self, key: Any, value: Any) -> None:
+        """Set item by key."""
+        self.insert(key, value)
+    
+    def __contains__(self, key: Any) -> bool:
+        """Check if key exists."""
+        return self.find(key) is not None
+    
+    # Type checking properties
+    @property
+    def is_leaf(self) -> bool:
+        """Check if this is a leaf node."""
+        return self._size == 0
+    
+    @property
+    def is_list(self) -> bool:
+        """Check if this is a list node."""
+        return False
+    
+    @property
+    def is_dict(self) -> bool:
+        """Check if this is a dict node."""
+        return True  # Trie is dict-like (maps strings to values)
+    
+    @property
+    def is_reference(self) -> bool:
+        """Check if this is a reference node."""
+        return False
+    
+    @property
+    def is_object(self) -> bool:
+        """Check if this is an object node."""
+        return False
+    
+    @property
+    def type(self) -> str:
+        """Get the type of this node."""
+        return "trie"
+    
+    @property
+    def value(self) -> Any:
+        """Get the value of this node."""
+        return self.to_native()
+    
+    @property
+    def strategy_name(self) -> str:
+        """Get strategy name."""
+        return "TRIE"
+    
+    @property
+    def supported_traits(self) -> NodeTrait:
+        """Get supported traits."""
+        return self.get_supported_traits()

exonware/xwnode/nodes/strategies/union_find.py

@@ -77,7 +77,7 @@ class UnionFind:
         return len(self.get_set_members(x))
 
 
-class xUnionFindStrategy(ANodeGraphStrategy):
+class UnionFindStrategy(ANodeGraphStrategy):
     """
     Union-Find node strategy for efficient set operations.
     
@@ -90,15 +90,13 @@ ations on disjoint sets.
     
     def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
         """Initialize the union-find strategy."""
-        super().__init__(data=None, **options)
-        self._mode = NodeMode.UNION_FIND
-        self._traits = traits
+        super().__init__(NodeMode.UNION_FIND, traits, **options)
         self._union_find = UnionFind()
         self._size = 0
     
     def get_supported_traits(self) -> NodeTrait:
         """Get the traits supported by the union-find strategy."""
-        return (NodeTrait.SET_OPERATIONS | NodeTrait.HIERARCHICAL)
+        return (NodeTrait.GRAPH | NodeTrait.HIERARCHICAL | NodeTrait.UNION_FIND)
     
     # ============================================================================
     # CORE OPERATIONS
@@ -122,6 +120,11 @@ ations on disjoint sets.
         # Union-Find doesn't support deletion efficiently
         return False
     
+    def clear(self) -> None:
+        """Clear all data."""
+        self._union_find = UnionFind()
+        self._size = 0
+    
     def size(self) -> int:
         """Get the number of elements."""
         return self._size
@@ -286,3 +289,106 @@ ations on disjoint sets.
             'sets': self._union_find.get_set_count(),
             'memory_usage': f"{self._size * 32} bytes (estimated)"
         }
+    
+    # ============================================================================
+    # REQUIRED INTERFACE METHODS (iNodeStrategy)
+    # ============================================================================
+    
+    def create_from_data(self, data: Any) -> 'UnionFindStrategy':
+        """Create strategy instance from data."""
+        new_strategy = UnionFindStrategy(self._traits)
+        if isinstance(data, dict):
+            for key, value in data.items():
+                new_strategy.insert(key, value)
+        elif isinstance(data, list):
+            for item in data:
+                new_strategy.insert(item, item)
+        return new_strategy
+    
+    def get(self, path: str, default: Any = None) -> Any:
+        """Get value by path."""
+        result = self.find(path)
+        return result if result is not None else default
+    
+    def has(self, key: Any) -> bool:
+        """Check if key exists."""
+        return str(key) in self._parent
+    
+    def put(self, path: str, value: Any) -> 'UnionFindStrategy':
+        """Put value at path."""
+        self.insert(path, value)
+        return self
+    
+    def exists(self, path: str) -> bool:
+        """Check if path exists."""
+        return path in self._union_find.parent
+    
+    # Container protocol
+    def __len__(self) -> int:
+        """Get length."""
+        return self._size
+    
+    def __iter__(self) -> Iterator[Any]:
+        """Iterate over elements."""
+        return self.keys()
+    
+    def __getitem__(self, key: Any) -> Any:
+        """Get item by key."""
+        result = self.find(key)
+        if result is None:
+            raise KeyError(str(key))
+        return result
+    
+    def __setitem__(self, key: Any, value: Any) -> None:
+        """Set item by key."""
+        self.insert(key, value)
+    
+    def __contains__(self, key: Any) -> bool:
+        """Check if key exists."""
+        return str(key) in self._union_find.parent
+    
+    # Type checking properties
+    @property
+    def is_leaf(self) -> bool:
+        """Check if this is a leaf node."""
+        return self._size == 0
+    
+    @property
+    def is_list(self) -> bool:
+        """Check if this is a list node."""
+        return False
+    
+    @property
+    def is_dict(self) -> bool:
+        """Check if this is a dict node."""
+        return True  # Union-find is dict-like (maps elements to sets)
+    
+    @property
+    def is_reference(self) -> bool:
+        """Check if this is a reference node."""
+        return False
+    
+    @property
+    def is_object(self) -> bool:
+        """Check if this is an object node."""
+        return False
+    
+    @property
+    def type(self) -> str:
+        """Get the type of this node."""
+        return "union_find"
+    
+    @property
+    def value(self) -> Any:
+        """Get the value of this node."""
+        return self.to_native()
+    
+    @property
+    def strategy_name(self) -> str:
+        """Get strategy name."""
+        return "UNION_FIND"
+    
+    @property
+    def supported_traits(self) -> NodeTrait:
+        """Get supported traits."""
+        return self.get_supported_traits()