exonware-xwnode 0.0.1.12__py3-none-any.whl

exonware/xwnode/strategies/nodes/heap.py

@@ -0,0 +1,307 @@
+"""
+Heap Node Strategy Implementation
+
+This module implements the HEAP strategy for priority queue operations.
+"""
+
+import heapq
+from typing import Any, Iterator, List, Optional, Dict
+from .base import ANodeTreeStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class MinHeap:
+    """Min heap implementation."""
+    
+    def __init__(self, max_heap: bool = False):
+        self._heap = []
+        self._max_heap = max_heap
+        self._counter = 0  # For stable sorting
+    
+    def push(self, priority: float, value: Any) -> None:
+        """Push item with priority."""
+        if self._max_heap:
+            priority = -priority
+        heapq.heappush(self._heap, (priority, self._counter, value))
+        self._counter += 1
+    
+    def pop(self) -> Any:
+        """Pop item with highest priority."""
+        if not self._heap:
+            raise IndexError("pop from empty heap")
+        priority, _, value = heapq.heappop(self._heap)
+        return value
+    
+    def peek(self) -> Any:
+        """Peek at highest priority item."""
+        if not self._heap:
+            raise IndexError("peek from empty heap")
+        return self._heap[0][2]
+    
+    def size(self) -> int:
+        """Get heap size."""
+        return len(self._heap)
+    
+    def is_empty(self) -> bool:
+        """Check if heap is empty."""
+        return len(self._heap) == 0
+
+
+class xHeapStrategy(ANodeTreeStrategy):
+    """
+    Heap node strategy for priority queue operations.
+    
+    Optimized for push, pop, and peek operations with configurable min/max behavior.
+    """
+    
+    def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
+        """Initialize the heap strategy."""
+        super().__init__(data=None, **options)
+        self._mode = NodeMode.HEAP
+        self._traits = traits
+        self._is_max_heap = options.get('max_heap', False)
+        self._heap = MinHeap(max_heap=self._is_max_heap)
+        self._size = 0
+    
+    def get_supported_traits(self) -> NodeTrait:
+        """Get the traits supported by the heap strategy."""
+        return (NodeTrait.ORDERED | NodeTrait.PRIORITY_QUEUE)
+    
+    # ============================================================================
+    # CORE OPERATIONS
+    # ============================================================================
+    
+    def insert(self, key: Any, value: Any) -> None:
+        """Store a key-value pair (key is priority, value is data)."""
+        priority = float(key) if key is not None else 0.0
+        data = value if value is not None else key
+        self._heap.push(priority, data)
+        self._size += 1
+    
+    def find(self, key: Any) -> Any:
+        """Find value by priority (not efficient for heaps)."""
+        # Heaps don't support efficient lookup by priority
+        # This is a limitation of the heap data structure
+        return None
+    
+    def delete(self, key: Any) -> bool:
+        """Delete by priority (not efficient for heaps)."""
+        # Heaps don't support efficient deletion by priority
+        # This is a limitation of the heap data structure
+        return False
+    
+    def size(self) -> int:
+        """Get the number of items."""
+        return self._size
+    
+    def is_empty(self) -> bool:
+        """Check if the structure is empty."""
+        return self._size == 0
+    
+    def to_native(self) -> List[Any]:
+        """Convert to native Python list."""
+        # Return all values in priority order
+        result = []
+        temp_heap = MinHeap(max_heap=self._is_max_heap)
+        
+        # Copy heap and extract all values
+        for item in self._heap._heap:
+            priority, counter, value = item
+            temp_heap._heap.append(item)
+        
+        while not temp_heap.is_empty():
+            result.append(temp_heap.pop())
+        
+        return result
+    
+    # ============================================================================
+    # TREE STRATEGY METHODS
+    # ============================================================================
+    
+    def traverse(self, order: str = 'inorder') -> List[Any]:
+        """Traverse heap in priority order."""
+        return self.to_native()
+    
+    def get_min(self) -> Any:
+        """Get minimum priority item."""
+        if self._is_max_heap:
+            return None  # No min in max heap
+        return self._heap.peek() if not self._heap.is_empty() else None
+    
+    def get_max(self) -> Any:
+        """Get maximum priority item."""
+        if not self._is_max_heap:
+            return None  # No max in min heap
+        return self._heap.peek() if not self._heap.is_empty() else None
+    
+    # ============================================================================
+    # AUTO-3 Phase 2 methods
+    # ============================================================================
+    
+    def as_trie(self):
+        """Provide Trie behavioral view."""
+        # TODO: Implement Trie view
+        return self
+    
+    def as_heap(self):
+        """Provide Heap behavioral view."""
+        return self
+    
+    def as_skip_list(self):
+        """Provide SkipList behavioral view."""
+        # TODO: Implement SkipList view
+        return self
+    
+    # ============================================================================
+    # HEAP SPECIFIC OPERATIONS
+    # ============================================================================
+    
+    def push(self, value: Any, priority: float = None) -> str:
+        """Push a value with optional priority."""
+        if priority is None:
+            priority = float(value) if isinstance(value, (int, float)) else 0.0
+        self._heap.push(priority, value)
+        self._size += 1
+        return str(priority)
+    
+    def pop(self) -> Any:
+        """Remove and return highest priority item."""
+        if self._heap.is_empty():
+            raise IndexError("pop from empty heap")
+        value = self._heap.pop()
+        self._size -= 1
+        return value
+    
+    def peek(self) -> Any:
+        """Get highest priority item without removing."""
+        if self._heap.is_empty():
+            raise IndexError("peek from empty heap")
+        return self._heap.peek()
+    
+    def peek_priority(self) -> float:
+        """Get priority of highest priority item."""
+        if self._heap.is_empty():
+            raise IndexError("peek from empty heap")
+        # This is a simplified implementation
+        return 0.0
+    
+    def pushpop(self, value: Any, priority: float = None) -> Any:
+        """Push value and pop highest priority item."""
+        if priority is None:
+            priority = float(value) if isinstance(value, (int, float)) else 0.0
+        
+        if self._heap.is_empty():
+            self._heap.push(priority, value)
+            return None
+        
+        # Push new value
+        self._heap.push(priority, value)
+        # Pop highest priority
+        return self._heap.pop()
+    
+    def replace(self, value: Any, priority: float = None) -> Any:
+        """Replace highest priority item with new value."""
+        if self._heap.is_empty():
+            raise IndexError("replace from empty heap")
+        
+        if priority is None:
+            priority = float(value) if isinstance(value, (int, float)) else 0.0
+        
+        # Pop current highest
+        old_value = self._heap.pop()
+        # Push new value
+        self._heap.push(priority, value)
+        
+        return old_value
+    
+    def heapify(self) -> None:
+        """Heapify the heap (already maintained)."""
+        # Heap is already heapified
+        pass
+    
+    def nlargest(self, n: int) -> List[Any]:
+        """Get n largest items."""
+        if self._is_max_heap:
+            # For max heap, get first n items
+            result = []
+            temp_heap = MinHeap(max_heap=True)
+            
+            # Copy heap
+            for item in self._heap._heap:
+                temp_heap._heap.append(item)
+            
+            for _ in range(min(n, self._size)):
+                if temp_heap.is_empty():
+                    break
+                result.append(temp_heap.pop())
+            
+            return result
+        else:
+            # For min heap, this is not efficient
+            return []
+    
+    def nsmallest(self, n: int) -> List[Any]:
+        """Get n smallest items."""
+        if not self._is_max_heap:
+            # For min heap, get first n items
+            result = []
+            temp_heap = MinHeap(max_heap=False)
+            
+            # Copy heap
+            for item in self._heap._heap:
+                temp_heap._heap.append(item)
+            
+            for _ in range(min(n, self._size)):
+                if temp_heap.is_empty():
+                    break
+                result.append(temp_heap.pop())
+            
+            return result
+        else:
+            # For max heap, this is not efficient
+            return []
+    
+    # ============================================================================
+    # ITERATION
+    # ============================================================================
+    
+    def keys(self) -> Iterator[str]:
+        """Get all priorities as strings."""
+        # This is not efficient for heaps
+        return iter([])
+    
+    def values(self) -> Iterator[Any]:
+        """Get all values."""
+        return iter(self.to_native())
+    
+    def items(self) -> Iterator[tuple[str, Any]]:
+        """Get all priority-value pairs."""
+        # This is not efficient for heaps
+        return iter([])
+    
+    # ============================================================================
+    # PERFORMANCE CHARACTERISTICS
+    # ============================================================================
+    
+    @property
+    def backend_info(self) -> Dict[str, Any]:
+        """Get backend implementation info."""
+        return {
+            'strategy': 'HEAP',
+            'backend': 'Python heapq',
+            'complexity': {
+                'push': 'O(log n)',
+                'pop': 'O(log n)',
+                'peek': 'O(1)',
+                'heapify': 'O(n)'
+            }
+        }
+    
+    @property
+    def metrics(self) -> Dict[str, Any]:
+        """Get performance metrics."""
+        return {
+            'size': self._size,
+            'is_max_heap': self._is_max_heap,
+            'memory_usage': f"{self._size * 24} bytes (estimated)"
+        }

exonware/xwnode/strategies/nodes/linked_list.py

@@ -0,0 +1,232 @@
+"""
+Linked List Node Strategy Implementation
+
+This module implements the LINKED_LIST strategy for efficient
+insertions and deletions with sequential access patterns.
+"""
+
+from typing import Any, Iterator, List, Dict, Optional
+from .base import ANodeLinearStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class ListNode:
+    """Node in the doubly linked list."""
+    
+    def __init__(self, key: str, value: Any):
+        self.key = key
+        self.value = value
+        self.prev: Optional['ListNode'] = None
+        self.next: Optional['ListNode'] = None
+
+
+class LinkedListStrategy(ANodeLinearStrategy):
+    """
+    Linked List node strategy for efficient insertions and deletions.
+    
+    Provides O(1) insertions/deletions at known positions with
+    sequential access patterns optimized for iteration.
+    """
+    
+    def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
+        """Initialize the Linked List strategy."""
+        super().__init__(data=None, **options)
+        self._mode = NodeMode.LINKED_LIST
+        self._traits = traits
+        
+        self.doubly_linked = options.get('doubly_linked', True)
+        
+        # Doubly linked list with sentinel nodes
+        self._head = ListNode("HEAD", None)
+        self._tail = ListNode("TAIL", None)
+        self._head.next = self._tail
+        self._tail.prev = self._head
+        
+        # Quick access mapping
+        self._key_to_node: Dict[str, ListNode] = {}
+        self._size = 0
+    
+    def get_supported_traits(self) -> NodeTrait:
+        """Get the traits supported by the linked list strategy."""
+        return (NodeTrait.ORDERED | NodeTrait.INDEXED)
+    
+    # ============================================================================
+    # CORE OPERATIONS
+    # ============================================================================
+    
+    def insert(self, key: Any, value: Any) -> None:
+        """Insert key-value pair."""
+        key_str = str(key)
+        if key_str in self._key_to_node:
+            # Update existing
+            self._key_to_node[key_str].value = value
+        else:
+            # Insert new node at end
+            self._insert_at_end(key_str, value)
+    
+    def find(self, key: Any) -> Any:
+        """Find value by key."""
+        key_str = str(key)
+        node = self._key_to_node.get(key_str)
+        return node.value if node else None
+    
+    def delete(self, key: Any) -> bool:
+        """Delete by key."""
+        key_str = str(key)
+        if key_str in self._key_to_node:
+            self._remove_node(self._key_to_node[key_str])
+            del self._key_to_node[key_str]
+            return True
+        return False
+    
+    def size(self) -> int:
+        """Get size."""
+        return self._size
+    
+    def is_empty(self) -> bool:
+        """Check if empty."""
+        return self._size == 0
+    
+    def to_native(self) -> List[Any]:
+        """Convert to native list."""
+        result = []
+        current = self._head.next
+        while current != self._tail:
+            result.append(current.value)
+            current = current.next
+        return result
+    
+    # ============================================================================
+    # LINEAR STRATEGY METHODS
+    # ============================================================================
+    
+    def push_front(self, value: Any) -> None:
+        """Add element to front."""
+        self._insert_after(self._head, str(self._size), value)
+    
+    def push_back(self, value: Any) -> None:
+        """Add element to back."""
+        self._insert_before(self._tail, str(self._size), value)
+    
+    def pop_front(self) -> Any:
+        """Remove element from front."""
+        if self._size == 0:
+            raise IndexError("pop from empty list")
+        first_node = self._head.next
+        value = first_node.value
+        self._remove_node(first_node)
+        return value
+    
+    def pop_back(self) -> Any:
+        """Remove element from back."""
+        if self._size == 0:
+            raise IndexError("pop from empty list")
+        last_node = self._tail.prev
+        value = last_node.value
+        self._remove_node(last_node)
+        return value
+    
+    def get_at_index(self, index: int) -> Any:
+        """Get element at index."""
+        if index < 0 or index >= self._size:
+            raise IndexError("list index out of range")
+        
+        current = self._head.next
+        for _ in range(index):
+            current = current.next
+        return current.value
+    
+    def set_at_index(self, index: int, value: Any) -> None:
+        """Set element at index."""
+        if index < 0 or index >= self._size:
+            raise IndexError("list index out of range")
+        
+        current = self._head.next
+        for _ in range(index):
+            current = current.next
+        current.value = value
+    
+    # ============================================================================
+    # AUTO-3 Phase 1 methods
+    # ============================================================================
+    
+    def as_linked_list(self):
+        """Provide LinkedList behavioral view."""
+        return self
+    
+    def as_stack(self):
+        """Provide Stack behavioral view."""
+        # TODO: Implement Stack view
+        return self
+    
+    def as_queue(self):
+        """Provide Queue behavioral view."""
+        # TODO: Implement Queue view
+        return self
+    
+    def as_deque(self):
+        """Provide Deque behavioral view."""
+        # TODO: Implement Deque view
+        return self
+    
+    # ============================================================================
+    # HELPER METHODS
+    # ============================================================================
+    
+    def _insert_at_end(self, key: str, value: Any) -> None:
+        """Insert new node at the end."""
+        self._insert_before(self._tail, key, value)
+    
+    def _insert_after(self, node: ListNode, key: str, value: Any) -> None:
+        """Insert new node after specified node."""
+        new_node = ListNode(key, value)
+        new_node.next = node.next
+        new_node.prev = node
+        node.next.prev = new_node
+        node.next = new_node
+        self._key_to_node[key] = new_node
+        self._size += 1
+    
+    def _insert_before(self, node: ListNode, key: str, value: Any) -> None:
+        """Insert new node before specified node."""
+        new_node = ListNode(key, value)
+        new_node.prev = node.prev
+        new_node.next = node
+        node.prev.next = new_node
+        node.prev = new_node
+        self._key_to_node[key] = new_node
+        self._size += 1
+    
+    def _remove_node(self, node: ListNode) -> None:
+        """Remove node from list."""
+        node.prev.next = node.next
+        node.next.prev = node.prev
+        self._size -= 1
+    
+    # ============================================================================
+    # PERFORMANCE CHARACTERISTICS
+    # ============================================================================
+    
+    @property
+    def backend_info(self) -> Dict[str, Any]:
+        """Get backend implementation info."""
+        return {
+            'strategy': 'LINKED_LIST',
+            'backend': 'Doubly linked list',
+            'complexity': {
+                'get': 'O(n)',
+                'put': 'O(1)',
+                'insert': 'O(1) at known position',
+                'delete': 'O(1) at known position',
+                'search': 'O(n)'
+            }
+        }
+    
+    @property
+    def metrics(self) -> Dict[str, Any]:
+        """Get performance metrics."""
+        return {
+            'size': self._size,
+            'memory_usage': f"{self._size * 32} bytes (estimated)",
+            'doubly_linked': self.doubly_linked
+        }