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

exonware/xwsystem/plugins/contracts.py

@@ -1,16 +1,16 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/plugins/contracts.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.4
 Generation Date: September 04, 2025
 
 Plugin protocol interfaces for XWSystem.
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Optional, Union, Iterator, Callable
+from typing import Any, Optional, Iterator, Callable, Protocol, runtime_checkable
 import importlib
 
 # Import enums from types module
@@ -27,28 +27,26 @@ from .defs import (
 # PLUGIN INTERFACES
 # ============================================================================
 
-class IPlugin(ABC):
+@runtime_checkable
+class IPlugin(Protocol):
     """
     Interface for plugins.
     
     Enforces consistent plugin behavior across XWSystem.
     """
     
-    @abstractmethod
     def initialize(self) -> None:
         """
         Initialize the plugin.
         """
-        pass
+        ...
     
-    @abstractmethod
     def shutdown(self) -> None:
         """
         Shutdown the plugin.
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_info(self) -> dict[str, Any]:
         """
         Get plugin information.
@@ -56,9 +54,8 @@ class IPlugin(ABC):
         Returns:
             Plugin information dictionary
         """
-        pass
+        ...
     
-    @abstractmethod
     def is_enabled(self) -> bool:
         """
         Check if plugin is enabled.
@@ -66,23 +63,20 @@ class IPlugin(ABC):
         Returns:
             True if enabled
         """
-        pass
+        ...
     
-    @abstractmethod
     def enable(self) -> None:
         """
         Enable the plugin.
         """
-        pass
+        ...
     
-    @abstractmethod
     def disable(self) -> None:
         """
         Disable the plugin.
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_state(self) -> PluginState:
         """
         Get plugin state.
@@ -90,9 +84,8 @@ class IPlugin(ABC):
         Returns:
             Current plugin state
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_plugin_type(self) -> PluginType:
         """
         Get plugin type.
@@ -100,9 +93,8 @@ class IPlugin(ABC):
         Returns:
             Plugin type
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_priority(self) -> PluginPriority:
         """
         Get plugin priority.
@@ -110,9 +102,8 @@ class IPlugin(ABC):
         Returns:
             Plugin priority
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_dependencies(self) -> list[str]:
         """
         Get plugin dependencies.
@@ -120,9 +111,8 @@ class IPlugin(ABC):
         Returns:
             List of dependency names
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_version(self) -> str:
         """
         Get plugin version.
@@ -130,9 +120,8 @@ class IPlugin(ABC):
         Returns:
             Plugin version string
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_author(self) -> str:
         """
         Get plugin author.
@@ -140,9 +129,8 @@ class IPlugin(ABC):
         Returns:
             Plugin author
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_description(self) -> str:
         """
         Get plugin description.
@@ -150,21 +138,21 @@ class IPlugin(ABC):
         Returns:
             Plugin description
         """
-        pass
+        ...
 
 
 # ============================================================================
 # EXTENSIBLE INTERFACES
 # ============================================================================
 
-class IExtensible(ABC):
+@runtime_checkable
+class IExtensible(Protocol):
     """
     Interface for extensible objects.
     
     Enforces consistent extension behavior across XWSystem.
     """
     
-    @abstractmethod
     def add_extension(self, extension: Any) -> bool:
         """
         Add extension.
@@ -175,9 +163,8 @@ class IExtensible(ABC):
         Returns:
             True if added successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def remove_extension(self, name: str) -> bool:
         """
         Remove extension by name.
@@ -188,9 +175,8 @@ class IExtensible(ABC):
         Returns:
             True if removed
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_extensions(self) -> list[Any]:
         """
         Get all extensions.
@@ -198,9 +184,8 @@ class IExtensible(ABC):
         Returns:
             List of extensions
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_extension(self, name: str) -> Optional[Any]:
         """
         Get extension by name.
@@ -211,9 +196,8 @@ class IExtensible(ABC):
         Returns:
             Extension or None
         """
-        pass
+        ...
     
-    @abstractmethod
     def has_extension(self, name: str) -> bool:
         """
         Check if extension exists.
@@ -224,9 +208,8 @@ class IExtensible(ABC):
         Returns:
             True if exists
         """
-        pass
+        ...
     
-    @abstractmethod
     def list_extension_names(self) -> list[str]:
         """
         List extension names.
@@ -234,16 +217,14 @@ class IExtensible(ABC):
         Returns:
             List of extension names
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_extensions(self) -> None:
         """
         Clear all extensions.
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_extension_count(self) -> int:
         """
         Get number of extensions.
@@ -251,21 +232,21 @@ class IExtensible(ABC):
         Returns:
             Number of extensions
         """
-        pass
+        ...
 
 
 # ============================================================================
 # HOOKABLE INTERFACES
 # ============================================================================
 
-class IHookable(ABC):
+@runtime_checkable
+class IHookable(Protocol):
     """
     Interface for hookable objects.
     
     Enforces consistent hook behavior across XWSystem.
     """
     
-    @abstractmethod
     def add_hook(self, event: str, callback: Callable, hook_type: HookType = HookType.ACTION) -> str:
         """
         Add hook callback.
@@ -278,9 +259,8 @@ class IHookable(ABC):
         Returns:
             Hook ID
         """
-        pass
+        ...
     
-    @abstractmethod
     def remove_hook(self, event: str, callback: Callable) -> bool:
         """
         Remove hook callback.
@@ -292,9 +272,8 @@ class IHookable(ABC):
         Returns:
             True if removed
         """
-        pass
+        ...
     
-    @abstractmethod
     def trigger_hook(self, event: str, data: Any = None) -> Any:
         """
         Trigger hook event.
@@ -306,9 +285,8 @@ class IHookable(ABC):
         Returns:
             Hook result
         """
-        pass
+        ...
     
-    @abstractmethod
     def list_hooks(self, event: Optional[str] = None) -> list[dict[str, Any]]:
         """
         List hooks.
@@ -319,9 +297,8 @@ class IHookable(ABC):
         Returns:
             List of hook information
         """
-        pass
+        ...
     
-    @abstractmethod
     def has_hooks(self, event: str) -> bool:
         """
         Check if event has hooks.
@@ -332,9 +309,8 @@ class IHookable(ABC):
         Returns:
             True if has hooks
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_hooks(self, event: Optional[str] = None) -> None:
         """
         Clear hooks.
@@ -342,9 +318,8 @@ class IHookable(ABC):
         Args:
             event: Clear hooks for specific event, or all if None
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_hook_count(self, event: Optional[str] = None) -> int:
         """
         Get hook count.
@@ -355,21 +330,21 @@ class IHookable(ABC):
         Returns:
             Number of hooks
         """
-        pass
+        ...
 
 
 # ============================================================================
 # PLUGIN MANAGER INTERFACES
 # ============================================================================
 
-class IPluginManager(ABC):
+@runtime_checkable
+class IPluginManager(Protocol):
     """
     Interface for plugin management.
     
     Enforces consistent plugin management across XWSystem.
     """
     
-    @abstractmethod
     def load_plugin(self, plugin_path: str) -> bool:
         """
         Load plugin from path.
@@ -380,9 +355,8 @@ class IPluginManager(ABC):
         Returns:
             True if loaded successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def unload_plugin(self, plugin_name: str) -> bool:
         """
         Unload plugin.
@@ -393,9 +367,8 @@ class IPluginManager(ABC):
         Returns:
             True if unloaded successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def reload_plugin(self, plugin_name: str) -> bool:
         """
         Reload plugin.
@@ -406,9 +379,8 @@ class IPluginManager(ABC):
         Returns:
             True if reloaded successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_plugin(self, plugin_name: str) -> Optional[IPlugin]:
         """
         Get plugin by name.
@@ -419,9 +391,8 @@ class IPluginManager(ABC):
         Returns:
             Plugin instance or None
         """
-        pass
+        ...
     
-    @abstractmethod
     def list_plugins(self) -> list[str]:
         """
         List all plugin names.
@@ -429,9 +400,8 @@ class IPluginManager(ABC):
         Returns:
             List of plugin names
         """
-        pass
+        ...
     
-    @abstractmethod
     def list_loaded_plugins(self) -> list[str]:
         """
         List loaded plugin names.
@@ -439,9 +409,8 @@ class IPluginManager(ABC):
         Returns:
             List of loaded plugin names
         """
-        pass
+        ...
     
-    @abstractmethod
     def is_plugin_loaded(self, plugin_name: str) -> bool:
         """
         Check if plugin is loaded.
@@ -452,9 +421,8 @@ class IPluginManager(ABC):
         Returns:
             True if loaded
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_plugin_info(self, plugin_name: str) -> Optional[dict[str, Any]]:
         """
         Get plugin information.
@@ -465,21 +433,21 @@ class IPluginManager(ABC):
         Returns:
             Plugin information or None
         """
-        pass
+        ...
 
 
 # ============================================================================
 # PLUGIN REGISTRY INTERFACES
 # ============================================================================
 
-class IPluginRegistry(ABC):
+@runtime_checkable
+class IPluginRegistry(Protocol):
     """
     Interface for plugin registry.
     
     Enforces consistent plugin registration across XWSystem.
     """
     
-    @abstractmethod
     def register_plugin(self, plugin_class: type[IPlugin], name: str, priority: PluginPriority = PluginPriority.NORMAL) -> bool:
         """
         Register plugin class.
@@ -492,9 +460,8 @@ class IPluginRegistry(ABC):
         Returns:
             True if registered successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def unregister_plugin(self, name: str) -> bool:
         """
         Unregister plugin.
@@ -505,9 +472,8 @@ class IPluginRegistry(ABC):
         Returns:
             True if unregistered
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_registered_plugins(self) -> dict[str, type[IPlugin]]:
         """
         Get all registered plugins.
@@ -515,9 +481,8 @@ class IPluginRegistry(ABC):
         Returns:
             Dictionary of registered plugins
         """
-        pass
+        ...
     
-    @abstractmethod
     def is_plugin_registered(self, name: str) -> bool:
         """
         Check if plugin is registered.
@@ -528,9 +493,8 @@ class IPluginRegistry(ABC):
         Returns:
             True if registered
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_plugin_class(self, name: str) -> Optional[type[IPlugin]]:
         """
         Get plugin class by name.
@@ -541,16 +505,14 @@ class IPluginRegistry(ABC):
         Returns:
             Plugin class or None
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_registry(self) -> None:
         """
         Clear plugin registry.
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_registry_stats(self) -> dict[str, Any]:
         """
         Get registry statistics.
@@ -558,21 +520,21 @@ class IPluginRegistry(ABC):
         Returns:
             Registry statistics dictionary
         """
-        pass
+        ...
 
 
 # ============================================================================
 # PLUGIN DISCOVERY INTERFACES
 # ============================================================================
 
-class IPluginDiscovery(ABC):
+@runtime_checkable
+class IPluginDiscovery(Protocol):
     """
     Interface for plugin discovery.
     
     Enforces consistent plugin discovery across XWSystem.
     """
     
-    @abstractmethod
     def discover_plugins(self, search_paths: list[str]) -> list[str]:
         """
         Discover plugins in search paths.
@@ -583,9 +545,8 @@ class IPluginDiscovery(ABC):
         Returns:
             List of discovered plugin paths
         """
-        pass
+        ...
     
-    @abstractmethod
     def scan_directory(self, directory: str) -> list[str]:
         """
         Scan directory for plugins.
@@ -596,9 +557,8 @@ class IPluginDiscovery(ABC):
         Returns:
             List of plugin files found
         """
-        pass
+        ...
     
-    @abstractmethod
     def validate_plugin(self, plugin_path: str) -> tuple[bool, list[str]]:
         """
         Validate plugin.
@@ -609,9 +569,8 @@ class IPluginDiscovery(ABC):
         Returns:
             Tuple of (is_valid, error_messages)
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_plugin_metadata(self, plugin_path: str) -> Optional[dict[str, Any]]:
         """
         Get plugin metadata.
@@ -622,9 +581,8 @@ class IPluginDiscovery(ABC):
         Returns:
             Plugin metadata or None
         """
-        pass
+        ...
     
-    @abstractmethod
     def is_plugin_file(self, file_path: str) -> bool:
         """
         Check if file is a plugin.
@@ -635,9 +593,8 @@ class IPluginDiscovery(ABC):
         Returns:
             True if file is a plugin
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_supported_extensions(self) -> list[str]:
         """
         Get supported plugin file extensions.
@@ -645,21 +602,21 @@ class IPluginDiscovery(ABC):
         Returns:
             List of supported extensions
         """
-        pass
+        ...
 
 
 # ============================================================================
 # PLUGIN CONFIGURATION INTERFACES
 # ============================================================================
 
-class IPluginConfig(ABC):
+@runtime_checkable
+class IPluginConfig(Protocol):
     """
     Interface for plugin configuration.
     
     Enforces consistent plugin configuration across XWSystem.
     """
     
-    @abstractmethod
     def get_plugin_config(self, plugin_name: str) -> dict[str, Any]:
         """
         Get plugin configuration.
@@ -670,9 +627,8 @@ class IPluginConfig(ABC):
         Returns:
             Plugin configuration dictionary
         """
-        pass
+        ...
     
-    @abstractmethod
     def set_plugin_config(self, plugin_name: str, config: dict[str, Any]) -> None:
         """
         Set plugin configuration.
@@ -681,9 +637,8 @@ class IPluginConfig(ABC):
             plugin_name: Plugin name
             config: Configuration dictionary
         """
-        pass
+        ...
     
-    @abstractmethod
     def update_plugin_config(self, plugin_name: str, key: str, value: Any) -> None:
         """
         Update plugin configuration value.
@@ -693,9 +648,8 @@ class IPluginConfig(ABC):
             key: Configuration key
             value: Configuration value
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_plugin_config_value(self, plugin_name: str, key: str, default: Any = None) -> Any:
         """
         Get plugin configuration value.
@@ -708,9 +662,8 @@ class IPluginConfig(ABC):
         Returns:
             Configuration value or default
         """
-        pass
+        ...
     
-    @abstractmethod
     def has_plugin_config(self, plugin_name: str, key: str) -> bool:
         """
         Check if plugin has configuration key.
@@ -722,9 +675,8 @@ class IPluginConfig(ABC):
         Returns:
             True if key exists
         """
-        pass
+        ...
     
-    @abstractmethod
     def remove_plugin_config(self, plugin_name: str, key: str) -> bool:
         """
         Remove plugin configuration key.
@@ -736,9 +688,8 @@ class IPluginConfig(ABC):
         Returns:
             True if removed
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_plugin_config(self, plugin_name: str) -> None:
         """
         Clear plugin configuration.
@@ -746,9 +697,8 @@ class IPluginConfig(ABC):
         Args:
             plugin_name: Plugin name
         """
-        pass
+        ...
     
-    @abstractmethod
     def save_plugin_config(self, plugin_name: str, file_path: str) -> bool:
         """
         Save plugin configuration to file.
@@ -760,9 +710,8 @@ class IPluginConfig(ABC):
         Returns:
             True if saved successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def load_plugin_config(self, plugin_name: str, file_path: str) -> bool:
         """
         Load plugin configuration from file.
@@ -774,21 +723,21 @@ class IPluginConfig(ABC):
         Returns:
             True if loaded successfully
         """
-        pass
+        ...
 
 
 # ============================================================================
 # PLUGIN EVENTS INTERFACES
 # ============================================================================
 
-class IPluginEvents(ABC):
+@runtime_checkable
+class IPluginEvents(Protocol):
     """
     Interface for plugin events.
     
     Enforces consistent plugin event handling across XWSystem.
     """
     
-    @abstractmethod
     def emit_event(self, event: PluginEvent, plugin_name: str, data: Any = None) -> None:
         """
         Emit plugin event.
@@ -798,9 +747,8 @@ class IPluginEvents(ABC):
             plugin_name: Plugin name
             data: Event data
         """
-        pass
+        ...
     
-    @abstractmethod
     def subscribe_to_event(self, event: PluginEvent, callback: Callable) -> str:
         """
         Subscribe to plugin event.
@@ -812,9 +760,8 @@ class IPluginEvents(ABC):
         Returns:
             Subscription ID
         """
-        pass
+        ...
     
-    @abstractmethod
     def unsubscribe_from_event(self, subscription_id: str) -> bool:
         """
         Unsubscribe from plugin event.
@@ -825,9 +772,8 @@ class IPluginEvents(ABC):
         Returns:
             True if unsubscribed
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_event_subscribers(self, event: PluginEvent) -> list[Callable]:
         """
         Get event subscribers.
@@ -838,9 +784,8 @@ class IPluginEvents(ABC):
         Returns:
             List of subscriber callbacks
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_event_subscribers(self, event: Optional[PluginEvent] = None) -> None:
         """
         Clear event subscribers.
@@ -848,9 +793,8 @@ class IPluginEvents(ABC):
         Args:
             event: Clear subscribers for specific event, or all if None
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_event_history(self, event: Optional[PluginEvent] = None, limit: int = 100) -> list[dict[str, Any]]:
         """
         Get event history.
@@ -862,28 +806,27 @@ class IPluginEvents(ABC):
         Returns:
             List of event history entries
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_event_history(self) -> None:
         """
         Clear event history.
         """
-        pass
+        ...
 
 
 # ============================================================================
 # PLUGIN DEPENDENCY INTERFACES
 # ============================================================================
 
-class IPluginDependency(ABC):
+@runtime_checkable
+class IPluginDependency(Protocol):
     """
     Interface for plugin dependency management.
     
     Enforces consistent plugin dependency handling across XWSystem.
     """
     
-    @abstractmethod
     def add_dependency(self, plugin_name: str, dependency: str, version: Optional[str] = None) -> None:
         """
         Add plugin dependency.
@@ -893,9 +836,8 @@ class IPluginDependency(ABC):
             dependency: Dependency name
             version: Required version
         """
-        pass
+        ...
     
-    @abstractmethod
     def remove_dependency(self, plugin_name: str, dependency: str) -> bool:
         """
         Remove plugin dependency.
@@ -907,9 +849,8 @@ class IPluginDependency(ABC):
         Returns:
             True if removed
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_dependencies(self, plugin_name: str) -> list[dict[str, Any]]:
         """
         Get plugin dependencies.
@@ -920,9 +861,8 @@ class IPluginDependency(ABC):
         Returns:
             List of dependency information
         """
-        pass
+        ...
     
-    @abstractmethod
     def check_dependencies(self, plugin_name: str) -> tuple[bool, list[str]]:
         """
         Check if plugin dependencies are satisfied.
@@ -933,9 +873,8 @@ class IPluginDependency(ABC):
         Returns:
             Tuple of (all_satisfied, missing_dependencies)
         """
-        pass
+        ...
     
-    @abstractmethod
     def resolve_dependencies(self, plugin_name: str) -> list[str]:
         """
         Resolve plugin dependency order.
@@ -946,9 +885,8 @@ class IPluginDependency(ABC):
         Returns:
             List of plugins in dependency order
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_dependents(self, plugin_name: str) -> list[str]:
         """
         Get plugins that depend on this plugin.
@@ -959,9 +897,8 @@ class IPluginDependency(ABC):
         Returns:
             List of dependent plugin names
         """
-        pass
+        ...
     
-    @abstractmethod
     def has_circular_dependency(self, plugin_name: str) -> bool:
         """
         Check for circular dependencies.
@@ -972,9 +909,8 @@ class IPluginDependency(ABC):
         Returns:
             True if circular dependency exists
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_dependency_graph(self) -> dict[str, list[str]]:
         """
         Get plugin dependency graph.
@@ -982,4 +918,4 @@ class IPluginDependency(ABC):
         Returns:
             Dependency graph dictionary
         """
-        pass
+        ...