IS-Matrix-Forge 1.0.0.dev1__py3-none-any.whl

is_matrix_forge/monitor/gui/event/collection.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+from typing import Optional
+
+from .event import MOD_LOGGER as __MOD_LOGGER, Event, Loggable
+from .errors import EventExistsError, EventLookupError
+
+__initialized = False
+
+if __initialized:
+    from ..windows.base import WindowBase
+
+
+MOD_LOGGER = __MOD_LOGGER.parent.get_child('collection')
+
+
+class EventCollection(Loggable):
+    def __init__(
+            self,
+            window: WindowBase
+    ):
+        """
+        Initializes an EventCollection instance.
+
+        This constructor sets up the logging and initializes an empty list to hold events.
+        """
+        super().__init__(MOD_LOGGER)
+        self.__events = []
+
+    def __iter__(self):
+        return iter(self.__events)
+
+    def __len__(self):
+        return len(self.__events)
+
+    @property
+    def event_names(self):
+        return [e.key for e in self.__events]
+
+    @property
+    def events(self):
+        return self.__events
+
+    @property
+    def exit_event_exists(self) -> bool:
+        """
+        Checks if an ExitEvent exists in the collection.
+
+        This method checks if any events in the collection are an instance of ExitEvent.
+
+        Returns:
+            bool:
+                True if an ExitEvent exists in the collection, False otherwise.
+        """
+        from ..event.event import ExitEvent
+
+        return any(isinstance(event, ExitEvent) for event in self.events)
+
+    @property
+    def times_failed(self):
+        """
+        The total number of times all events in the collection have failed.
+
+        This property is a shortcut to get the total number of times all events
+        in the collection have failed. It does this by summing up the `times_failed`
+        property of each event in the collection.
+
+        Returns:
+            int:
+                The total number of times all events in the collection have failed.
+        """
+        times = 0
+
+        if self.events:
+            for event in self.events:
+                times += event.times_failed
+        else:
+            self.method_logger.warn_once('No events in collection, returning 0')
+
+        return times
+
+    @property
+    def times_handled(self) -> int:
+        times = 0
+
+        if self.events:
+            for event in self.events:
+                times += event.times_handled
+        else:
+            self.method_logger.warn_once('No events in collection, returning 0')
+
+        return times
+
+    def add_event(self, event: Event) -> None:
+        if not isinstance(event, Event):
+            raise TypeError(f"event must be of type `Event`, not {type(event)}")
+
+        if event.key in self.event_names:
+            raise EventExistsError(event_name=event.key)
+
+        self.__events.append(event)
+
+    def clear(self) -> None:
+        self.method_logger.info('Clearing all events in collection...')
+        self.events.clear()
+
+    def create_event(self, key: str, callback: Optional[callable] = None) -> None:
+        if key is None and self.exit_event_exists:
+            raise EventExistsError(event_name='ExitEvent')
+        elif key is None and not self.exit_event_exists:
+            from ..event.event import ExitEvent
+            return self.add_event(ExitEvent())
+
+        key = key.upper()
+
+        if key in self.event_names:
+            raise EventExistsError(event_name=key)
+
+        return self.add_event(Event(key=key, callback=callback))
+
+    def handle_event(self, event: str, callback_args: tuple = (), callback_kwargs: Optional[dict] = None):
+        print('Reached handle_event')
+        event = self.lookup(event)
+
+        if event is None:
+            raise EventLookupError(event_name=event)
+
+        return event.handle(callback_args=callback_args, callback_kwargs=callback_kwargs)
+
+    def lookup(self, event_key: str) -> Optional[Event]:
+        """
+        Looks up an event in the collection by its key.
+
+        Parameters:
+            event_key (str):
+                The key of the event to be looked up.
+
+        Returns:
+            Event or None:
+                The event with the given key, or None if not found.
+
+        Raises:
+            TypeError:
+                If 'event_key' is not of type `str`.
+        """
+        if not isinstance(event_key, str):
+            raise TypeError(f"'event_key' must be of type `str`, not {type(event_key)}")
+
+        return next(
+            (e for e in self.__events if e.key.lower() == event_key.lower()), None
+        )
+
+
+__initialized = True

is_matrix_forge/monitor/gui/event/errors.py

@@ -0,0 +1,58 @@
+from inspyre_toolbox.exceptional import CustomRootException
+
+
+class EventError(CustomRootException):
+    default_message = 'An error occurred with event handling!'
+
+
+class EventExistsError(EventError, ValueError):
+    """
+    Raised when an event already exists in the collection.
+
+    Class Attributes:
+        default_message (str):
+            **Read-Only**. The default message for the error.
+    """
+    default_message = 'Event already exists in collection!'
+
+    def __init__(self, message: str = None, event_name: str = None, skip_print: bool = False) -> None:
+        """
+        Initializes the EventExistsError.
+
+        Parameters:
+            message (Optional[str]):
+                The error message to be displayed. If None, uses the default message.
+        """
+        if event_name is not None:
+            self.default_message = f"'{event_name}' already exists in collection!"
+        if message is not None:
+            self.default_message = f"{self.default_message}\n\n  Additional information from caller:\n    {message}"
+
+        super().__init__(message=self.default_message, skip_print=skip_print)
+
+
+class EventLookupError(EventError, ValueError):
+    """
+    Raised when an event is not found in the collection.
+
+    Class Attributes:
+        default_message (str): Read-Only. The default message for the error.
+    """
+    default_message = 'Event not found in collection!'
+
+    def __init__(self, message: str = None, event_name: str = None, skip_print: bool = False) -> None:
+        """
+        Initializes the EventLookupError.
+
+        Parameters:
+            message (Optional[str]):
+                The error message to be displayed. If None, uses the default message.
+        """
+        if event_name is not None:
+            self.default_message = f"'{event_name}' not found in collection!"
+        if message is not None:
+            self.default_message = f"{self.default_message}\n\n  Additional information from caller:\n    {message}"
+
+        self.__additional_info = 'Test'
+
+        super().__init__(message=self.default_message, skip_print=skip_print)

is_matrix_forge/monitor/gui/event/event.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+from typing import Optional
+from is_matrix_forge.log_engine import ROOT_LOGGER as PARENT_LOGGER, Loggable
+from dataclasses import dataclass, field
+
+
+__initialized = False
+
+
+if __initialized:
+    from ..windows.base import WindowBase
+
+
+MOD_LOGGER = PARENT_LOGGER.get_child('monitor.gui.event.event')
+
+
+@dataclass
+class ElementArgMap():
+    pos_args: tuple = field(default_factory=tuple)
+    kw_args: dict = field(default_factory=dict)
+
+
+class Event(Loggable):
+    def __init__(
+            self,
+            key: Optional[str],
+            window: WindowBase,
+            callback: Optional[callable] = None,
+            element_arg_map: Optional[dict] = None,
+
+    ) -> None:
+        """
+        Initializes the Event.
+
+        Parameters:
+            key (str):
+                The unique string identifier for the event.
+
+            callback (Optional[callable]):
+                The callable to be called when the event is triggered.
+
+            pass_window_values (bool):
+                Whether to pass window values to the callback function.
+        """
+        super().__init__(MOD_LOGGER)
+        self.__callback      = None
+        self.__failed        = 0
+        self.__initialized   = False
+        self.__key           = None
+        self.__times_handled = 0
+
+        self.key = key
+
+        if callback is not None:
+            self.callback = callback
+
+        self.__initialized = True
+
+    @property
+    def callback(self) -> callable:
+        """
+        The callback function for the event.
+
+        The callback function is called whenever the event is triggered. The
+        function should accept zero or more arguments.
+
+        Returns:
+            callable:
+                The callback function for the event.
+
+        Raises:
+            TypeError:
+                If the callback is not callable.
+
+        """
+        return self.__callback
+
+    @callback.setter
+    def callback(self, new: callable) -> None:
+        """
+        The callback function for the event.
+
+        The callback function is called whenever the event is triggered. The
+        function should accept zero or more arguments.
+
+        Parameters:
+            new (callable):
+                The new value for the callback.
+
+        Raises:
+            TypeError:
+                If the new value is not callable.
+        """
+        if not callable(new):
+            raise TypeError(f"callback must be callable, not {type(new)}")
+
+        self.__callback = new
+
+    @property
+    def times_failed(self) -> int:
+        """
+        The number of times the callback function has failed. (**Read-Only**)
+
+        If the callback function fails, an error is raised and the number of
+        times it has failed is incremented.
+
+        Returns:
+            int:
+                The number of times the callback function has failed.
+        """
+        return self.__failed
+
+
+    @property
+    def key(self):
+        """
+        The key of the event.
+
+        The key is the identifier for this event. It is used to look up the event
+        in the collection.
+
+        Returns:
+            str:
+                The key of the event.
+        """
+        return self.__key
+
+    @key.setter
+    def key(self, new: Optional[str]):
+        """
+        The key of the event.
+
+        The key is the identifier for this event. It is used to look up the event
+        in the collection.
+
+        If the event is an `ExitEvent` (a special event given to every window
+        handler collection), the key is allowed to be `None`. Otherwise, the key
+        must be a string.
+
+        Parameters:
+            new (Optional[str]):
+                The new key of the event.
+
+        Raises:
+            RuntimeError:
+                If the key is changed after initialization.
+            TypeError:
+                If the new key is not a string.
+        """
+        # Allow for `key` to allow `None` as a value if it is from `ExitEvent` (a special event given to every window
+        # handler collection)
+        if new is None and isinstance(self, ExitEvent):
+            self._Event__key = None
+            return
+
+        if self.__initialized:
+            raise RuntimeError("Cannot change key after initialization")
+
+        if not isinstance(new, str):
+            raise TypeError(f"key must be of type `str`, not {type(new)}")
+
+        self.__key = new.upper()
+
+    @property
+    def times_handled(self):
+        """
+        The number of times the event has been handled.
+
+        This property returns the count of how many times the `handle` method
+        has been invoked for this event.
+
+        Returns:
+            int:
+                The number of times the event has been handled.
+        """
+        return self.__times_handled
+
+    def handle(self, callback_args: tuple = (), callback_kwargs: Optional[dict] = None):
+        """
+        Handles an event by calling the associated callback.
+
+        Parameters:
+            callback_args (tuple):
+                The arguments to be passed to the callback.
+
+            callback_kwargs (Optional[dict]):
+                The keyword arguments to be passed to the callback.
+
+        Returns:
+            Any:
+                The return value of the callback, or None if no callback is associated with the event.
+        """
+        if callback_kwargs is None:
+            callback_kwargs = {}
+
+        self.__times_handled += 1
+
+        if self.callback:
+            try:
+                return self.callback(*callback_args, **callback_kwargs)
+            except Exception as e:
+                self.__failed += 1
+                raise e from e
+
+        return None
+
+
+class ExitEvent(Event):
+    """
+    A special event that can be applied to any PySimpleGUI main loop to recognize and handle a press of the 'X' button.
+    """
+    def __init__(self):
+        super().__init__(key=None,)
+
+    @property
+    def key(self) -> None:
+        return None
+
+    @key.setter
+    def key(self, new: None) -> None:
+        raise ValueError('The key of an ExitEvent cannot be set.')
+
+
+__initialized = True
+

is_matrix_forge/monitor/gui/layout/__init__.py

@@ -0,0 +1,8 @@
+"""
+Author: Taylor B. tayjaybabee@gmail.com
+Date: 2025-05-02 16:04:13
+LastEditors: Taylor B. tayjaybabee@gmail.com
+LastEditTime: 2025-05-02 16:13:48
+FilePath: is_matrix_forge/monitor/gui/layout/__init__.py
+Description: 这是默认设置,可以在设置》工具》File Description中进行配置
+"""

is_matrix_forge/monitor/gui/layout/base.py

@@ -0,0 +1,147 @@
+from abc import abstractmethod
+import copy
+
+from is_matrix_forge.log_engine import ROOT_LOGGER, Loggable
+from is_matrix_forge.monitor.gui.metaclasses import SingletonABCMeta
+from inspyre_toolbox.exceptional import CustomRootException
+
+
+class LayoutError(CustomRootException):
+    default_message = 'An error occurred with the layout!'
+
+
+class LayoutNotBuiltError(LayoutError):
+    """
+    Raised when the layout is not built yet.
+
+    Class Attributes:
+        default_message (str):
+            **Read-Only**. The default message for the error.
+    """
+    default_message = 'Layout not built yet!'
+
+
+class LayoutAlreadyBuiltError(LayoutError):
+    """
+    Raised when the layout is already built.
+
+    Class Attributes:
+        default_message (str):
+            **Read-Only**. The default message for the error.
+    """
+    default_message = 'Layout already built!'
+
+
+LOGGER = ROOT_LOGGER.get_child('monitor.gui.layout.base')
+
+
+class Layout(Loggable, metaclass=SingletonABCMeta):
+
+    @property
+    @abstractmethod
+    def BLUEPRINT(self):
+        """Return a 2D list of PySimpleGUI elements used to build this layout."""
+        raise NotImplementedError
+
+    def __init__(self, with_logging_parent=None):
+        if with_logging_parent is None:
+            with_logging_parent = LOGGER
+
+        super().__init__(with_logging_parent)
+
+        self.__layout   = None
+        self.__is_built = False
+
+    @property
+    def built(self):
+        """
+        Check if the layout has been built.
+
+        Returns:
+            bool:
+                True if the layout has been built, False otherwise.
+        """
+        return self.__is_built
+
+    @property
+    def layout(self):
+        """
+        Get a fresh deep-copy of the built layout.
+
+        Returns:
+            List[List[PySimpleGUI.Element]]:
+                A 2D list of `PySimpleGUI` elements representing the layout.
+
+        Raises:
+            LayoutNotBuiltError:
+                If the layout has not been built yet.
+        """
+        log = self.method_logger
+        if not self.built:
+            log.warning('Attempted to access layout before it was built!')
+            raise LayoutNotBuiltError()
+
+        if self.__layout is None:
+            err_msg = 'Layout is None, but built is True!'
+            log.warning(err_msg)
+            raise LayoutNotBuiltError(err_msg)
+
+        log.debug('Returning a deep-copy of the layout.')
+        return copy.deepcopy(self.__layout)
+
+    def build(self):
+        """
+        Build the layout from the `BLUEPRINT` attribute once.
+
+        Returns:
+            List[List[PySimpleGUI.Element]]:
+                A 2D list of `PySimpleGUI` elements representing the layout, deep-copied.
+
+        Raises:
+            LayoutAlreadyBuiltError:
+                If the layout has already been built.
+        """
+        log = self.method_logger
+        if self.built:
+            log.warning('Attempted to build layout when it was already built!')
+            raise LayoutAlreadyBuiltError()
+
+        blueprint = self.BLUEPRINT
+        if not isinstance(blueprint, list) or not all(isinstance(r, list) for r in blueprint):
+            raise LayoutError('BLUEPRINT must be a 2D list of PySimpleGUI elements.')
+
+        self.__layout   = copy.deepcopy(blueprint)
+        log.debug('Layout built successfully.')
+        self.__is_built = True
+        log.debug('Marked layout as built.')
+
+        return self.layout
+
+    def rebuild(self):
+        """
+        Clear the current layout and build a new one from `BLUEPRINT`.
+
+        Returns:
+            List[List[PySimpleGUI.Element]]:
+                A 2D list of `PySimpleGUI` elements representing the layout, deep-copied.
+
+        Raises:
+            LayoutNotBuiltError:
+                If the layout has not been built yet.
+        """
+        log = self.method_logger
+
+        if not self.built:
+            log.warning('Attempted to rebuild layout when it was not built yet!')
+            raise LayoutNotBuiltError('Cannot rebuild layout when it was not built yet!')
+
+        log.debug('Rebuilding layout...')
+        log.debug('Clearing current layout...')
+
+        self.__layout   = None
+        log.debug('Layout set to None.')
+        self.__is_built = False
+        log.debug('Layout marked as not built.')
+        log.debug('Building new layout and returning...')
+
+        return self.build()

is_matrix_forge/monitor/gui/metaclasses/__init__.py

@@ -0,0 +1,20 @@
+from abc import ABCMeta
+from threading import Lock
+
+
+class SingletonABCMeta(ABCMeta):
+    """
+    A metaclass that ensures all subclasses are singletons.
+
+    This metaclass can be combined with abstract base classes
+    to make all concrete subclasses singletons.
+    """
+    _instances = {}
+    _lock = Lock()
+
+    def __call__(cls, *args, **kwargs):
+        with SingletonABCMeta._lock:
+            if cls not in SingletonABCMeta._instances:
+                instance = super().__call__(*args, **kwargs)
+                SingletonABCMeta._instances[cls] = instance
+            return SingletonABCMeta._instances[cls]