exonware-xwsystem 0.1.0.1__py3-none-any.whl → 0.1.0.3__py3-none-any.whl

exonware/xwsystem/plugins/defs.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/plugins/defs.py
 #exonware/xwsystem/plugins/types.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: 07-Sep-2025
 
 Plugins types and enums for XWSystem.

exonware/xwsystem/plugins/errors.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/plugins/errors.py
 #exonware/xwsystem/plugins/errors.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 Plugin-specific error classes for XSystem plugin system.

exonware/xwsystem/py.typed

@@ -0,0 +1,3 @@
+#
+# Marker file for PEP 561 to indicate that exonware.xwsystem is a typed package.
+#

exonware/xwsystem/query/__init__.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""
+#exonware/xwsystem/src/exonware/xwsystem/query/__init__.py
+
+Query foundation layer for eXonware ecosystem.
+
+This package defines query contracts and a small registry that higher-level
+libraries (e.g., xwquery) can register into, while lower-level libraries
+(e.g., xwnode) can depend on without creating circular dependencies.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.3
+Generation Date: 28-Dec-2025
+"""
+
+from .contracts import IQueryProvider, QueryResult
+from .errors import QueryProviderError, QueryProviderNotRegisteredError
+from .registry import (
+    get_query_provider,
+    get_query_provider_registry,
+    register_query_provider,
+    reset_query_provider_registry,
+)
+
+__all__ = [
+    "IQueryProvider",
+    "QueryResult",
+    "QueryProviderError",
+    "QueryProviderNotRegisteredError",
+    "get_query_provider",
+    "get_query_provider_registry",
+    "register_query_provider",
+    "reset_query_provider_registry",
+]

exonware/xwsystem/query/contracts.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""
+#exonware/xwsystem/src/exonware/xwsystem/query/contracts.py
+
+Query contracts (foundation layer).
+
+These interfaces live in xwsystem to avoid circular dependencies between:
+- xwnode (data structures / node facade)
+- xwquery (query engine)
+- xwdata (data facade built on xwnode + xwquery)
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.3
+Generation Date: 28-Dec-2025
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable, TypeAlias
+
+QueryResult: TypeAlias = Any
+
+
+@runtime_checkable
+class IQueryProvider(Protocol):
+    """
+    Interface for query execution providers.
+
+    Implementations live in higher-level packages (e.g., xwquery) and register
+    themselves via `exonware.xwsystem.query.registry`.
+    """
+
+    provider_id: str
+
+    def execute(
+        self,
+        query: str,
+        data: Any,
+        *,
+        format: str | None = None,
+        auto_detect: bool = True,
+        **opts: Any,
+    ) -> QueryResult:
+        """
+        Execute a query against data.
+
+        Args:
+            query: Query string (SQL, GraphQL, xwquery script, etc.)
+            data: Target data (XWNode, dict, list, etc.)
+            format: Optional explicit format identifier
+            auto_detect: Whether provider should auto-detect when format is None
+            **opts: Provider-specific options
+        """
+        ...

exonware/xwsystem/query/errors.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+"""
+#exonware/xwsystem/src/exonware/xwsystem/query/errors.py
+
+Query provider errors (foundation layer).
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.3
+Generation Date: 28-Dec-2025
+"""
+
+
+class QueryProviderError(Exception):
+    """Base error for query provider integration."""
+
+
+class QueryProviderNotRegisteredError(QueryProviderError):
+    """
+    Raised when a consumer requests a query provider but none is registered.
+    """

exonware/xwsystem/query/registry.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""
+#exonware/xwsystem/src/exonware/xwsystem/query/registry.py
+
+Global query provider registry (foundation layer).
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.3
+Generation Date: 28-Dec-2025
+"""
+
+from __future__ import annotations
+
+from threading import RLock
+from typing import Optional
+
+from .contracts import IQueryProvider
+from .errors import QueryProviderNotRegisteredError
+
+
+class QueryProviderRegistry:
+    """
+    Thread-safe registry for query providers.
+
+    Design notes:
+    - Multiple providers may be registered (future-proofing).
+    - A default provider may be selected; consumers typically use the default.
+    """
+
+    def __init__(self) -> None:
+        self._lock = RLock()
+        self._providers: dict[str, IQueryProvider] = {}
+        self._default_provider_id: Optional[str] = None
+
+    def register(self, provider: IQueryProvider, *, overwrite: bool = False, make_default: bool = True) -> None:
+        provider_id = provider.provider_id.strip().lower()
+        if not provider_id:
+            raise ValueError("provider.provider_id must be a non-empty string")
+
+        with self._lock:
+            if provider_id in self._providers and not overwrite:
+                return
+            self._providers[provider_id] = provider
+            if make_default or self._default_provider_id is None:
+                self._default_provider_id = provider_id
+
+    def unregister(self, provider_id: str) -> bool:
+        pid = provider_id.strip().lower()
+        with self._lock:
+            if pid not in self._providers:
+                return False
+            del self._providers[pid]
+            if self._default_provider_id == pid:
+                self._default_provider_id = next(iter(self._providers.keys()), None)
+            return True
+
+    def get(self, provider_id: str) -> Optional[IQueryProvider]:
+        pid = provider_id.strip().lower()
+        with self._lock:
+            return self._providers.get(pid)
+
+    def get_default(self) -> Optional[IQueryProvider]:
+        with self._lock:
+            if not self._default_provider_id:
+                return None
+            return self._providers.get(self._default_provider_id)
+
+    def require_default(self) -> IQueryProvider:
+        provider = self.get_default()
+        if provider is None:
+            raise QueryProviderNotRegisteredError(
+                "No query provider registered. "
+                "Install and import exonware-xwquery to register a provider."
+            )
+        return provider
+
+    def list_provider_ids(self) -> list[str]:
+        with self._lock:
+            return list(self._providers.keys())
+
+    def clear(self) -> None:
+        with self._lock:
+            self._providers.clear()
+            self._default_provider_id = None
+
+
+_global_registry: Optional[QueryProviderRegistry] = None
+_global_lock = RLock()
+
+
+def get_query_provider_registry() -> QueryProviderRegistry:
+    """
+    Get the global query provider registry (thread-safe singleton).
+    """
+    global _global_registry
+    if _global_registry is None:
+        with _global_lock:
+            if _global_registry is None:
+                _global_registry = QueryProviderRegistry()
+    return _global_registry
+
+
+def reset_query_provider_registry() -> None:
+    """
+    Reset the global registry (primarily for testing).
+    """
+    global _global_registry
+    with _global_lock:
+        _global_registry = None
+
+
+def register_query_provider(provider: IQueryProvider, *, overwrite: bool = False, make_default: bool = True) -> None:
+    """
+    Register a query provider in the global registry.
+    """
+    get_query_provider_registry().register(provider, overwrite=overwrite, make_default=make_default)
+
+
+def get_query_provider(provider_id: str | None = None) -> Optional[IQueryProvider]:
+    """
+    Get a provider by id, or the default provider if provider_id is None.
+    """
+    registry = get_query_provider_registry()
+    if provider_id is None:
+        return registry.get_default()
+    return registry.get(provider_id)

exonware/xwsystem/runtime/__init__.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/runtime/__init__.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 XSystem Runtime Package

exonware/xwsystem/runtime/base.py

@@ -1,16 +1,17 @@
+#exonware/xwsystem/src/exonware/xwsystem/runtime/base.py
 #exonware/xwsystem/runtime/base.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 Runtime module base classes - abstract classes for runtime functionality.
 """
 
 from abc import ABC, abstractmethod
-from typing import Any, Optional, Union, Callable
+from typing import Any, Optional, Callable
 from .contracts import RuntimeMode, PlatformType, PythonVersion, EnvironmentType
 
 
@@ -370,7 +371,7 @@ class ARuntimeManagerBase(ABC):
 
 
 class BaseRuntime(ARuntimeBase):
-    """Base runtime implementation for backward compatibility."""
+    """Base runtime implementation."""
     
     def __init__(self, mode: RuntimeMode = RuntimeMode.NORMAL):
         """Initialize base runtime."""

exonware/xwsystem/runtime/contracts.py

@@ -1,15 +1,15 @@
+#exonware/xwsystem/src/exonware/xwsystem/runtime/contracts.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 Runtime module contracts - interfaces and enums for runtime environment functionality.
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Optional, Union, Callable
+from typing import Any, Optional, Callable, Protocol, runtime_checkable
 import sys
 
 # Import enums from types module
@@ -21,151 +21,130 @@ from .defs import (
 )
 
 
-class IEnvironmentManager(ABC):
+@runtime_checkable
+class IEnvironmentManager(Protocol):
     """Interface for environment management."""
     
-    @abstractmethod
     def get_environment_type(self) -> EnvironmentType:
         """Get current environment type."""
-        pass
+        ...
     
-    @abstractmethod
     def set_environment_type(self, env_type: EnvironmentType) -> None:
         """Set environment type."""
-        pass
+        ...
     
-    @abstractmethod
     def get_environment_variable(self, name: str, default: Optional[str] = None) -> Optional[str]:
         """Get environment variable."""
-        pass
+        ...
     
-    @abstractmethod
     def set_environment_variable(self, name: str, value: str) -> None:
         """Set environment variable."""
-        pass
+        ...
     
-    @abstractmethod
     def get_all_environment_variables(self) -> dict[str, str]:
         """Get all environment variables."""
-        pass
+        ...
 
 
-class IPlatformInfo(ABC):
+@runtime_checkable
+class IPlatformInfo(Protocol):
     """Interface for platform information."""
     
-    @abstractmethod
     def get_platform_type(self) -> PlatformType:
         """Get platform type."""
-        pass
+        ...
     
-    @abstractmethod
     def get_platform_version(self) -> str:
         """Get platform version."""
-        pass
+        ...
     
-    @abstractmethod
     def get_architecture(self) -> str:
         """Get system architecture."""
-        pass
+        ...
     
-    @abstractmethod
     def get_hostname(self) -> str:
         """Get system hostname."""
-        pass
+        ...
     
-    @abstractmethod
     def get_username(self) -> str:
         """Get current username."""
-        pass
+        ...
 
 
-class IPythonInfo(ABC):
+@runtime_checkable
+class IPythonInfo(Protocol):
     """Interface for Python information."""
     
-    @abstractmethod
     def get_python_version(self) -> PythonVersion:
         """Get Python version."""
-        pass
+        ...
     
-    @abstractmethod
     def get_python_executable(self) -> str:
         """Get Python executable path."""
-        pass
+        ...
     
-    @abstractmethod
     def get_python_path(self) -> list[str]:
         """Get Python path."""
-        pass
+        ...
     
-    @abstractmethod
     def get_installed_packages(self) -> dict[str, str]:
         """Get installed packages."""
-        pass
+        ...
     
-    @abstractmethod
     def is_package_installed(self, package_name: str) -> bool:
         """Check if package is installed."""
-        pass
+        ...
 
 
-class IReflectionUtils(ABC):
+@runtime_checkable
+class IReflectionUtils(Protocol):
     """Interface for reflection utilities."""
     
-    @abstractmethod
     def get_class_from_string(self, class_path: str) -> type:
         """Get class from string path."""
-        pass
+        ...
     
-    @abstractmethod
     def get_function_from_string(self, function_path: str) -> Callable:
         """Get function from string path."""
-        pass
+        ...
     
-    @abstractmethod
     def find_classes_in_module(self, module: Any, base_class: type) -> list[type]:
         """Find classes in module."""
-        pass
+        ...
     
-    @abstractmethod
     def get_class_hierarchy(self, cls: type) -> list[type]:
         """Get class hierarchy."""
-        pass
+        ...
     
-    @abstractmethod
     def get_class_attributes(self, cls: type) -> dict[str, Any]:
         """Get class attributes."""
-        pass
+        ...
 
 
-class IRuntimeConfig(ABC):
+@runtime_checkable
+class IRuntimeConfig(Protocol):
     """Interface for runtime configuration."""
     
-    @abstractmethod
     def get_runtime_mode(self) -> RuntimeMode:
         """Get runtime mode."""
-        pass
+        ...
     
-    @abstractmethod
     def set_runtime_mode(self, mode: RuntimeMode) -> None:
         """Set runtime mode."""
-        pass
+        ...
     
-    @abstractmethod
     def get_config_value(self, key: str, default: Optional[Any] = None) -> Any:
         """Get configuration value."""
-        pass
+        ...
     
-    @abstractmethod
     def set_config_value(self, key: str, value: Any) -> None:
         """Set configuration value."""
-        pass
+        ...
     
-    @abstractmethod
     def load_config_from_file(self, file_path: str) -> None:
         """Load configuration from file."""
-        pass
+        ...
     
-    @abstractmethod
     def save_config_to_file(self, file_path: str) -> None:
         """Save configuration to file."""
-        pass
+        ...

exonware/xwsystem/runtime/defs.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/runtime/defs.py
 #exonware/xwsystem/runtime/types.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: 07-Sep-2025
 
 Runtime types and enums for XWSystem.

exonware/xwsystem/runtime/env.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/runtime/env.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 Environment management utilities for runtime configuration and detection.
@@ -12,7 +13,7 @@ import os
 import platform
 import sys
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 from ..config.logging_setup import get_logger
 
@@ -49,18 +50,18 @@ class EnvironmentManager:
 
     @property
     def is_windows(self) -> bool:
-        """Check if running on Windows."""
-        return platform.system().lower() == 'windows'
+        """Check if running on Windows using Python's native platform module."""
+        return platform.system() == 'Windows'
 
     @property
     def is_linux(self) -> bool:
-        """Check if running on Linux."""
-        return platform.system().lower() == 'linux'
+        """Check if running on Linux using Python's native platform module."""
+        return platform.system() == 'Linux'
 
     @property
     def is_macos(self) -> bool:
-        """Check if running on macOS."""
-        return platform.system().lower() == 'darwin'
+        """Check if running on macOS using Python's native platform module."""
+        return platform.system() == 'Darwin'
 
     @property
     def is_64bit(self) -> bool:
@@ -262,7 +263,8 @@ class EnvironmentManager:
 
     def get_temp_dir(self) -> Path:
         """Get system temporary directory."""
-        return Path(self.get_env('TEMP') or self.get_env('TMP') or '/tmp')
+        import tempfile
+        return Path(tempfile.gettempdir())
 
     def get_current_working_dir(self) -> Path:
         """Get current working directory."""

exonware/xwsystem/runtime/errors.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/runtime/errors.py
 #exonware/xwsystem/runtime/errors.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 Runtime module errors - exception classes for runtime functionality.

exonware/xwsystem/runtime/reflection.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/runtime/reflection.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 Reflection utilities for dynamic code inspection and manipulation.
@@ -12,7 +13,7 @@ import importlib
 import inspect
 import sys
 from pathlib import Path
-from typing import Any, Callable, Optional, Union
+from typing import Any, Callable, Optional
 
 from ..config.logging_setup import get_logger