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

exonware/__init__.py

@@ -4,7 +4,7 @@ exonware package - Enterprise-grade Python framework ecosystem
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.22
+Version: 0.0.1.23
 Generation Date: 2025-01-03
 
 This is a namespace package allowing multiple exonware subpackages

exonware/xwnode/__init__.py

@@ -10,12 +10,11 @@ data handling libraries like xdata.
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.22
+Version: 0.0.1.23
 Generation Date: 07-Sep-2025
 
 Main Classes:
     XWNode: The primary interface for working with hierarchical data
-    XWQuery: Query interface for searching and filtering nodes
     XWFactory: Factory for creating XWNode instances
     
 Exceptions:
@@ -57,7 +56,7 @@ Example:
 # IMPORTS - Standard Python Imports (No Defensive Code!)
 # =============================================================================
 from .facade import (
-    XWNode, XWEdge, XWQuery, XWFactory,
+    XWNode, XWEdge, XWFactory,
     # A+ Usability Presets
     create_with_preset, list_available_presets,
     # Performance Modes
@@ -68,9 +67,12 @@ from .errors import (
     XWNodeSecurityError, XWNodeLimitError, XWNodePathSecurityError
 )
 from .config import XWNodeConfig, get_config, set_config
+from .defs import NodeMode, EdgeMode, NodeTrait, EdgeTrait, GraphOptimization
+# Note: QueryMode and QueryTrait are in xwquery.defs module
+from .common.graph import XWGraphManager
 
 # xwsystem lazy install functionality
-from exonware.xwsystem.utils.lazy_install import xwimport
+from exonware.xwsystem.utils.lazy_package import xwimport
 from exonware.xwsystem.monitoring import get_metrics as get_xwsystem_metrics, reset_metrics as reset_xwsystem_metrics
 
 # Version info
@@ -84,7 +86,6 @@ __all__ = [
     # Main classes
     'XWNode',
     'XWEdge',
-    'XWQuery',
     'XWFactory',
     
     # A+ Usability Presets
@@ -102,6 +103,18 @@ __all__ = [
     'get_config',
     'set_config',
     
+    # Enums and Types
+    'NodeMode',
+    'EdgeMode',
+    'QueryMode',
+    'NodeTrait',
+    'EdgeTrait',
+    'QueryTrait',
+    'GraphOptimization',
+    
+    # Graph Optimization
+    'XWGraphManager',
+    
     # Lazy Install
     'xwimport',
     

exonware/xwnode/add_strategy_types.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""
+Add STRATEGY_TYPE to All Node Strategies
+
+This script automatically adds STRATEGY_TYPE declarations to all node strategy files
+based on the inheritance audit.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.23
+Generation Date: 08-Oct-2025
+"""
+
+import re
+from pathlib import Path
+from typing import Dict
+
+# Map strategy files to their NodeType
+STRATEGY_TYPE_MAP = {
+    # LINEAR
+    'array_list.py': 'LINEAR',
+    'linked_list.py': 'LINEAR',
+    'stack.py': 'LINEAR',
+    'queue.py': 'LINEAR',
+    'deque.py': 'LINEAR',
+    'priority_queue.py': 'LINEAR',
+    
+    # TREE
+    'hash_map.py': 'TREE',
+    'heap.py': 'TREE',
+    'trie.py': 'TREE',
+    'aho_corasick.py': 'TREE',
+    'avl_tree.py': 'TREE',
+    'b_plus_tree.py': 'TREE',
+    'btree.py': 'TREE',
+    'cow_tree.py': 'TREE',
+    'fenwick_tree.py': 'TREE',
+    'lsm_tree.py': 'TREE',
+    'ordered_map.py': 'TREE',
+    'ordered_map_balanced.py': 'TREE',
+    'patricia.py': 'TREE',
+    'persistent_tree.py': 'TREE',
+    'radix_trie.py': 'TREE',
+    'red_black_tree.py': 'TREE',
+    'segment_tree.py': 'TREE',
+    'skip_list.py': 'TREE',
+    'splay_tree.py': 'TREE',
+    'suffix_array.py': 'TREE',
+    'treap.py': 'TREE',
+    'art.py': 'TREE',
+    'bw_tree.py': 'TREE',
+    'hamt.py': 'TREE',
+    'masstree.py': 'TREE',
+    'extendible_hash.py': 'TREE',
+    'linear_hash.py': 'TREE',
+    't_tree.py': 'TREE',
+    'learned_index.py': 'TREE',
+    
+    # GRAPH
+    'union_find.py': 'GRAPH',
+    'adjacency_list.py': 'GRAPH',
+    
+    # MATRIX
+    'sparse_matrix.py': 'MATRIX',
+    'bitmap.py': 'MATRIX',
+    'bitset_dynamic.py': 'MATRIX',
+    'roaring_bitmap.py': 'MATRIX',
+    'bloom_filter.py': 'MATRIX',
+    'count_min_sketch.py': 'MATRIX',
+    'hyperloglog.py': 'MATRIX',
+    'set_hash.py': 'MATRIX',
+    'set_tree.py': 'TREE',
+    'cuckoo_hash.py': 'TREE',
+    
+    # HYBRID
+    'tree_graph_hybrid.py': 'HYBRID',
+    'xdata_optimized.py': 'HYBRID',
+}
+
+
+def add_strategy_type_to_file(file_path: Path, node_type: str) -> bool:
+    """Add STRATEGY_TYPE to a strategy file."""
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+        
+        # Check if STRATEGY_TYPE already exists
+        if 'STRATEGY_TYPE' in content:
+            print(f"  ⏭️  Already has STRATEGY_TYPE: {file_path.name}")
+            return False
+        
+        # Find class definition
+        class_match = re.search(r'(class \w+Strategy\([^)]+\):\s*\n\s*"""[^"]*""")', content, re.MULTILINE)
+        if not class_match:
+            print(f"  ⚠️  Could not find class definition: {file_path.name}")
+            return False
+        
+        # Add import if not present
+        if 'from .contracts import NodeType' not in content:
+            # Find where to add import (after other local imports)
+            if 'from .base import' in content:
+                content = content.replace(
+                    'from .base import',
+                    'from .base import'
+                )
+                # Add after base import
+                import_pos = content.find('from .base import')
+                line_end = content.find('\n', import_pos)
+                content = content[:line_end+1] + 'from .contracts import NodeType\n' + content[line_end+1:]
+        
+        # Add STRATEGY_TYPE after class docstring
+        class_end = class_match.end()
+        
+        # Add STRATEGY_TYPE declaration
+        strategy_type_line = f'\n    \n    # Strategy type classification\n    STRATEGY_TYPE = NodeType.{node_type}\n'
+        content = content[:class_end] + strategy_type_line + content[class_end:]
+        
+        # Write back
+        with open(file_path, 'w', encoding='utf-8') as f:
+            f.write(content)
+        
+        print(f"  ✅ Added STRATEGY_TYPE.{node_type}: {file_path.name}")
+        return True
+        
+    except Exception as e:
+        print(f"  ❌ Error processing {file_path.name}: {e}")
+        return False
+
+
+def main():
+    """Main function."""
+    print("="*70)
+    print("Adding STRATEGY_TYPE to All Node Strategies")
+    print("="*70)
+    
+    base_path = Path(__file__).parent / 'src' / 'exonware' / 'xwnode' / 'nodes' / 'strategies'
+    
+    count_added = 0
+    count_skipped = 0
+    count_errors = 0
+    
+    for filename, node_type in STRATEGY_TYPE_MAP.items():
+        file_path = base_path / filename
+        
+        if not file_path.exists():
+            print(f"  ⚠️  File not found: {filename}")
+            count_errors += 1
+            continue
+        
+        result = add_strategy_type_to_file(file_path, node_type)
+        if result:
+            count_added += 1
+        elif 'Already has' in str(result):
+            count_skipped += 1
+        else:
+            count_errors += 1
+    
+    print("\n" + "="*70)
+    print(f"Summary: {count_added} added, {count_skipped} skipped, {count_errors} errors")
+    print("="*70)
+
+
+if __name__ == '__main__':
+    main()

exonware/xwnode/common/__init__.py

@@ -6,7 +6,7 @@ Common utilities and patterns shared across xwnode.
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.22
+Version: 0.0.1.23
 """
 
 # Export common patterns

exonware/xwnode/common/graph/__init__.py

@@ -0,0 +1,30 @@
+"""
+#exonware/xwnode/src/exonware/xwnode/common/graph/__init__.py
+
+Graph optimization module for XWNode.
+
+Provides O(1) relationship queries with multi-tenant security isolation.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.23
+Generation Date: 11-Oct-2025
+"""
+
+from .manager import XWGraphManager
+from .errors import (
+    XWGraphError,
+    XWGraphSecurityError,
+    XWGraphEntityNotFoundError,
+    XWGraphRelationshipNotFoundError
+)
+
+__all__ = [
+    'XWGraphManager',
+    'XWGraphError',
+    'XWGraphSecurityError',
+    'XWGraphEntityNotFoundError',
+    'XWGraphRelationshipNotFoundError'
+]
+

exonware/xwnode/common/graph/caching.py

@@ -0,0 +1,131 @@
+"""
+#exonware/xwnode/src/exonware/xwnode/common/graph/caching.py
+
+LRU cache manager for frequent relationship queries.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.23
+Generation Date: 11-Oct-2025
+"""
+
+import threading
+from typing import Any, Optional, List
+from collections import OrderedDict
+
+
+class CacheManager:
+    """
+    Thread-safe LRU cache for query results.
+    
+    Provides O(1) cache operations with automatic eviction
+    of least recently used entries.
+    """
+    
+    def __init__(self, max_size: int = 1000):
+        """
+        Initialize cache manager.
+        
+        Args:
+            max_size: Maximum number of cached entries
+        """
+        self._cache: OrderedDict[str, Any] = OrderedDict()
+        self._max_size = max_size
+        self._hits = 0
+        self._misses = 0
+        self._lock = threading.RLock()
+    
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get cached result.
+        
+        Args:
+            key: Cache key
+        
+        Returns:
+            Cached value or None if not found
+            
+        Time Complexity: O(1)
+        """
+        with self._lock:
+            if key in self._cache:
+                self._hits += 1
+                # Move to end (most recently used)
+                self._cache.move_to_end(key)
+                return self._cache[key]
+            
+            self._misses += 1
+            return None
+    
+    def put(self, key: str, value: Any) -> None:
+        """
+        Cache a query result.
+        
+        Args:
+            key: Cache key
+            value: Value to cache
+            
+        Time Complexity: O(1)
+        """
+        with self._lock:
+            if key in self._cache:
+                # Update existing entry
+                self._cache.move_to_end(key)
+                self._cache[key] = value
+            else:
+                # Add new entry
+                if len(self._cache) >= self._max_size:
+                    # Remove least recently used (first item)
+                    self._cache.popitem(last=False)
+                self._cache[key] = value
+    
+    def invalidate(self, entity_id: str) -> None:
+        """
+        Invalidate cache entries for entity.
+        
+        Removes all cached queries that involve the specified entity.
+        
+        Args:
+            entity_id: Entity whose cache entries should be invalidated
+        """
+        with self._lock:
+            # Find all cache keys containing this entity
+            keys_to_remove = [k for k in self._cache.keys() if entity_id in k]
+            
+            # Remove them
+            for key in keys_to_remove:
+                del self._cache[key]
+    
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        with self._lock:
+            self._cache.clear()
+    
+    def get_hit_rate(self) -> float:
+        """
+        Get cache hit rate.
+        
+        Returns:
+            Hit rate as float between 0.0 and 1.0
+        """
+        with self._lock:
+            total = self._hits + self._misses
+            return self._hits / total if total > 0 else 0.0
+    
+    def get_stats(self) -> dict:
+        """
+        Get cache statistics.
+        
+        Returns:
+            Dictionary with cache metrics
+        """
+        with self._lock:
+            return {
+                'size': len(self._cache),
+                'max_size': self._max_size,
+                'hits': self._hits,
+                'misses': self._misses,
+                'hit_rate': self.get_hit_rate()
+            }
+

exonware/xwnode/common/graph/contracts.py

@@ -0,0 +1,100 @@
+"""
+#exonware/xwnode/src/exonware/xwnode/common/graph/contracts.py
+
+Graph manager contracts and enums.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.23
+Generation Date: 11-Oct-2025
+"""
+
+from enum import Enum
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional, Any
+
+
+class GraphOptimization(Enum):
+    """
+    Graph optimization levels for XWGraphManager.
+    
+    Controls indexing and caching behavior for performance tuning.
+    """
+    
+    OFF = 0           # No optimization - fallback to O(n) iteration
+    INDEX_ONLY = 1    # Only indexing - O(1) lookups, no caching
+    CACHE_ONLY = 2    # Only caching - benefits from repeated queries
+    FULL = 3          # Both indexing + caching - maximum performance
+    
+    # Aliases for clarity
+    DISABLED = 0
+    MINIMAL = 1
+    MODERATE = 2
+    MAXIMUM = 3
+
+
+class IGraphManager(ABC):
+    """Interface for graph manager implementations."""
+    
+    @abstractmethod
+    def add_relationship(
+        self,
+        source: str,
+        target: str,
+        relationship_type: str,
+        **properties
+    ) -> str:
+        """Add a relationship between entities."""
+        pass
+    
+    @abstractmethod
+    def remove_relationship(
+        self,
+        source: str,
+        target: str,
+        relationship_type: Optional[str] = None
+    ) -> bool:
+        """Remove relationship(s) between entities."""
+        pass
+    
+    @abstractmethod
+    def get_outgoing(
+        self,
+        entity_id: str,
+        relationship_type: Optional[str] = None,
+        limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """Get outgoing relationships for entity."""
+        pass
+    
+    @abstractmethod
+    def get_incoming(
+        self,
+        entity_id: str,
+        relationship_type: Optional[str] = None,
+        limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """Get incoming relationships for entity."""
+        pass
+    
+    @abstractmethod
+    def has_relationship(
+        self,
+        source: str,
+        target: str,
+        relationship_type: Optional[str] = None
+    ) -> bool:
+        """Check if relationship exists."""
+        pass
+    
+    @abstractmethod
+    def get_stats(self) -> Dict[str, Any]:
+        """Get graph statistics."""
+        pass
+    
+    @abstractmethod
+    def clear_cache(self) -> None:
+        """Clear query cache."""
+        pass
+

exonware/xwnode/common/graph/errors.py

@@ -0,0 +1,44 @@
+"""
+#exonware/xwnode/src/exonware/xwnode/common/graph/errors.py
+
+Graph-specific error classes.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.0.1.23
+Generation Date: 11-Oct-2025
+"""
+
+from ...errors import XWNodeError
+
+
+class XWGraphError(XWNodeError):
+    """Base error for graph operations."""
+    pass
+
+
+class XWGraphSecurityError(XWGraphError):
+    """Security violation in graph operations."""
+    pass
+
+
+class XWGraphEntityNotFoundError(XWGraphError):
+    """Entity not found in graph."""
+    pass
+
+
+class XWGraphRelationshipNotFoundError(XWGraphError):
+    """Relationship not found in graph."""
+    pass
+
+
+class XWGraphCycleDetectedError(XWGraphError):
+    """Cycle detected in graph traversal."""
+    pass
+
+
+class XWGraphInvalidOperationError(XWGraphError):
+    """Invalid graph operation."""
+    pass
+