exonware-xwnode 0.0.1.12__py3-none-any.whl

exonware/xwnode/strategies/nodes/base.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""
+Node Strategy Base Classes
+
+This module defines the abstract base classes for all node strategy implementations:
+- ANodeStrategy: Base strategy for all node implementations
+- ANodeLinearStrategy: Phase 1 - Linear data structure capabilities
+- ANodeTreeStrategy: Phase 2 - Tree data structure capabilities  
+- ANodeGraphStrategy: Phase 3&4 - Graph data structure capabilities
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.12
+Generation Date: January 2, 2025
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional, List, Dict, Iterator
+
+from ...contracts import iNodeStrategy
+from ...errors import XWNodeTypeError, XWNodeValueError
+
+
+class ANodeStrategy(ABC):
+    """Base strategy for all node implementations."""
+    
+    def __init__(self, data: Any = None, **options):
+        """Initialize node strategy."""
+        self._data = data
+        self._options = options
+        self._mode = options.get('mode', 'AUTO')
+        self._traits = options.get('traits', None)
+    
+    @abstractmethod
+    def insert(self, key: Any, value: Any) -> None:
+        """Insert key-value pair."""
+        pass
+    
+    @abstractmethod
+    def find(self, key: Any) -> Optional[Any]:
+        """Find value by key."""
+        pass
+    
+    @abstractmethod
+    def delete(self, key: Any) -> bool:
+        """Delete by key."""
+        pass
+    
+    @abstractmethod
+    def size(self) -> int:
+        """Get size of structure."""
+        pass
+    
+    @abstractmethod
+    def is_empty(self) -> bool:
+        """Check if structure is empty."""
+        pass
+    
+    @abstractmethod
+    def to_native(self) -> Any:
+        """Convert to native Python object."""
+        pass
+    
+    def get_mode(self) -> str:
+        """Get strategy mode."""
+        return self._mode
+    
+    def get_traits(self):
+        """Get strategy traits."""
+        return self._traits
+
+
+class ANodeLinearStrategy(ANodeStrategy):
+    """Phase 1: Linear data structure capabilities."""
+    
+    def push_front(self, value: Any) -> None:
+        """Add element to front."""
+        raise NotImplementedError("Subclasses must implement push_front")
+    
+    def push_back(self, value: Any) -> None:
+        """Add element to back."""
+        raise NotImplementedError("Subclasses must implement push_back")
+    
+    def pop_front(self) -> Any:
+        """Remove element from front."""
+        raise NotImplementedError("Subclasses must implement pop_front")
+    
+    def pop_back(self) -> Any:
+        """Remove element from back."""
+        raise NotImplementedError("Subclasses must implement pop_back")
+    
+    def get_at_index(self, index: int) -> Any:
+        """Get element at index."""
+        raise NotImplementedError("Subclasses must implement get_at_index")
+    
+    def set_at_index(self, index: int, value: Any) -> None:
+        """Set element at index."""
+        raise NotImplementedError("Subclasses must implement set_at_index")
+    
+    # AUTO-3 Phase 1 methods
+    def as_linked_list(self):
+        """Provide LinkedList behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_linked_list")
+    
+    def as_stack(self):
+        """Provide Stack behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_stack")
+    
+    def as_queue(self):
+        """Provide Queue behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_queue")
+    
+    def as_deque(self):
+        """Provide Deque behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_deque")
+
+
+class ANodeGraphStrategy(ANodeStrategy):
+    """Phase 3&4: Graph data structure capabilities."""
+    
+    def add_edge(self, from_node: Any, to_node: Any, weight: float = 1.0) -> None:
+        """Add edge between nodes."""
+        raise NotImplementedError("Subclasses must implement add_edge")
+    
+    def remove_edge(self, from_node: Any, to_node: Any) -> bool:
+        """Remove edge between nodes."""
+        raise NotImplementedError("Subclasses must implement remove_edge")
+    
+    def has_edge(self, from_node: Any, to_node: Any) -> bool:
+        """Check if edge exists."""
+        raise NotImplementedError("Subclasses must implement has_edge")
+    
+    def find_path(self, start: Any, end: Any) -> List[Any]:
+        """Find path between nodes."""
+        raise NotImplementedError("Subclasses must implement find_path")
+    
+    def get_neighbors(self, node: Any) -> List[Any]:
+        """Get neighboring nodes."""
+        raise NotImplementedError("Subclasses must implement get_neighbors")
+    
+    def get_edge_weight(self, from_node: Any, to_node: Any) -> float:
+        """Get edge weight."""
+        raise NotImplementedError("Subclasses must implement get_edge_weight")
+    
+    # AUTO-3 Phase 3&4 methods
+    def as_union_find(self):
+        """Provide Union-Find behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_union_find")
+    
+    def as_neural_graph(self):
+        """Provide Neural Graph behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_neural_graph")
+    
+    def as_flow_network(self):
+        """Provide Flow Network behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_flow_network")
+
+
+class ANodeMatrixStrategy(ANodeStrategy):
+    """Matrix-based data structure capabilities."""
+    
+    def get_dimensions(self) -> tuple:
+        """Get matrix dimensions (rows, cols)."""
+        raise NotImplementedError("Subclasses must implement get_dimensions")
+    
+    def get_at_position(self, row: int, col: int) -> Any:
+        """Get element at matrix position."""
+        raise NotImplementedError("Subclasses must implement get_at_position")
+    
+    def set_at_position(self, row: int, col: int, value: Any) -> None:
+        """Set element at matrix position."""
+        raise NotImplementedError("Subclasses must implement set_at_position")
+    
+    def get_row(self, row: int) -> List[Any]:
+        """Get entire row."""
+        raise NotImplementedError("Subclasses must implement get_row")
+    
+    def get_column(self, col: int) -> List[Any]:
+        """Get entire column."""
+        raise NotImplementedError("Subclasses must implement get_column")
+    
+    def transpose(self) -> 'ANodeMatrixStrategy':
+        """Transpose the matrix."""
+        raise NotImplementedError("Subclasses must implement transpose")
+    
+    def multiply(self, other: 'ANodeMatrixStrategy') -> 'ANodeMatrixStrategy':
+        """Matrix multiplication."""
+        raise NotImplementedError("Subclasses must implement multiply")
+    
+    def add(self, other: 'ANodeMatrixStrategy') -> 'ANodeMatrixStrategy':
+        """Matrix addition."""
+        raise NotImplementedError("Subclasses must implement add")
+    
+    # Matrix-specific behavioral views
+    def as_adjacency_matrix(self):
+        """Provide Adjacency Matrix behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_adjacency_matrix")
+    
+    def as_incidence_matrix(self):
+        """Provide Incidence Matrix behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_incidence_matrix")
+    
+    def as_sparse_matrix(self):
+        """Provide Sparse Matrix behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_sparse_matrix")
+
+
+class ANodeTreeStrategy(ANodeGraphStrategy):
+    """Phase 2: Tree data structure capabilities."""
+    
+    def insert(self, key: Any, value: Any) -> None:
+        """Insert with tree ordering."""
+        raise NotImplementedError("Subclasses must implement insert")
+    
+    def find(self, key: Any) -> Optional[Any]:
+        """Find with tree traversal."""
+        raise NotImplementedError("Subclasses must implement find")
+    
+    def delete(self, key: Any) -> bool:
+        """Delete with tree restructuring."""
+        raise NotImplementedError("Subclasses must implement delete")
+    
+    def traverse(self, order: str = 'inorder') -> List[Any]:
+        """Traverse tree in specified order."""
+        raise NotImplementedError("Subclasses must implement traverse")
+    
+    def get_min(self) -> Any:
+        """Get minimum key."""
+        raise NotImplementedError("Subclasses must implement get_min")
+    
+    def get_max(self) -> Any:
+        """Get maximum key."""
+        raise NotImplementedError("Subclasses must implement get_max")
+    
+    # AUTO-3 Phase 2 methods
+    def as_trie(self):
+        """Provide Trie behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_trie")
+    
+    def as_heap(self):
+        """Provide Heap behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_heap")
+    
+    def as_skip_list(self):
+        """Provide SkipList behavioral view."""
+        raise NotImplementedError("Subclasses must implement as_skip_list")

exonware/xwnode/strategies/nodes/deque.py

@@ -0,0 +1,200 @@
+"""
+Deque Strategy Implementation
+
+Implements a double-ended queue using Python's deque for efficient operations at both ends.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.12
+Generation Date: 07-Sep-2025
+"""
+
+from typing import Any, Iterator, Optional, Dict, Union
+from collections import deque
+from .base import ANodeLinearStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class DequeStrategy(ANodeLinearStrategy):
+    """
+    Deque (Double-ended queue) node strategy for efficient operations at both ends.
+    
+    Provides O(1) operations for adding/removing elements at both front and back,
+    ideal for sliding window algorithms and breadth-first search.
+    """
+    
+    def __init__(self):
+        """Initialize an empty deque."""
+        super().__init__()
+        self._deque: deque = deque()
+        self._mode = NodeMode.DEQUE
+        self._traits = {NodeTrait.DOUBLE_ENDED, NodeTrait.FAST_INSERT, NodeTrait.FAST_DELETE}
+    
+    def insert(self, key: str, value: Any) -> None:
+        """Insert an item (defaults to back)."""
+        self._deque.append((key, value))
+    
+    def find(self, key: str) -> Optional[Any]:
+        """Find an item in the deque (O(n) operation)."""
+        for k, v in self._deque:
+            if k == key:
+                return v
+        return None
+    
+    def delete(self, key: str) -> bool:
+        """Remove an item from the deque."""
+        for i, (k, v) in enumerate(self._deque):
+            if k == key:
+                del self._deque[i]
+                return True
+        return False
+    
+    def size(self) -> int:
+        """Get the number of items in the deque."""
+        return len(self._deque)
+    
+    def is_empty(self) -> bool:
+        """Check if the deque is empty."""
+        return len(self._deque) == 0
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert deque to native dictionary format."""
+        return dict(self._deque)
+    
+    def from_native(self, data: Dict[str, Any]) -> None:
+        """Load deque from native dictionary format."""
+        self._deque = deque(data.items())
+    
+    def append(self, value: Any) -> None:
+        """Add an item to the right end."""
+        key = f"item_{len(self._deque)}"
+        self._deque.append((key, value))
+    
+    def appendleft(self, value: Any) -> None:
+        """Add an item to the left end."""
+        key = f"item_{len(self._deque)}"
+        self._deque.appendleft((key, value))
+    
+    def pop(self) -> Optional[Any]:
+        """Remove and return an item from the right end."""
+        if self.is_empty():
+            return None
+        key, value = self._deque.pop()
+        return value
+    
+    def popleft(self) -> Optional[Any]:
+        """Remove and return an item from the left end."""
+        if self.is_empty():
+            return None
+        key, value = self._deque.popleft()
+        return value
+    
+    def peek_right(self) -> Optional[Any]:
+        """Peek at the rightmost item without removing it."""
+        if self.is_empty():
+            return None
+        key, value = self._deque[-1]
+        return value
+    
+    def peek_left(self) -> Optional[Any]:
+        """Peek at the leftmost item without removing it."""
+        if self.is_empty():
+            return None
+        key, value = self._deque[0]
+        return value
+    
+    def rotate(self, n: int = 1) -> None:
+        """Rotate the deque n steps to the right (positive) or left (negative)."""
+        self._deque.rotate(n)
+    
+    def reverse(self) -> None:
+        """Reverse the deque in place."""
+        self._deque.reverse()
+    
+    def clear(self) -> None:
+        """Clear all items from the deque."""
+        self._deque.clear()
+    
+    def get_at_index(self, index: int) -> Optional[Any]:
+        """Get item at specific index."""
+        if 0 <= index < len(self._deque):
+            key, value = self._deque[index]
+            return value
+        return None
+    
+    def set_at_index(self, index: int, value: Any) -> bool:
+        """Set item at specific index."""
+        if 0 <= index < len(self._deque):
+            key, old_value = self._deque[index]
+            self._deque[index] = (key, value)
+            return True
+        return False
+    
+    def push_front(self, value: Any) -> None:
+        """Push to front (left end)."""
+        self.appendleft(value)
+    
+    def push_back(self, value: Any) -> None:
+        """Push to back (right end)."""
+        self.append(value)
+    
+    def remove(self, value: Any) -> bool:
+        """Remove the first occurrence of a value."""
+        for i, (key, v) in enumerate(self._deque):
+            if v == value:
+                del self._deque[i]
+                return True
+        return False
+    
+    def count(self, value: Any) -> int:
+        """Count occurrences of a value."""
+        count = 0
+        for key, v in self._deque:
+            if v == value:
+                count += 1
+        return count
+    
+    def extend(self, values: list) -> None:
+        """Extend the deque with values from the right."""
+        for value in values:
+            self.append(value)
+    
+    def extendleft(self, values: list) -> None:
+        """Extend the deque with values from the left."""
+        for value in reversed(values):
+            self.appendleft(value)
+    
+    def __iter__(self) -> Iterator[Any]:
+        """Iterate through deque items (left to right)."""
+        for key, value in self._deque:
+            yield value
+    
+    def __repr__(self) -> str:
+        """String representation of the deque."""
+        return f"DequeStrategy(size={len(self._deque)}, left={self.peek_left()}, right={self.peek_right()})"
+    
+    # Required abstract methods from base classes
+    def pop_front(self) -> Any:
+        """Remove element from front (same as popleft for deque)."""
+        return self.popleft()
+    
+    def pop_back(self) -> Any:
+        """Remove element from back (same as pop for deque)."""
+        return self.pop()
+    
+    def as_linked_list(self):
+        """Provide LinkedList behavioral view."""
+        return self
+    
+    def as_stack(self):
+        """Provide Stack behavioral view."""
+        return self
+    
+    def as_queue(self):
+        """Provide Queue behavioral view."""
+        return self
+    
+    def as_deque(self):
+        """Provide Deque behavioral view."""
+        return self

exonware/xwnode/strategies/nodes/hash_map.py

@@ -0,0 +1,135 @@
+"""
+Hash Map Node Strategy Implementation
+
+This module implements the HASH_MAP strategy for fast key-value operations
+using Python's built-in dictionary.
+"""
+
+from typing import Any, Iterator, Dict, List, Optional, Union
+from .base import ANodeStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class HashMapStrategy(ANodeStrategy):
+    """
+    Hash Map node strategy for fast O(1) key-value operations.
+    
+    Uses Python's built-in dictionary for optimal performance
+    with associative operations.
+    """
+    
+    def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
+        """Initialize the hash map strategy."""
+        super().__init__(data=None, **options)
+        self._mode = NodeMode.HASH_MAP
+        self._traits = traits
+        self._data: Dict[str, Any] = {}
+    
+    def get_supported_traits(self) -> NodeTrait:
+        """Get the traits supported by the hash map strategy."""
+        return (NodeTrait.INDEXED | NodeTrait.HIERARCHICAL)
+    
+    # ============================================================================
+    # CORE OPERATIONS
+    # ============================================================================
+    
+    def insert(self, key: Any, value: Any) -> None:
+        """Store a key-value pair."""
+        str_key = str(key)
+        self._data[str_key] = value
+    
+    def find(self, key: Any) -> Any:
+        """Retrieve a value by key."""
+        str_key = str(key)
+        return self._data.get(str_key)
+    
+    def delete(self, key: Any) -> bool:
+        """Remove a key-value pair."""
+        str_key = str(key)
+        if str_key in self._data:
+            del self._data[str_key]
+            return True
+        return False
+    
+    def size(self) -> int:
+        """Get the number of items."""
+        return len(self._data)
+    
+    def is_empty(self) -> bool:
+        """Check if the structure is empty."""
+        return len(self._data) == 0
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert to native Python dictionary."""
+        return self._data.copy()
+    
+    # ============================================================================
+    # ITERATION
+    # ============================================================================
+    
+    def keys(self) -> Iterator[str]:
+        """Get all keys."""
+        return iter(self._data.keys())
+    
+    def values(self) -> Iterator[Any]:
+        """Get all values."""
+        return iter(self._data.values())
+    
+    def items(self) -> Iterator[tuple[str, Any]]:
+        """Get all key-value pairs."""
+        return iter(self._data.items())
+    
+    # ============================================================================
+    # HASH MAP SPECIFIC OPERATIONS
+    # ============================================================================
+    
+    def get(self, key: Any, default: Any = None) -> Any:
+        """Get value with default."""
+        str_key = str(key)
+        return self._data.get(str_key, default)
+    
+    def setdefault(self, key: Any, default: Any = None) -> Any:
+        """Set default value if key doesn't exist."""
+        str_key = str(key)
+        return self._data.setdefault(str_key, default)
+    
+    def update(self, other: Dict[str, Any]) -> None:
+        """Update with another dictionary."""
+        self._data.update(other)
+    
+    def pop(self, key: Any, default: Any = None) -> Any:
+        """Remove and return value."""
+        str_key = str(key)
+        return self._data.pop(str_key, default)
+    
+    def clear(self) -> None:
+        """Clear all data."""
+        self._data.clear()
+    
+    # ============================================================================
+    # PERFORMANCE CHARACTERISTICS
+    # ============================================================================
+    
+    @property
+    def backend_info(self) -> Dict[str, Any]:
+        """Get backend implementation info."""
+        return {
+            'strategy': 'HASH_MAP',
+            'backend': 'Python dict',
+            'complexity': {
+                'get': 'O(1)',
+                'put': 'O(1)',
+                'delete': 'O(1)',
+                'keys': 'O(n)',
+                'values': 'O(n)'
+            }
+        }
+    
+    @property
+    def metrics(self) -> Dict[str, Any]:
+        """Get performance metrics."""
+        return {
+            'size': len(self._data),
+            'memory_usage': f"{len(self._data) * 24} bytes (estimated)",
+            'load_factor': 'N/A (Python dict)'
+        }