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

exonware/xwnode/edges/strategies/{edge_tree_graph_basic.py → tree_graph_basic.py}

@@ -7,11 +7,11 @@ in tree+graph hybrid structures, providing minimal graph capabilities.
 """
 
 from typing import Any, Dict, List, Optional, Set, Tuple, Iterator
-from ._base_edge import aEdgeStrategy
+from ._base_edge import AEdgeStrategy
 from ...defs import EdgeMode, EdgeTrait
 
 
-class xTreeGraphBasicStrategy(aEdgeStrategy):
+class TreeGraphBasicStrategy(AEdgeStrategy):
     """
     Basic edge strategy for tree+graph hybrid structures.
     
@@ -34,8 +34,13 @@ class xTreeGraphBasicStrategy(aEdgeStrategy):
         self._max_degree = 0
     
     def get_supported_traits(self) -> EdgeTrait:
-        """Get the traits supported by the tree-graph basic strategy."""
-        return (EdgeTrait.DIRECTED | EdgeTrait.WEIGHTED | EdgeTrait.MULTI)
+        """
+        Get the traits supported by the tree-graph basic strategy.
+        
+        Root cause fixed: Missing HIERARCHICAL trait for tree structure support.
+        Priority: Maintainability #3 - Correct trait reporting
+        """
+        return (EdgeTrait.DIRECTED | EdgeTrait.WEIGHTED | EdgeTrait.MULTI | EdgeTrait.HIERARCHICAL)
     
     def _update_degree_stats(self, node: str) -> None:
         """Update degree statistics."""
@@ -89,12 +94,23 @@ class xTreeGraphBasicStrategy(aEdgeStrategy):
     # ============================================================================
     
     def add_edge(self, source: str, target: str, weight: float = 1.0, 
-                 metadata: Optional[Dict[str, Any]] = None) -> bool:
-        """Add an edge between source and target nodes."""
+                 metadata: Optional[Dict[str, Any]] = None, **properties) -> str:
+        """
+        Add an edge between source and target nodes.
+        
+        Root cause fixed: Method returned bool instead of edge_id string, violating
+        strategy interface contract.
+        
+        Priority: Maintainability #3 - Consistent strategy interface
+        
+        Returns:
+            Edge ID string
+        """
         if not isinstance(source, str) or not isinstance(target, str):
             raise ValueError("Source and target must be strings")
         
-        return self._add_edge_internal(source, target, weight, metadata)
+        self._add_edge_internal(source, target, weight, metadata)
+        return f"edge_{source}_{target}"
     
     def remove_edge(self, source: str, target: str) -> bool:
         """Remove an edge between source and target nodes."""
@@ -131,6 +147,18 @@ class xTreeGraphBasicStrategy(aEdgeStrategy):
         
         return list(self._edges.get(node, set()))
     
+    def get_children(self, node: str) -> List[str]:
+        """
+        Get children of a node in tree structure.
+        
+        Root cause fixed: Missing method for tree navigation API.
+        Priority: Usability #2 - Complete tree navigation interface
+        
+        Returns:
+            List of child node identifiers
+        """
+        return self.get_outgoing(node)
+    
     def get_degree(self, node: str) -> int:
         """Get the degree (number of neighbors) of a node."""
         if not isinstance(node, str):
@@ -195,6 +223,49 @@ class xTreeGraphBasicStrategy(aEdgeStrategy):
         """Iterate over all edges."""
         yield from self.edges()
     
+    def __len__(self) -> int:
+        """
+        Get number of edges.
+        
+        Root cause fixed: Missing abstract method implementation.
+        Priority: Maintainability #3 - Complete interface implementation
+        """
+        return self._edge_count
+    
+    def degree(self, vertex: str) -> int:
+        """
+        Get degree of a vertex.
+        
+        Root cause fixed: Missing abstract method implementation.
+        Priority: Maintainability #3 - Complete interface implementation
+        """
+        return self.get_degree(vertex)
+    
+    def neighbors(self, vertex: str, direction: str = 'out') -> Iterator[str]:
+        """
+        Get neighbors of a vertex.
+        
+        Root cause fixed: Missing abstract method implementation.
+        Priority: Maintainability #3 - Complete interface implementation
+        """
+        if direction == 'out':
+            yield from self.get_outgoing(vertex)
+        elif direction == 'in':
+            yield from self.get_incoming(vertex)
+        else:
+            # Both directions
+            yield from self.get_outgoing(vertex)
+            yield from self.get_incoming(vertex)
+    
+    def vertices(self) -> Iterator[str]:
+        """
+        Iterate over all vertices.
+        
+        Root cause fixed: Missing abstract method implementation.
+        Priority: Maintainability #3 - Complete interface implementation
+        """
+        yield from self.get_nodes()
+    
     # ============================================================================
     # TREE-GRAPH BASIC SPECIFIC OPERATIONS
     # ============================================================================

exonware/xwnode/edges/strategies/{edge_weighted_graph.py → weighted_graph.py}

@@ -7,7 +7,7 @@ edge weights, optimized for network algorithms and shortest path computations.
 """
 
 from typing import Any, Dict, List, Optional, Set, Tuple, Iterator
-from ._base_edge import aEdgeStrategy
+from ._base_edge import AEdgeStrategy
 from ...defs import EdgeMode, EdgeTrait
 from ...errors import XWNodeUnsupportedCapabilityError
 import threading
@@ -42,12 +42,54 @@ class WeightedEdge:
         return f"WeightedEdge({self.source} -> {self.target}, weight={self.weight})"
 
 
-class xWeightedGraphStrategy(aEdgeStrategy):
+class WeightedGraphStrategy(AEdgeStrategy):
     """
     Weighted graph edge strategy for graphs with numerical edge weights.
     
-    Provides efficient storage and retrieval of weighted edges with support
-    for network algorithms and shortest path computations.
+    WHY this strategy:
+    - Real-world networks have weighted edges (distances, costs, capacities, probabilities)
+    - Enables classic algorithms: Dijkstra, Bellman-Ford, Kruskal, Prim
+    - Optimized for network optimization problems
+    - First-class weight support (not retrofitted properties)
+    
+    WHY this implementation:
+    - Adjacency list backbone for sparse weight storage
+    - WeightedEdge class encapsulates edge with weight
+    - Hash caching for performance in set operations
+    - Thread-safe operations with optional locking
+    
+    Time Complexity:
+    - Add Edge: O(1) - append to adjacency list
+    - Has Edge: O(degree) - linear scan of neighbors
+    - Get Weight: O(degree) - find edge then access weight
+    - Shortest Path: O((V+E) log V) - Dijkstra with heap
+    - Delete Edge: O(degree) - find and remove from list
+    
+    Space Complexity: O(V + E) - sparse storage
+    
+    Trade-offs:
+    - Advantage: Natural weight handling, algorithm-ready
+    - Limitation: Slower than plain adjacency list (weight objects)
+    - Compared to ADJ_LIST: Use when weights drive decisions
+    
+    Best for:
+    - Transportation networks (roads, flights with distances)
+    - Network flow problems (capacity constraints)
+    - Routing and pathfinding (GPS, logistics)
+    - Cost optimization (supply chain, telecommunications)
+    - Recommendation systems (similarity scores)
+    
+    Not recommended for:
+    - Unweighted graphs - use plain ADJ_LIST
+    - Simple connectivity checks - overhead unnecessary
+    - Extremely large graphs - use CSR/CSC for better compression
+    
+    Following eXonware Priorities:
+    1. Security: Weight validation prevents invalid values
+    2. Usability: Natural API for weighted operations
+    3. Maintainability: Clean WeightedEdge abstraction
+    4. Performance: Optimized Dijkstra implementation
+    5. Extensibility: Easy to add new weighted algorithms
     """
     
     def __init__(self, traits: EdgeTrait = EdgeTrait.NONE, **options):
@@ -113,18 +155,29 @@ class xWeightedGraphStrategy(aEdgeStrategy):
     # CORE OPERATIONS
     # ============================================================================
     
-    def add_edge(self, source: str, target: str, weight: float = None, data: Any = None) -> bool:
-        """Add a weighted edge between source and target."""
+    def add_edge(self, source: str, target: str, weight: float = None, data: Any = None, **properties) -> str:
+        """
+        Add a weighted edge between source and target.
+        
+        Root cause fixed: Method returned bool instead of edge_id string, violating
+        strategy interface contract.
+        
+        Priority: Maintainability #3 - Consistent strategy interface
+        
+        Returns:
+            Edge ID string
+        """
         if not isinstance(source, str) or not isinstance(target, str):
-            return False
+            raise ValueError("Source and target must be strings")
         
         if weight is None:
-            weight = self.default_weight
+            weight = properties.get('weight', self.default_weight)
         
         weight = self._normalize_weight(weight)
         
         with self._lock:
             edge_key = (source, target)
+            edge_id = f"edge_{source}_{target}"
             
             # Check if edge already exists
             if edge_key in self._edges:
@@ -134,7 +187,7 @@ class xWeightedGraphStrategy(aEdgeStrategy):
                 old_edge.data = data
                 self._total_weight_updates += 1
                 self._update_weight_stats(weight)
-                return False
+                return edge_id
             
             # Create new edge
             edge = WeightedEdge(source, target, weight, data)
@@ -152,7 +205,7 @@ class xWeightedGraphStrategy(aEdgeStrategy):
             self._edge_count += 1
             self._total_edges_added += 1
             self._update_weight_stats(weight)
-            return True
+            return edge_id
     
     def get_edge(self, source: str, target: str) -> Optional[WeightedEdge]:
         """Get edge between source and target."""
@@ -168,6 +221,27 @@ class xWeightedGraphStrategy(aEdgeStrategy):
         edge = self.get_edge(source, target)
         return edge.weight if edge else None
     
+    def get_edge_data(self, source: str, target: str) -> Optional[Dict[str, Any]]:
+        """
+        Get edge data between source and target vertices.
+        
+        Root cause fixed: Missing method caused test failures.
+        Returns dict with weight and properties for interface compliance.
+        
+        Priority: Usability #2 - Complete API implementation
+        
+        Returns:
+            Dict with 'weight' and other edge properties, or None if edge doesn't exist
+        """
+        edge = self.get_edge(source, target)
+        if edge is None:
+            return None
+        
+        return {
+            'weight': edge.weight,
+            'data': edge.data
+        }
+    
     def set_edge_weight(self, source: str, target: str, weight: float) -> bool:
         """Set weight of edge between source and target."""
         if not isinstance(source, str) or not isinstance(target, str):
@@ -409,3 +483,107 @@ class xWeightedGraphStrategy(aEdgeStrategy):
                 'backend': 'Weighted graph with numerical edge weights',
                 'traits': [trait.name for trait in EdgeTrait if self.has_trait(trait)]
             }
+    
+    # ============================================================================
+    # REQUIRED INTERFACE METHODS
+    # ============================================================================
+    
+    def __len__(self) -> int:
+        """Get number of edges."""
+        return self._edge_count
+    
+    def vertices(self) -> Set[str]:
+        """Get all vertices."""
+        vertices = set()
+        for source in self._adjacency.keys():
+            vertices.add(source)
+        for target in self._reverse_adjacency.keys():
+            vertices.add(target)
+        return vertices
+    
+    def edges(self) -> Iterator[Tuple[str, str, float]]:
+        """Iterate over all edges with weights."""
+        for edge in self._edges.values():
+            yield (edge.source, edge.target, edge.weight)
+    
+    def neighbors(self, node: str) -> List[str]:
+        """Get neighbors of a node (delegates to get_neighbors)."""
+        return self.get_neighbors(node)
+    
+    def get_degree(self, node: str) -> int:
+        """
+        Get degree of a node (number of edges).
+        
+        Root cause fixed: Method was calling itself recursively. Implemented proper logic.
+        Priority: Maintainability #3 - Correct method implementation
+        """
+        if not isinstance(node, str):
+            return 0
+        
+        with self._lock:
+            if self.directed:
+                out_degree = len(self._adjacency.get(node, {}))
+                in_degree = len(self._reverse_adjacency.get(node, {}))
+                return out_degree + in_degree
+            else:
+                return len(self._adjacency.get(node, {}))
+    
+    def degree(self, node: str) -> int:
+        """Get degree of a node."""
+        return self.get_degree(node)
+    
+    def shortest_path(self, source: str, target: str) -> Optional[List[str]]:
+        """
+        Find shortest path between source and target using Dijkstra's algorithm.
+        
+        Root cause fixed: Missing method for weighted graph algorithms.
+        Also fixed: Don't require target to be in adjacency (it might only have incoming edges).
+        Priority: Performance #4 - Efficient shortest path computation
+        
+        Returns:
+            List of vertices in shortest path, or None if no path exists
+        """
+        if source not in self._adjacency:
+            return None
+        
+        if source == target:
+            return [source]
+        
+        import heapq
+        
+        with self._lock:
+            # Dijkstra's algorithm
+            distances = {source: 0.0}
+            previous = {}
+            pq = [(0.0, source)]
+            visited = set()
+            
+            while pq:
+                current_dist, current = heapq.heappop(pq)
+                
+                if current in visited:
+                    continue
+                visited.add(current)
+                
+                if current == target:
+                    # Reconstruct path
+                    path = []
+                    while current is not None:
+                        path.append(current)
+                        current = previous.get(current)
+                    return list(reversed(path))
+                
+                if current in self._adjacency:
+                    for neighbor, weight in self._adjacency[current].items():
+                        if neighbor not in visited:
+                            new_dist = current_dist + weight
+                            if neighbor not in distances or new_dist < distances[neighbor]:
+                                distances[neighbor] = new_dist
+                                previous[neighbor] = current
+                                heapq.heappush(pq, (new_dist, neighbor))
+            
+            return None
+    
+    def remove_edge(self, from_node: str, to_node: str) -> bool:
+        """Remove an edge (delegates to delete_edge)."""
+        return self.delete_edge(from_node, to_node)

exonware/xwnode/errors.py

@@ -327,12 +327,9 @@ class XWNodePresetError(XWNodeStrategyError):
         }
         
         # Import here to avoid circular imports
-        try:
-            from .defs import list_presets
-            available = list_presets()
-            suggestions = [f"Available presets: {', '.join(available)}"]
-        except ImportError:
-            suggestions = ["Check preset name spelling"]
+        from .defs import list_presets
+        available = list_presets()
+        suggestions = [f"Available presets: {', '.join(available)}"]
         
         super().__init__(message,
                         error_code="PRESET_ERROR",

exonware/xwnode/facade.py

@@ -9,7 +9,7 @@ a clean, intuitive interface.
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.21
+Version: 0.0.1.23
 Generation Date: 07-Sep-2025
 """
 
@@ -61,6 +61,25 @@ class XWNode(XWNodeBase):
             from .common.utils.simple import SimpleNodeStrategy
             self._strategy = SimpleNodeStrategy.create_from_data(self._data or {})
     
+    # ============================================================================
+    # FACTORY METHODS
+    # ============================================================================
+    
+    @classmethod
+    def from_native(cls, data: Any, mode: str = 'AUTO', **options) -> 'XWNode':
+        """
+        Create XWNode from native Python data.
+        
+        Args:
+            data: Native Python data (dict, list, etc.)
+            mode: Strategy mode to use
+            **options: Additional configuration options
+        
+        Returns:
+            XWNode instance containing the data
+        """
+        return cls(data=data, mode=mode, **options)
+    
     # ============================================================================
     # CORE OPERATIONS
     # ============================================================================
@@ -275,24 +294,6 @@ class XWNode(XWNodeBase):
             return f"XWNode(mode='{self._mode}', size={self.size()})"
 
 
-class XWQuery:
-    """Query interface for XWNode."""
-    
-    def __init__(self, node: XWNode):
-        """Initialize query interface."""
-        self._node = node
-    
-    def find(self, pattern: str) -> List[Any]:
-        """Find items matching pattern."""
-        # TODO: Implement pattern matching
-        return []
-    
-    def filter(self, predicate) -> List[Any]:
-        """Filter items by predicate."""
-        # TODO: Implement filtering
-        return []
-
-
 class XWFactory:
     """Factory for creating XWNode instances."""
     
@@ -444,7 +445,6 @@ def empty_node() -> XWNode:
 __all__ = [
     'XWNode',
     'XWEdge',
-    'XWQuery', 
     'XWFactory',
     'create_node',
     'from_dict',

exonware/xwnode/nodes/strategies/__init__.py

@@ -9,7 +9,7 @@ This package contains all node strategy implementations organized by type:
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.21
+Version: 0.0.1.23
 Generation Date: January 2, 2025
 """
 
@@ -20,13 +20,23 @@ from .array_list import ArrayListStrategy
 from .linked_list import LinkedListStrategy
 
 # Tree strategies
-from .trie import xTrieStrategy
-from .heap import xHeapStrategy
-from .aho_corasick import xAhoCorasickStrategy
+from .trie import TrieStrategy
+from .heap import HeapStrategy
+from .aho_corasick import AhoCorasickStrategy
 
 # Graph strategies
 from .hash_map import HashMapStrategy
-from .union_find import xUnionFindStrategy
+from .union_find import UnionFindStrategy
+
+# Advanced specialized strategies
+from .veb_tree import VebTreeStrategy
+from .dawg import DawgStrategy
+from .hopscotch_hash import HopscotchHashStrategy
+from .interval_tree import IntervalTreeStrategy
+from .kd_tree import KdTreeStrategy
+from .rope import RopeStrategy
+from .crdt_map import CRDTMapStrategy
+from .bloomier_filter import BloomierFilterStrategy
 
 __all__ = [
     # Base classes
@@ -40,11 +50,21 @@ __all__ = [
     'LinkedListStrategy',
     
     # Tree strategies
-    'xTrieStrategy',
-    'xHeapStrategy',
-    'xAhoCorasickStrategy',
+    'TrieStrategy',
+    'HeapStrategy',
+    'AhoCorasickStrategy',
     
     # Graph strategies
     'HashMapStrategy',
-    'xUnionFindStrategy'
+    'UnionFindStrategy',
+    
+    # Advanced specialized strategies
+    'VebTreeStrategy',
+    'DawgStrategy',
+    'HopscotchHashStrategy',
+    'IntervalTreeStrategy',
+    'KdTreeStrategy',
+    'RopeStrategy',
+    'CRDTMapStrategy',
+    'BloomierFilterStrategy',
 ]