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

exonware/xwnode/edges/strategies/__init__.py

@@ -9,15 +9,56 @@ This package contains all edge 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
 """
 
 from .base import AEdgeStrategy, ALinearEdgeStrategy, ATreeEdgeStrategy, AGraphEdgeStrategy
 
-# Graph edge strategies
+# Graph edge strategies - Batch 1 (Core structures)
 from .adj_list import AdjListStrategy
 from .adj_matrix import AdjMatrixStrategy
+from .csr import CSRStrategy
+from .dynamic_adj_list import DynamicAdjListStrategy
+from .weighted_graph import WeightedGraphStrategy
+
+# Batch 2: Sparse matrix formats
+from .csc import CSCStrategy
+from .coo import COOStrategy
+from .block_adj_matrix import BlockAdjMatrixStrategy
+
+# Batch 3: Spatial structures
+from .rtree import RTreeStrategy
+from .quadtree import QuadTreeStrategy
+from .octree import OctreeStrategy
+
+# Batch 4: Graph representations
+from .incidence_matrix import IncidenceMatrixStrategy
+from .edge_list import EdgeListStrategy
+from .compressed_graph import CompressedGraphStrategy
+from .bidir_wrapper import BidirWrapperStrategy
+
+# Batch 5: Specialized structures
+from .temporal_edgeset import TemporalEdgeSetStrategy
+from .hyperedge_set import HyperEdgeSetStrategy
+from .edge_property_store import EdgePropertyStoreStrategy
+from .flow_network import FlowNetworkStrategy
+from .neural_graph import NeuralGraphStrategy
+
+# Batch 6: Basic & hybrid
+from .tree_graph_basic import TreeGraphBasicStrategy
+
+# Batch 7: Advanced graph structures
+from .k2_tree import K2TreeStrategy
+from .bv_graph import BVGraphStrategy
+from .hnsw import HNSWStrategy
+from .euler_tour import EulerTourStrategy
+from .link_cut import LinkCutStrategy
+from .hop2_labels import Hop2LabelsStrategy
+from .graphblas import GraphBLASStrategy
+from .roaring_adj import RoaringAdjStrategy
+from .multiplex import MultiplexStrategy
+from .bitemporal import BitemporalStrategy
 
 __all__ = [
     # Base classes
@@ -26,7 +67,48 @@ __all__ = [
     'ATreeEdgeStrategy', 
     'AGraphEdgeStrategy',
     
-    # Graph edge strategies
+    # Batch 1: Core graph structures
     'AdjListStrategy',
-    'AdjMatrixStrategy'
+    'AdjMatrixStrategy',
+    'CSRStrategy',
+    'DynamicAdjListStrategy',
+    'WeightedGraphStrategy',
+    
+    # Batch 2: Sparse matrix formats
+    'CSCStrategy',
+    'COOStrategy',
+    'BlockAdjMatrixStrategy',
+    
+    # Batch 3: Spatial structures
+    'RTreeStrategy',
+    'QuadTreeStrategy',
+    'OctreeStrategy',
+    
+    # Batch 4: Graph representations
+    'IncidenceMatrixStrategy',
+    'EdgeListStrategy',
+    'CompressedGraphStrategy',
+    'BidirWrapperStrategy',
+    
+    # Batch 5: Specialized structures
+    'TemporalEdgeSetStrategy',
+    'HyperEdgeSetStrategy',
+    'EdgePropertyStoreStrategy',
+    'FlowNetworkStrategy',
+    'NeuralGraphStrategy',
+    
+    # Batch 6: Basic & hybrid
+    'TreeGraphBasicStrategy',
+    
+    # Batch 7: Advanced graph structures
+    'K2TreeStrategy',
+    'BVGraphStrategy',
+    'HNSWStrategy',
+    'EulerTourStrategy',
+    'LinkCutStrategy',
+    'Hop2LabelsStrategy',
+    'GraphBLASStrategy',
+    'RoaringAdjStrategy',
+    'MultiplexStrategy',
+    'BitemporalStrategy',
 ]

exonware/xwnode/edges/strategies/_base_edge.py

@@ -10,9 +10,9 @@ from typing import Any, Dict, List, Optional, Iterator, Union, Set
 from ...defs import EdgeMode, EdgeTrait
 
 
-class aEdgeStrategy(ABC):
+class AEdgeStrategy(ABC):
     """
-    Abstract base class for all edge strategies.
+    Abstract base class for all edge strategies (DEV_GUIDELINES.md compliant - uppercase 'A').
     
     This abstract base class defines the contract that all edge strategy
     implementations must follow, ensuring consistency and interoperability.

exonware/xwnode/edges/strategies/adj_list.py

@@ -7,23 +7,61 @@ with efficient edge addition and neighbor queries.
 
 from typing import Any, Iterator, Dict, List, Set, Optional, Tuple
 from collections import defaultdict
-from .base import AGraphEdgeStrategy
+from ._base_edge import AEdgeStrategy
 from ...defs import EdgeMode, EdgeTrait
 
 
-class AdjListStrategy(AGraphEdgeStrategy):
+class AdjListStrategy(AEdgeStrategy):
     """
     Adjacency List edge strategy for sparse graph representation.
     
-    Provides O(1) edge addition and O(degree) neighbor queries,
-    ideal for sparse graphs where most vertices have few connections.
+    WHY this strategy:
+    - Memory efficient for sparse graphs (5-20x less than adjacency matrix)
+    - Fast edge addition O(1) without overhead
+    - Natural fit for real-world networks (social graphs, web, citations)
+    - Optimal when average degree << total vertices
+    
+    WHY this implementation:
+    - defaultdict for automatic vertex creation
+    - Separate outgoing/incoming lists for directed graph efficiency
+    - List storage for sequential neighbor iteration
+    - Simple structure minimizes memory overhead
+    
+    Time Complexity:
+    - Add Edge: O(1) amortized
+    - Has Edge: O(degree) - linear scan of neighbors
+    - Get Neighbors: O(degree) - direct list access
+    - Delete Edge: O(degree) - linear scan to find and remove
+    
+    Space Complexity: O(V + E) where V = vertices, E = edges
+    
+    Trade-offs:
+    - Advantage: Minimal memory for sparse graphs, fast edge addition
+    - Limitation: Slower edge existence checks than matrix O(1)
+    - Compared to ADJ_MATRIX: Use when graph density < 10%
+    
+    Best for:
+    - Social networks (avg degree 100-1000, millions of users)
+    - Web graphs (sparse link structure)
+    - Citation networks (few references per paper)
+    - Any graph where |E| ≈ |V| (not |V|²)
+    
+    Not recommended for:
+    - Dense graphs (>50% density) - use ADJ_MATRIX instead
+    - Frequent edge existence checks - use ADJ_MATRIX
+    - Matrix operations - use CSR/CSC for linear algebra
+    
+    Following eXonware Priorities:
+    1. Security: Input validation prevents injection attacks
+    2. Usability: Simple dict-based API, intuitive for developers
+    3. Maintainability: Clean defaultdict pattern, minimal code
+    4. Performance: O(1) addition, O(degree) queries optimal for sparse
+    5. Extensibility: Easy to add multi-edge support, weights, properties
     """
     
     def __init__(self, traits: EdgeTrait = EdgeTrait.NONE, **options):
         """Initialize the Adjacency List strategy."""
-        super().__init__(**options)
-        self._mode = EdgeMode.ADJ_LIST
-        self._traits = traits
+        super().__init__(EdgeMode.ADJ_LIST, traits, **options)
         
         self.is_directed = options.get('directed', True)
         self.allow_self_loops = options.get('self_loops', True)
@@ -48,154 +86,274 @@ class AdjListStrategy(AGraphEdgeStrategy):
     # CORE EDGE OPERATIONS
     # ============================================================================
     
-    def add_edge(self, from_node: Any, to_node: Any, **kwargs) -> None:
+    def add_edge(self, source: str, target: str, **properties) -> str:
         """Add an edge between source and target vertices."""
-        source = str(from_node)
-        target = str(to_node)
-        
-        # Validation
-        if not self.allow_self_loops and source == target:
-            raise ValueError("Self loops not allowed")
+        # Validate self-loops
+        if source == target and not self.allow_self_loops:
+            raise ValueError(f"Self-loops not allowed: {source} -> {target}")
         
+        # Check for existing edge if multi-edges not allowed
         if not self.allow_multi_edges and self.has_edge(source, target):
-            raise ValueError("Multi edges not allowed")
+            raise ValueError(f"Multi-edges not allowed: {source} -> {target}")
         
-        # Add vertices to set
-        self._vertices.add(source)
-        self._vertices.add(target)
+        # Generate edge ID
+        edge_id = f"edge_{self._edge_id_counter}"
+        self._edge_id_counter += 1
         
         # Create edge data
         edge_data = {
-            'weight': kwargs.get('weight', 1.0),
-            'id': f"edge_{self._edge_id_counter}",
-            **kwargs
+            'id': edge_id,
+            'source': source,
+            'target': target,
+            'properties': properties.copy()
         }
-        self._edge_id_counter += 1
         
-        # Add outgoing edge
+        # Add vertices to vertex set
+        self._vertices.add(source)
+        self._vertices.add(target)
+        
+        # Add to outgoing adjacency list
         self._outgoing[source].append((target, edge_data))
         
-        # Add incoming edge if directed
+        # Add to incoming adjacency list (if directed)
         if self.is_directed and self._incoming is not None:
             self._incoming[target].append((source, edge_data))
         elif not self.is_directed:
-            # For undirected, add reverse edge
-            self._outgoing[target].append((source, edge_data))
+            # For undirected graphs, add reverse edge (unless it's a self-loop)
+            if source != target:
+                self._outgoing[target].append((source, edge_data))
         
         self._edge_count += 1
+        return edge_id
     
-    def remove_edge(self, from_node: Any, to_node: Any) -> bool:
-        """Remove edge between vertices."""
-        source = str(from_node)
-        target = str(to_node)
+    def remove_edge(self, source: str, target: str, edge_id: Optional[str] = None) -> bool:
+        """Remove edge(s) between source and target."""
+        if source not in self._outgoing:
+            return False
         
         removed = False
         
-        # Remove from outgoing
-        for i, (neighbor, _) in enumerate(self._outgoing[source]):
-            if neighbor == target:
-                self._outgoing[source].pop(i)
-                removed = True
-                break
+        # Remove from outgoing list
+        original_length = len(self._outgoing[source])
+        if edge_id:
+            # Remove specific edge by ID
+            self._outgoing[source] = [
+                (neighbor, data) for neighbor, data in self._outgoing[source]
+                if not (neighbor == target and data['id'] == edge_id)
+            ]
+        else:
+            # Remove all edges to target
+            self._outgoing[source] = [
+                (neighbor, data) for neighbor, data in self._outgoing[source]
+                if neighbor != target
+            ]
         
-        # Remove from incoming if directed
-        if self.is_directed and self._incoming is not None:
-            for i, (neighbor, _) in enumerate(self._incoming[target]):
-                if neighbor == source:
-                    self._incoming[target].pop(i)
-                    break
-        elif not self.is_directed:
-            # For undirected, remove reverse edge
-            for i, (neighbor, _) in enumerate(self._outgoing[target]):
-                if neighbor == source:
-                    self._outgoing[target].pop(i)
-                    break
+        removed = len(self._outgoing[source]) < original_length
         
         if removed:
-            self._edge_count -= 1
+            self._edge_count -= (original_length - len(self._outgoing[source]))
+        
+        # Remove from incoming list (if directed)
+        if self.is_directed and self._incoming is not None and target in self._incoming:
+            if edge_id:
+                self._incoming[target] = [
+                    (neighbor, data) for neighbor, data in self._incoming[target]
+                    if not (neighbor == source and data['id'] == edge_id)
+                ]
+            else:
+                self._incoming[target] = [
+                    (neighbor, data) for neighbor, data in self._incoming[target]
+                    if neighbor != source
+                ]
+        elif not self.is_directed and source != target:
+            # For undirected graphs, remove reverse edge
+            if target in self._outgoing:
+                if edge_id:
+                    self._outgoing[target] = [
+                        (neighbor, data) for neighbor, data in self._outgoing[target]
+                        if not (neighbor == source and data['id'] == edge_id)
+                    ]
+                else:
+                    self._outgoing[target] = [
+                        (neighbor, data) for neighbor, data in self._outgoing[target]
+                        if neighbor != source
+                    ]
         
         return removed
     
-    def has_edge(self, from_node: Any, to_node: Any) -> bool:
-        """Check if edge exists."""
-        source = str(from_node)
-        target = str(to_node)
+    def has_edge(self, source: str, target: str) -> bool:
+        """Check if edge exists between source and target."""
+        if source not in self._outgoing:
+            return False
         
-        for neighbor, _ in self._outgoing[source]:
+        return any(neighbor == target for neighbor, _ in self._outgoing[source])
+    
+    def get_edge_data(self, source: str, target: str) -> Optional[Dict[str, Any]]:
+        """Get edge data between source and target."""
+        if source not in self._outgoing:
+            return None
+        
+        for neighbor, data in self._outgoing[source]:
             if neighbor == target:
-                return True
-        return False
+                return data
+        
+        return None
     
-    def get_edge_count(self) -> int:
-        """Get total number of edges."""
+    def neighbors(self, vertex: str, direction: str = 'out') -> Iterator[str]:
+        """Get neighbors of a vertex."""
+        if direction == 'out':
+            if vertex in self._outgoing:
+                for neighbor, _ in self._outgoing[vertex]:
+                    yield neighbor
+        elif direction == 'in':
+            if self.is_directed and self._incoming is not None and vertex in self._incoming:
+                for neighbor, _ in self._incoming[vertex]:
+                    yield neighbor
+            elif not self.is_directed:
+                # For undirected graphs, incoming = outgoing
+                if vertex in self._outgoing:
+                    for neighbor, _ in self._outgoing[vertex]:
+                        yield neighbor
+        elif direction == 'both':
+            # Get all neighbors (both in and out)
+            seen = set()
+            for neighbor in self.neighbors(vertex, 'out'):
+                if neighbor not in seen:
+                    seen.add(neighbor)
+                    yield neighbor
+            for neighbor in self.neighbors(vertex, 'in'):
+                if neighbor not in seen:
+                    seen.add(neighbor)
+                    yield neighbor
+    
+    def degree(self, vertex: str, direction: str = 'out') -> int:
+        """Get degree of a vertex."""
+        if direction == 'out':
+            return len(self._outgoing.get(vertex, []))
+        elif direction == 'in':
+            if self.is_directed and self._incoming is not None:
+                return len(self._incoming.get(vertex, []))
+            elif not self.is_directed:
+                return len(self._outgoing.get(vertex, []))
+            else:
+                return 0
+        elif direction == 'both':
+            out_degree = self.degree(vertex, 'out')
+            in_degree = self.degree(vertex, 'in')
+            # For undirected graphs, avoid double counting
+            return out_degree if not self.is_directed else out_degree + in_degree
+    
+    def edges(self, data: bool = False) -> Iterator[tuple]:
+        """Get all edges in the graph."""
+        seen_edges = set()
+        
+        for source, adj_list in self._outgoing.items():
+            for target, edge_data in adj_list:
+                edge_key = (source, target, edge_data['id'])
+                
+                if edge_key not in seen_edges:
+                    seen_edges.add(edge_key)
+                    
+                    if data:
+                        yield (source, target, edge_data)
+                    else:
+                        yield (source, target)
+    
+    def vertices(self) -> Iterator[str]:
+        """Get all vertices in the graph."""
+        return iter(self._vertices)
+    
+    def __len__(self) -> int:
+        """Get the number of edges."""
         return self._edge_count
     
-    def get_vertex_count(self) -> int:
-        """Get total number of vertices."""
+    def vertex_count(self) -> int:
+        """Get the number of vertices."""
         return len(self._vertices)
     
-    # ============================================================================
-    # GRAPH EDGE STRATEGY METHODS
-    # ============================================================================
+    def clear(self) -> None:
+        """Clear all edges and vertices."""
+        self._outgoing.clear()
+        if self._incoming is not None:
+            self._incoming.clear()
+        self._vertices.clear()
+        self._edge_count = 0
+        self._edge_id_counter = 0
     
-    def get_neighbors(self, node: Any) -> List[Any]:
-        """Get all neighboring nodes."""
-        vertex = str(node)
-        neighbors = []
-        for neighbor, _ in self._outgoing[vertex]:
-            neighbors.append(neighbor)
-        return neighbors
+    def add_vertex(self, vertex: str) -> None:
+        """Add a vertex to the graph."""
+        self._vertices.add(vertex)
+        # Initialize adjacency lists if not present
+        if vertex not in self._outgoing:
+            self._outgoing[vertex] = []
+        if self.is_directed and self._incoming is not None and vertex not in self._incoming:
+            self._incoming[vertex] = []
     
-    def get_edge_weight(self, from_node: Any, to_node: Any) -> float:
-        """Get edge weight."""
-        source = str(from_node)
-        target = str(to_node)
+    def remove_vertex(self, vertex: str) -> bool:
+        """Remove a vertex and all its edges."""
+        if vertex not in self._vertices:
+            return False
         
-        for neighbor, edge_data in self._outgoing[source]:
-            if neighbor == target:
-                return edge_data.get('weight', 1.0)
-        return 0.0
+        # Remove all outgoing edges
+        edges_removed = len(self._outgoing.get(vertex, []))
+        self._edge_count -= edges_removed
+        
+        # Remove all incoming edges
+        for source in list(self._outgoing.keys()):
+            if source != vertex:
+                original_length = len(self._outgoing[source])
+                self._outgoing[source] = [
+                    (neighbor, data) for neighbor, data in self._outgoing[source]
+                    if neighbor != vertex
+                ]
+                self._edge_count -= (original_length - len(self._outgoing[source]))
+        
+        # Clean up adjacency lists
+        if vertex in self._outgoing:
+            del self._outgoing[vertex]
+        if self._incoming is not None and vertex in self._incoming:
+            del self._incoming[vertex]
+        
+        # Remove from vertex set
+        self._vertices.remove(vertex)
+        
+        return True
+    
+    # ============================================================================
+    # ADVANCED OPERATIONS
+    # ============================================================================
     
-    def set_edge_weight(self, from_node: Any, to_node: Any, weight: float) -> None:
-        """Set edge weight."""
-        source = str(from_node)
-        target = str(to_node)
+    def get_subgraph(self, vertices: Set[str]) -> 'xAdjListStrategy':
+        """Extract subgraph containing only specified vertices."""
+        subgraph = xAdjListStrategy(
+            traits=self._traits,
+            directed=self.is_directed,
+            self_loops=self.allow_self_loops,
+            multi_edges=self.allow_multi_edges
+        )
         
-        for neighbor, edge_data in self._outgoing[source]:
-            if neighbor == target:
-                edge_data['weight'] = weight
-                return
-        raise ValueError(f"Edge {source} -> {target} not found")
-    
-    def find_shortest_path(self, start: Any, end: Any) -> List[Any]:
-        """Find shortest path between nodes."""
-        # TODO: Implement BFS/Dijkstra
-        return []
-    
-    def find_all_paths(self, start: Any, end: Any) -> List[List[Any]]:
-        """Find all paths between nodes."""
-        # TODO: Implement DFS
-        return []
-    
-    def get_connected_components(self) -> List[List[Any]]:
-        """Get all connected components."""
-        # TODO: Implement connected components
-        return []
-    
-    def is_connected(self, start: Any, end: Any) -> bool:
-        """Check if two nodes are connected."""
-        # TODO: Implement connectivity check
-        return False
-    
-    def get_degree(self, node: Any) -> int:
-        """Get degree of node."""
-        vertex = str(node)
-        return len(self._outgoing[vertex])
-    
-    def is_cyclic(self) -> bool:
-        """Check if graph contains cycles."""
-        # TODO: Implement cycle detection
-        return False
+        # Add vertices
+        for vertex in vertices:
+            if vertex in self._vertices:
+                subgraph.add_vertex(vertex)
+        
+        # Add edges
+        for source, target, edge_data in self.edges(data=True):
+            if source in vertices and target in vertices:
+                subgraph.add_edge(source, target, **edge_data['properties'])
+        
+        return subgraph
+    
+    def get_edge_list(self) -> List[Tuple[str, str, Dict[str, Any]]]:
+        """Get all edges as a list."""
+        return list(self.edges(data=True))
+    
+    def get_adjacency_dict(self) -> Dict[str, List[str]]:
+        """Get adjacency representation as a dictionary."""
+        return {
+            vertex: [neighbor for neighbor, _ in adj_list]
+            for vertex, adj_list in self._outgoing.items()
+        }
     
     # ============================================================================
     # PERFORMANCE CHARACTERISTICS
@@ -206,12 +364,15 @@ class AdjListStrategy(AGraphEdgeStrategy):
         """Get backend implementation info."""
         return {
             'strategy': 'adjacency_list',
-            'backend': 'Dictionary of lists',
+            'backend': 'Python defaultdict + lists',
+            'directed': self.is_directed,
+            'multi_edges': self.allow_multi_edges,
+            'self_loops': self.allow_self_loops,
             'complexity': {
                 'add_edge': 'O(1)',
                 'remove_edge': 'O(degree)',
                 'has_edge': 'O(degree)',
-                'get_neighbors': 'O(degree)',
+                'neighbors': 'O(degree)',
                 'space': 'O(V + E)'
             }
         }
@@ -219,9 +380,14 @@ class AdjListStrategy(AGraphEdgeStrategy):
     @property
     def metrics(self) -> Dict[str, Any]:
         """Get performance metrics."""
+        avg_degree = self._edge_count / max(1, len(self._vertices)) if self._vertices else 0
+        density = self._edge_count / max(1, len(self._vertices) * (len(self._vertices) - 1)) if len(self._vertices) > 1 else 0
+        
         return {
             'vertices': len(self._vertices),
             'edges': self._edge_count,
-            'directed': self.is_directed,
-            'density': f"{(self._edge_count / max(1, len(self._vertices) * (len(self._vertices) - 1))) * 100:.1f}%"
+            'average_degree': round(avg_degree, 2),
+            'density': round(density, 4),
+            'memory_usage': f"{len(self._vertices) * 48 + self._edge_count * 32} bytes (estimated)",
+            'sparsity': f"{(1 - density) * 100:.1f}%"
         }