orionis 0.513.0__py3-none-any.whl → 0.515.0__py3-none-any.whl

orionis/console/tasks/schedule.py

@@ -1,38 +1,45 @@
 import asyncio
 from datetime import datetime
 import logging
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Union
 import pytz
 from apscheduler.events import (
-    EVENT_JOB_ERROR,
-    EVENT_JOB_EXECUTED,
-    EVENT_JOB_MISSED,
-    EVENT_JOB_SUBMITTED,
+    EVENT_SCHEDULER_STARTED,
     EVENT_SCHEDULER_PAUSED,
     EVENT_SCHEDULER_RESUMED,
     EVENT_SCHEDULER_SHUTDOWN,
-    EVENT_SCHEDULER_STARTED,
-    EVENT_JOB_MAX_INSTANCES
+    EVENT_JOB_ERROR,
+    EVENT_JOB_SUBMITTED,
+    EVENT_JOB_EXECUTED,
+    EVENT_JOB_MISSED,
+    EVENT_JOB_MAX_INSTANCES,
+    EVENT_JOB_MODIFIED,
+    EVENT_JOB_REMOVED
 )
 from apscheduler.schedulers.asyncio import AsyncIOScheduler as APSAsyncIOScheduler
 from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
+from orionis.console.contracts.event import IEvent
 from orionis.console.contracts.reactor import IReactor
 from orionis.console.contracts.schedule import ISchedule
+from orionis.console.contracts.schedule_event_listener import IScheduleEventListener
 from orionis.console.entities.job_error import JobError
 from orionis.console.entities.job_executed import JobExecuted
 from orionis.console.entities.job_max_instances import JobMaxInstances
 from orionis.console.entities.job_missed import JobMissed
+from orionis.console.entities.job_modified import JobModified
+from orionis.console.entities.job_removed import JobRemoved
 from orionis.console.entities.job_submitted import JobSubmitted
 from orionis.console.entities.scheduler_paused import SchedulerPaused
 from orionis.console.entities.scheduler_resumed import SchedulerResumed
 from orionis.console.entities.scheduler_shutdown import SchedulerShutdown
 from orionis.console.entities.scheduler_started import SchedulerStarted
 from orionis.console.enums.listener import ListeningEvent
+from orionis.console.enums.event import Event as EventEntity
 from orionis.console.exceptions import CLIOrionisRuntimeError
+from orionis.console.exceptions.cli_orionis_value_error import CLIOrionisValueError
 from orionis.console.output.contracts.console import IConsole
-from orionis.console.tasks.event import Event
 from orionis.foundation.contracts.application import IApplication
 from orionis.services.log.contracts.log_service import ILogger
 
@@ -97,10 +104,10 @@ class Scheduler(ISchedule):
         self.__available_commands = self.__getCommands()
 
         # Initialize the jobs dictionary to keep track of scheduled jobs.
-        self.__events: Dict[str, Event] = {}
+        self.__events: Dict[str, IEvent] = {}
 
         # Initialize the jobs list to keep track of all scheduled jobs.
-        self.__jobs: List[dict] = []
+        self.__jobs: List[EventEntity] = []
 
         # Initialize the listeners dictionary to manage event listeners.
         self.__listeners: Dict[str, callable] = {}
@@ -121,10 +128,166 @@ class Scheduler(ISchedule):
             formatted as "YYYY-MM-DD HH:MM:SS".
         """
 
+        # Get the current time in the configured timezone
         tz = pytz.timezone(self.__app.config("app.timezone", "UTC"))
         now = datetime.now(tz)
+
+        # Format the current time as a string
         return now.strftime("%Y-%m-%d %H:%M:%S")
 
+    def __getCommands(
+        self
+    ) -> dict:
+        """
+        Retrieve available commands from the reactor and return them as a dictionary.
+
+        This method queries the reactor for all available jobs/commands, extracting their
+        signatures and descriptions. The result is a dictionary where each key is the command
+        signature and the value is another dictionary containing the command's signature and
+        its description.
+
+        Returns
+        -------
+        dict
+            A dictionary mapping command signatures to their details. Each value is a dictionary
+            with 'signature' and 'description' keys.
+        """
+
+        # Initialize the commands dictionary
+        commands = {}
+
+        # Iterate over all jobs provided by the reactor's info method
+        for job in self.__reactor.info():
+
+            # Store each job's signature and description in the commands dictionary
+            commands[job['signature']] = {
+                'signature': job['signature'],
+                'description': job.get('description', '')
+            }
+
+        # Return the commands dictionary
+        return commands
+
+    def __isAvailable(
+        self,
+        signature: str
+    ) -> bool:
+        """
+        Check if a command with the given signature is available.
+
+        This method iterates through the available commands and determines
+        whether the provided signature matches any registered command.
+
+        Parameters
+        ----------
+        signature : str
+            The signature of the command to check for availability.
+
+        Returns
+        -------
+        bool
+            True if the command with the specified signature exists and is available,
+            False otherwise.
+        """
+
+        # Iterate through all available command signatures
+        for command in self.__available_commands.keys():
+
+            # Return True if the signature matches an available command
+            if command == signature:
+                return True
+
+        # Return False if the signature is not found among available commands
+        return False
+
+    def __getDescription(
+        self,
+        signature: str
+    ) -> Optional[str]:
+        """
+        Retrieve the description of a command given its signature.
+
+        This method looks up the available commands dictionary and returns the description
+        associated with the provided command signature. If the signature does not exist,
+        it returns None.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature identifying the command.
+
+        Returns
+        -------
+        Optional[str]
+            The description of the command if found; otherwise, None.
+        """
+
+        # Attempt to retrieve the command entry from the available commands dictionary
+        command_entry = self.__available_commands.get(signature)
+
+        # Return the description if the command exists, otherwise return None
+        return command_entry['description'] if command_entry else None
+
+    def command(
+        self,
+        signature: str,
+        args: Optional[List[str]] = None
+    ) -> 'IEvent':
+        """
+        Prepare an Event instance for a given command signature and its arguments.
+
+        This method validates the provided command signature and arguments, ensuring
+        that the command exists among the registered commands and that the arguments
+        are in the correct format. If validation passes, it creates and returns an
+        Event object representing the scheduled command, including its signature,
+        arguments, and description.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature identifying the command to be scheduled. Must be a non-empty string.
+        args : Optional[List[str]], optional
+            A list of string arguments to be passed to the command. Defaults to None.
+
+        Returns
+        -------
+        Event
+            An Event instance containing the command signature, arguments, and its description.
+
+        Raises
+        ------
+        ValueError
+            If the command signature is not a non-empty string, if the arguments are not a list
+            of strings or None, or if the command does not exist among the registered commands.
+        """
+
+        # Prevent adding new commands while the scheduler is running
+        if self.__scheduler.running:
+            raise CLIOrionisRuntimeError("Cannot add new commands while the scheduler is running.")
+
+        # Validate that the command signature is a non-empty string
+        if not isinstance(signature, str) or not signature.strip():
+            raise CLIOrionisValueError("Command signature must be a non-empty string.")
+
+        # Ensure that arguments are either a list of strings or None
+        if args is not None and not isinstance(args, list):
+            raise CLIOrionisValueError("Arguments must be a list of strings or None.")
+
+        # Check if the command is available in the registered commands
+        if not self.__isAvailable(signature):
+            raise CLIOrionisValueError(f"The command '{signature}' is not available or does not exist.")
+
+        # Store the command and its arguments for scheduling
+        from orionis.console.tasks.event import Event
+        self.__events[signature] = Event(
+            signature=signature,
+            args=args or [],
+            purpose=self.__getDescription(signature)
+        )
+
+        # Return the Event instance for further scheduling configuration
+        return self.__events[signature]
+
     def __suscribeListeners(
         self
     ) -> None:
@@ -146,32 +309,131 @@ class Scheduler(ISchedule):
             This method does not return any value. It configures event listeners on the scheduler.
         """
 
-        # Add a listener for the scheduler started event
         self.__scheduler.add_listener(self.__startedListener, EVENT_SCHEDULER_STARTED)
-
-        # Add a listener for the scheduler shutdown event
+        self.__scheduler.add_listener(self.__pausedListener, EVENT_SCHEDULER_PAUSED)
+        self.__scheduler.add_listener(self.__resumedListener, EVENT_SCHEDULER_RESUMED)
         self.__scheduler.add_listener(self.__shutdownListener, EVENT_SCHEDULER_SHUTDOWN)
+        self.__scheduler.add_listener(self.__errorListener, EVENT_JOB_ERROR)
+        self.__scheduler.add_listener(self.__submittedListener, EVENT_JOB_SUBMITTED)
+        self.__scheduler.add_listener(self.__executedListener, EVENT_JOB_EXECUTED)
+        self.__scheduler.add_listener(self.__missedListener, EVENT_JOB_MISSED)
+        self.__scheduler.add_listener(self.__maxInstancesListener, EVENT_JOB_MAX_INSTANCES)
+        self.__scheduler.add_listener(self.__modifiedListener, EVENT_JOB_MODIFIED)
+        self.__scheduler.add_listener(self.__removedListener, EVENT_JOB_REMOVED)
 
-        # Add a listener for the scheduler paused event
-        self.__scheduler.add_listener(self.__pausedListener, EVENT_SCHEDULER_PAUSED)
+    def __globalCallableListener(
+        self,
+        event_data: Optional[Union[SchedulerStarted, SchedulerPaused, SchedulerResumed, SchedulerShutdown, JobError]],
+        listening_vent: ListeningEvent
+    ) -> None:
+        """
+        Invoke registered listeners for global scheduler events.
 
-        # Add a listener for the scheduler resumed event
-        self.__scheduler.add_listener(self.__resumedListener, EVENT_SCHEDULER_RESUMED)
+        This method handles global scheduler events such as when the scheduler starts, pauses, resumes,
+        or shuts down. It checks if a listener is registered for the specified event and invokes it if callable.
+        The listener can be either a coroutine or a regular function.
 
-        # Add a listener for job submission events
-        self.__scheduler.add_listener(self.__submittedListener, EVENT_JOB_SUBMITTED)
+        Parameters
+        ----------
+        event_data : Optional[Union[SchedulerStarted, SchedulerPaused, SchedulerResumed, SchedulerShutdown, JobError]]
+            The event data associated with the global scheduler event. This can include details about the event,
+            such as its type and context. If no specific data is available, this parameter can be None.
+        listening_vent : ListeningEvent
+            An instance of the ListeningEvent enum representing the global scheduler event to handle.
 
-        # Add a listener for job execution events
-        self.__scheduler.add_listener(self.__executedListener, EVENT_JOB_EXECUTED)
+        Returns
+        -------
+        None
+            This method does not return any value. It invokes the registered listener for the specified event,
+            if one exists.
 
-        # Add a listener for missed job events
-        self.__scheduler.add_listener(self.__missedListener, EVENT_JOB_MISSED)
+        Raises
+        ------
+        CLIOrionisValueError
+            If the provided `listening_vent` is not an instance of ListeningEvent.
+        """
 
-        # Add a listener for job error events
-        self.__scheduler.add_listener(self.__errorListener, EVENT_JOB_ERROR)
+        # Validate that the provided event is an instance of ListeningEvent
+        if not isinstance(listening_vent, ListeningEvent):
+            raise CLIOrionisValueError("The event must be an instance of ListeningEvent.")
 
-        # Add a listener for job max instances events
-        self.__scheduler.add_listener(self.__maxInstancesListener, EVENT_JOB_MAX_INSTANCES)
+        # Retrieve the global identifier for the event from the ListeningEvent enum
+        scheduler_event = listening_vent.value
+
+        # Check if a listener is registered for the specified event
+        if scheduler_event in self.__listeners:
+            listener = self.__listeners[scheduler_event]
+
+            # Ensure the listener is callable before invoking it
+            if callable(listener):
+                # If the listener is a coroutine, schedule it as an asyncio task
+                if asyncio.iscoroutinefunction(listener):
+                    asyncio.create_task(listener(event_data, self))
+                # Otherwise, invoke the listener directly as a regular function
+                else:
+                    listener(event_data, self)
+
+    def __taskCallableListener(
+        self,
+        event_data: Optional[Union[JobError, JobExecuted, JobSubmitted, JobMissed, JobMaxInstances]],
+        listening_vent: ListeningEvent
+    ) -> None:
+        """
+        Invoke registered listeners for specific task/job events.
+
+        This method handles task/job-specific events such as job errors, executions, submissions,
+        missed jobs, and max instance violations. It checks if a listener is registered for the
+        specific job ID associated with the event and invokes the appropriate method on the listener
+        if callable. The listener can be either a coroutine or a regular function.
+
+        Parameters
+        ----------
+        event_data : Optional[Union[JobError, JobExecuted, JobSubmitted, JobMissed, JobMaxInstances]]
+            The event data associated with the task/job event. This includes details about the job,
+            such as its ID, exception (if any), and other context. If no specific data is available,
+            this parameter can be None.
+        listening_vent : ListeningEvent
+            An instance of the ListeningEvent enum representing the task/job event to handle.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It invokes the registered listener for the
+            specified job event, if one exists.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the provided `listening_vent` is not an instance of ListeningEvent.
+        """
+
+        # Validate that the provided event is an instance of ListeningEvent
+        if not isinstance(listening_vent, ListeningEvent):
+            raise CLIOrionisValueError("The event must be an instance of ListeningEvent.")
+
+        # Retrieve the global identifier for the event from the ListeningEvent enum
+        scheduler_event = listening_vent.value
+
+        # Check if a listener is registered for the specific job ID in the event data
+        if event_data.job_id in self.__listeners:
+
+            # Retrieve the listener for the specific job ID
+            listener = self.__listeners[event_data.job_id]
+
+            # Check if the listener is an instance of IScheduleEventListener
+            if isinstance(listener, IScheduleEventListener):
+
+                # Check if the listener has a method corresponding to the event type
+                if hasattr(listener, scheduler_event) and callable(getattr(listener, scheduler_event)):
+                    listener_method = getattr(listener, scheduler_event)
+
+                    # Invoke the listener method, handling both coroutine and regular functions
+                    if asyncio.iscoroutinefunction(listener_method):
+                        # Schedule the coroutine listener method as an asyncio task
+                        asyncio.create_task(listener_method(event_data, self))
+                    else:
+                        # Call the regular listener method directly
+                        listener_method(event_data, self)
 
     def __startedListener(
         self,
@@ -225,68 +487,8 @@ class Scheduler(ISchedule):
         # Add another blank line for better formatting
         self.__rich_console.line()
 
-        # Retrieve the global identifier for the scheduler started event
-        scheduler_started = ListeningEvent.SCHEDULER_STARTED.value
-
         # Check if a listener is registered for the scheduler started event
-        if scheduler_started in self.__listeners:
-            listener = self.__listeners[scheduler_started]
-
-            # Ensure the listener is callable before invoking it
-            if callable(listener):
-
-                # Invoke the registered listener with the event details
-                listener(event)
-
-    def __shutdownListener(
-        self,
-        event: SchedulerShutdown
-    ) -> None:
-        """
-        Handle the scheduler shutdown event for logging and invoking registered listeners.
-
-        This method is triggered when the scheduler shuts down. It logs an informational
-        message indicating that the scheduler has shut down successfully and displays
-        a formatted message on the rich console. If a listener is registered for the
-        scheduler shutdown event, it invokes the listener with the event details.
-
-        Parameters
-        ----------
-        event : SchedulerShutdown
-            An event object containing details about the scheduler shutdown event.
-
-        Returns
-        -------
-        None
-            This method does not return any value. It performs logging, displays
-            a message on the console, and invokes any registered listener for the
-            scheduler shutdown event.
-        """
-
-        # Get the current time in the configured timezone
-        now = self.__getCurrentTime()
-
-        # Create a shutdown message
-        message = f"Orionis Scheduler shut down successfully at {now}."
-
-        # Log an informational message indicating that the scheduler has shut down
-        self.__logger.info(message)
-
-        # Display a shutdown message for the scheduler worker on console
-        if self.__app.config('app.debug', False):
-            self.__console.info(message)
-
-        # Retrieve the global identifier for the scheduler shutdown event
-        scheduler_shutdown = GlobalListener.SCHEDULER_SHUTDOWN.value
-
-        # Check if a listener is registered for the scheduler shutdown event
-        if scheduler_shutdown in self.__listeners:
-            listener = self.__listeners[scheduler_shutdown]
-
-            # Ensure the listener is callable before invoking it
-            if callable(listener):
-                # Invoke the registered listener with the event details
-                listener(event)
+        self.__globalCallableListener(event, ListeningEvent.SCHEDULER_STARTED)
 
     def __pausedListener(
         self,
@@ -326,17 +528,8 @@ class Scheduler(ISchedule):
         if self.__app.config('app.debug', False):
             self.__console.info(message)
 
-        # Retrieve the global identifier for the scheduler paused event
-        scheduler_paused = GlobalListener.SCHEDULER_PAUSED.value
-
-        # Check if a listener is registered for the scheduler paused event
-        if scheduler_paused in self.__listeners:
-            listener = self.__listeners[scheduler_paused]
-
-            # Ensure the listener is callable before invoking it
-            if callable(listener):
-                # Invoke the registered listener with the event details
-                listener(event)
+        # Check if a listener is registered for the scheduler started event
+        self.__globalCallableListener(event, ListeningEvent.SCHEDULER_PAUSED)
 
     def __resumedListener(
         self,
@@ -376,17 +569,90 @@ class Scheduler(ISchedule):
         if self.__app.config('app.debug', False):
             self.__console.info(message)
 
-        # Retrieve the global identifier for the scheduler resumed event
-        scheduler_resumed = GlobalListener.SCHEDULER_RESUMED.value
+        # Check if a listener is registered for the scheduler started event
+        self.__globalCallableListener(event, ListeningEvent.SCHEDULER_RESUMED)
+
+    def __shutdownListener(
+        self,
+        event: SchedulerShutdown
+    ) -> None:
+        """
+        Handle the scheduler shutdown event for logging and invoking registered listeners.
+
+        This method is triggered when the scheduler shuts down. It logs an informational
+        message indicating that the scheduler has shut down successfully and displays
+        a formatted message on the rich console. If a listener is registered for the
+        scheduler shutdown event, it invokes the listener with the event details.
+
+        Parameters
+        ----------
+        event : SchedulerShutdown
+            An event object containing details about the scheduler shutdown event.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs logging, displays
+            a message on the console, and invokes any registered listener for the
+            scheduler shutdown event.
+        """
+
+        # Get the current time in the configured timezone
+        now = self.__getCurrentTime()
+
+        # Create a shutdown message
+        message = f"Orionis Scheduler shut down successfully at {now}."
+
+        # Log an informational message indicating that the scheduler has shut down
+        self.__logger.info(message)
+
+        # Display a shutdown message for the scheduler worker on console
+        if self.__app.config('app.debug', False):
+            self.__console.info(message)
+
+        # Check if a listener is registered for the scheduler started event
+        self.__globalCallableListener(event, ListeningEvent.SCHEDULER_SHUTDOWN)
+
+    def __errorListener(
+        self,
+        event: JobError
+    ) -> None:
+        """
+        Handle job error events for logging and error reporting.
+
+        This method is triggered when a job execution results in an error. It logs an error
+        message indicating the job ID and the exception raised. If the application is in
+        debug mode, it also reports the error using the error reporter. Additionally, if a
+        listener is registered for the errored job, it invokes the listener with the event details.
+
+        Parameters
+        ----------
+        event : JobError
+            An instance of the JobError event containing details about the errored job,
+            including its ID and the exception raised.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs logging, error reporting,
+            and listener invocation for the job error event.
+        """
 
-        # Check if a listener is registered for the scheduler resumed event
-        if scheduler_resumed in self.__listeners:
-            listener = self.__listeners[scheduler_resumed]
+        # Create an error message
+        message = f"Task {event.job_id} raised an exception: {event.exception}"
+
+        # Log an error message indicating that the job raised an exception
+        self.__logger.error(message)
+
+        # If the application is in debug mode, display a message on the console
+        if self.__app.config('app.debug', False):
+            self.__console.error(message)
+
+        # If a listener is registered for this job ID, invoke the listener with the event details
+        self.__taskCallableListener(event, ListeningEvent.JOB_ON_FAILURE)
 
-            # Ensure the listener is callable before invoking it
-            if callable(listener):
-                # Invoke the registered listener with the event details
-                listener(event)
+        # Check if a listener is registered for the scheduler started event
+        self.__globalCallableListener(event, ListeningEvent.SCHEDULER_ERROR)
 
     def __submittedListener(
         self,
@@ -424,14 +690,7 @@ class Scheduler(ISchedule):
             self.__console.info(message)
 
         # If a listener is registered for this job ID, invoke the listener with the event details
-        if event.job_id in self.__listeners:
-            listener = self.__listeners[event.job_id]
-
-            # Ensure the listener is callable before invoking it
-            if callable(listener):
-
-                # Invoke the registered listener with the event details
-                listener(event)
+        self.__taskCallableListener(event, ListeningEvent.JOB_BEFORE)
 
     def __executedListener(
         self,
@@ -470,14 +729,7 @@ class Scheduler(ISchedule):
             self.__console.info(message)
 
         # If a listener is registered for this job ID, invoke the listener with the event details
-        if event.job_id in self.__listeners:
-            listener = self.__listeners[event.job_id]
-
-            # Ensure the listener is callable before invoking it
-            if callable(listener):
-
-                # Invoke the registered listener with the event details
-                listener(event)
+        self.__taskCallableListener(event, ListeningEvent.JOB_AFTER)
 
     def __missedListener(
         self,
@@ -516,59 +768,7 @@ class Scheduler(ISchedule):
             self.__console.warning(message)
 
         # If a listener is registered for this job ID, invoke the listener with the event details
-        if event.job_id in self.__listeners:
-            listener = self.__listeners[event.job_id]
-
-            # Ensure the listener is callable before invoking it
-            if callable(listener):
-
-                # Invoke the registered listener with the event details
-                listener(event)
-
-    def __errorListener(
-        self,
-        event: JobError
-    ) -> None:
-        """
-        Handle job error events for logging and error reporting.
-
-        This method is triggered when a job execution results in an error. It logs an error
-        message indicating the job ID and the exception raised. If the application is in
-        debug mode, it also reports the error using the error reporter. Additionally, if a
-        listener is registered for the errored job, it invokes the listener with the event details.
-
-        Parameters
-        ----------
-        event : JobError
-            An instance of the JobError event containing details about the errored job,
-            including its ID and the exception raised.
-
-        Returns
-        -------
-        None
-            This method does not return any value. It performs logging, error reporting,
-            and listener invocation for the job error event.
-        """
-
-        # Create an error message
-        message = f"Task {event.job_id} raised an exception: {event.exception}"
-
-        # Log an error message indicating that the job raised an exception
-        self.__logger.error(message)
-
-        # If the application is in debug mode, display a message on the console
-        if self.__app.config('app.debug', False):
-            self.__console.error(message)
-
-        # If a listener is registered for this job ID, invoke the listener with the event details
-        if event.job_id in self.__listeners:
-            listener = self.__listeners[event.job_id]
-
-            # Ensure the listener is callable before invoking it
-            if callable(listener):
-
-                # Invoke the registered listener with the event details
-                listener(event)
+        self.__taskCallableListener(event, ListeningEvent.JOB_ON_MISSED)
 
     def __maxInstancesListener(
         self,
@@ -607,107 +807,87 @@ class Scheduler(ISchedule):
             self.__console.error(message)
 
         # If a listener is registered for this job ID, invoke the listener with the event details
-        if event.job_id in self.__listeners:
-            listener = self.__listeners[event.job_id]
-
-            # Ensure the listener is callable before invoking it
-            if callable(listener):
-
-                # Invoke the registered listener with the event details
-                listener(event)
-
-    def __getCommands(
-        self
-    ) -> dict:
-        """
-        Retrieve available commands from the reactor and return them as a dictionary.
-
-        This method queries the reactor for all available jobs/commands, extracting their
-        signatures and descriptions. The result is a dictionary where each key is the command
-        signature and the value is another dictionary containing the command's signature and
-        its description.
-
-        Returns
-        -------
-        dict
-            A dictionary mapping command signatures to their details. Each value is a dictionary
-            with 'signature' and 'description' keys.
-        """
-
-        # Initialize the commands dictionary
-        commands = {}
-
-        # Iterate over all jobs provided by the reactor's info method
-        for job in self.__reactor.info():
-
-            # Store each job's signature and description in the commands dictionary
-            commands[job['signature']] = {
-                'signature': job['signature'],
-                'description': job.get('description', '')
-            }
-
-        # Return the commands dictionary
-        return commands
+        self.__taskCallableListener(event, ListeningEvent.JOB_ON_MAXINSTANCES)
 
-    def __isAvailable(
+    def __modifiedListener(
         self,
-        signature: str
-    ) -> bool:
+        event: JobModified
+    ) -> None:
         """
-        Check if a command with the given signature is available.
+        Handle job modified events for logging and error reporting.
 
-        This method iterates through the available commands and determines
-        whether the provided signature matches any registered command.
+        This method is triggered when a job is modified. It logs an informational
+        message indicating that the job has been modified successfully. If the application
+        is in debug mode, it also displays a message on the console. Additionally, if a
+        listener is registered for the modified job, it invokes the listener with the
+        event details.
 
         Parameters
         ----------
-        signature : str
-            The signature of the command to check for availability.
+        event : JobModified
+            An instance of the JobModified event containing details about the modified job,
+            including its ID and other relevant information.
 
         Returns
         -------
-        bool
-            True if the command with the specified signature exists and is available,
-            False otherwise.
+        None
+            This method does not return any value. It performs logging, error reporting,
+            and listener invocation for the job modified event.
         """
 
-        # Iterate through all available command signatures
-        for command in self.__available_commands.keys():
+        # Create a modified message
+        message = f"Task {event.job_id} has been modified."
 
-            # Return True if the signature matches an available command
-            if command == signature:
-                return True
+        # Log an informational message indicating that the job has been modified
+        self.__logger.info(message)
 
-        # Return False if the signature is not found among available commands
-        return False
+        # If the application is in debug mode, display a message on the console
+        if self.__app.config('app.debug', False):
+            self.__console.info(message)
 
-    def __getDescription(
+        # If a listener is registered for this job ID, invoke the listener with the event details
+        if event.next_run_time is None:
+            self.__taskCallableListener(event, ListeningEvent.JOB_ON_PAUSED)
+        else:
+            self.__taskCallableListener(event, ListeningEvent.JOB_ON_RESUMED)
+
+    def __removedListener(
         self,
-        signature: str
-    ) -> Optional[str]:
+        event: JobRemoved
+    ) -> None:
         """
-        Retrieve the description of a command given its signature.
+        Handle job removal events for logging and invoking registered listeners.
 
-        This method looks up the available commands dictionary and returns the description
-        associated with the provided command signature. If the signature does not exist,
-        it returns None.
+        This method is triggered when a job is removed from the scheduler. It logs an informational
+        message indicating that the job has been removed successfully. If the application is in debug
+        mode, it displays a message on the console. Additionally, if a listener is registered for the
+        removed job, it invokes the listener with the event details.
 
         Parameters
         ----------
-        signature : str
-            The unique signature identifying the command.
+        event : JobRemoved
+            An instance of the JobRemoved event containing details about the removed job,
+            including its ID and other relevant information.
 
         Returns
         -------
-        Optional[str]
-            The description of the command if found; otherwise, None.
+        None
+            This method does not return any value. It performs logging and invokes any registered
+            listener for the job removal event.
         """
 
-        # Attempt to retrieve the command entry from the available commands dictionary
-        command_entry = self.__available_commands.get(signature)
+        # Create a message indicating that the job has been removed
+        message = f"Task {event.job_id} has been removed."
 
-        # Return the description if the command exists, otherwise return None
-        return command_entry['description'] if command_entry else None
+        # Log the removal of the job
+        self.__logger.info(message)
+
+        # If the application is in debug mode, display the message on the console
+        if self.__app.config('app.debug', False):
+            self.__console.info(message)
+
+        # If a listener is registered for this job ID, invoke the listener with the event details
+        self.__taskCallableListener(event, ListeningEvent.JOB_ON_REMOVED)
 
     def __loadEvents(
         self
@@ -735,7 +915,7 @@ class Scheduler(ISchedule):
                 entity = event.toEntity()
 
                 # Add the job to the internal jobs list
-                self.__jobs.append(entity.toDict())
+                self.__jobs.append(entity)
 
                 # Create a unique key for the job based on its signature
                 self.__scheduler.add_job(
@@ -749,82 +929,32 @@ class Scheduler(ISchedule):
                     replace_existing=True
                 )
 
-    def command(
-        self,
-        signature: str,
-        args: Optional[List[str]] = None
-    ) -> 'Event':
-        """
-        Prepare an Event instance for a given command signature and its arguments.
-
-        This method validates the provided command signature and arguments, ensuring
-        that the command exists among the registered commands and that the arguments
-        are in the correct format. If validation passes, it creates and returns an
-        Event object representing the scheduled command, including its signature,
-        arguments, and description.
-
-        Parameters
-        ----------
-        signature : str
-            The unique signature identifying the command to be scheduled. Must be a non-empty string.
-        args : Optional[List[str]], optional
-            A list of string arguments to be passed to the command. Defaults to None.
-
-        Returns
-        -------
-        Event
-            An Event instance containing the command signature, arguments, and its description.
-
-        Raises
-        ------
-        ValueError
-            If the command signature is not a non-empty string, if the arguments are not a list
-            of strings or None, or if the command does not exist among the registered commands.
-        """
-
-        # Validate that the command signature is a non-empty string
-        if not isinstance(signature, str) or not signature.strip():
-            raise ValueError("Command signature must be a non-empty string.")
-
-        # Ensure that arguments are either a list of strings or None
-        if args is not None and not isinstance(args, list):
-            raise ValueError("Arguments must be a list of strings or None.")
-
-        # Check if the command is available in the registered commands
-        if not self.__isAvailable(signature):
-            raise ValueError(f"The command '{signature}' is not available or does not exist.")
-
-        # Store the command and its arguments for scheduling
-        self.__events[signature] = Event(
-            signature=signature,
-            args=args or [],
-            purpose=self.__getDescription(signature)
-        )
-
-        # Return the Event instance for further scheduling configuration
-        return self.__events[signature]
+                # If a listener is associated with the event, register it
+                if entity.listener:
+                    self._setListener(signature, entity.listener)
 
-    def _setListener(
+    def setListener(
         self,
-        event: str,
-        listener: callable
+        event: Union[str, ListeningEvent],
+        listener: Union[IScheduleEventListener, callable]
     ) -> None:
         """
         Register a listener callback for a specific scheduler event.
 
-        This method allows the registration of a callable listener function that will be
-        invoked when the specified scheduler event occurs. The event can be one of the
-        predefined global events or a specific job ID. The listener must be a callable
-        function that accepts a single argument, which will be the event object.
+        This method registers a listener function or an instance of IScheduleEventListener
+        to be invoked when the specified scheduler event occurs. The event can be a global
+        event name (e.g., 'scheduler_started') or a specific job ID. The listener must be
+        callable and should accept the event object as a parameter.
 
         Parameters
         ----------
         event : str
             The name of the event to listen for. This can be a global event name (e.g., 'scheduler_started')
             or a specific job ID.
-        listener : callable
-            A callable function that will be invoked when the specified event occurs.
-            The function should accept one parameter, which will be the event object.
+        listener : IScheduleEventListener or callable
+            A callable function or an instance of IScheduleEventListener that will be invoked
+            when the specified event occurs. The listener should accept one parameter, which
+            will be the event object.
 
         Returns
         -------
@@ -834,18 +964,23 @@ class Scheduler(ISchedule):
         Raises
         ------
         ValueError
-            If the event name is not a non-empty string or if the listener is not callable.
+            If the event name is not a non-empty string or if the listener is not callable
+            or an instance of IScheduleEventListener.
         """
 
+        # If the event is an instance of ListeningEvent, extract its value
+        if isinstance(event, ListeningEvent):
+            event = event.value
+
         # Validate that the event name is a non-empty string
         if not isinstance(event, str) or not event.strip():
             raise ValueError("Event name must be a non-empty string.")
 
-        # Validate that the listener is a callable function
-        if not callable(listener):
-            raise ValueError("Listener must be a callable function.")
+        # Validate that the listener is either callable or an instance of IScheduleEventListener
+        if not callable(listener) and not isinstance(listener, IScheduleEventListener):
+            raise ValueError("Listener must be a callable function or an instance of IScheduleEventListener.")
 
-        # Register the listener for the specified event
+        # Register the listener for the specified event in the internal listeners dictionary
         self.__listeners[event] = listener
 
     def pauseEverythingAt(
@@ -969,7 +1104,7 @@ class Scheduler(ISchedule):
 
         # Add a job to the scheduler to shut it down at the specified datetime
         self.__scheduler.add_job(
-            func=self.shutdown,                 # Function to shut down the scheduler
+            func=self.__scheduler.shutdown,                 # Function to shut down the scheduler
             trigger='date',                                 # Trigger type is 'date' for one-time execution
             run_date=at,                                    # The datetime at which the job will run
             id=f"shutdown_scheduler_at_{at.isoformat()}",   # Unique job ID based on the datetime
@@ -1011,13 +1146,14 @@ class Scheduler(ISchedule):
             try:
 
                 # Run indefinitely until interrupted
-                while self.__scheduler.running and self.__scheduler.get_jobs():
+                while self.__scheduler.running:
                     await asyncio.sleep(1)
 
             except (KeyboardInterrupt, asyncio.CancelledError):
-
-                # Handle graceful shutdown on keyboard interrupt or cancellation
                 await self.shutdown()
+            except Exception as e:
+                raise CLIOrionisRuntimeError(f"Failed to start the scheduler: {str(e)}") from e
+
 
         except Exception as e:
 
@@ -1028,92 +1164,186 @@ class Scheduler(ISchedule):
         """
         Shut down the AsyncIO scheduler instance asynchronously.
 
-        This method gracefully stops the AsyncIOScheduler that handles asynchronous job execution.
-        Using async ensures proper cleanup in asyncio environments.
+        This method gracefully stops the AsyncIOScheduler that manages asynchronous job execution.
+        It ensures proper cleanup in asyncio environments and allows for an optional wait period
+        to complete currently executing jobs before shutting down.
 
         Parameters
         ----------
         wait : bool, optional
-            If True, the method will wait until all currently executing jobs are completed before shutting down the scheduler.
-            If False, the scheduler will be shut down immediately without waiting for running jobs to finish. Default is True.
+            If True, the method waits until all currently executing jobs are completed before shutting down the scheduler.
+            If False, the scheduler shuts down immediately without waiting for running jobs to finish. Default is True.
 
         Returns
         -------
         None
-            This method does not return any value. It shuts down the AsyncIO scheduler.
+            This method does not return any value. It performs the shutdown operation for the AsyncIO scheduler.
+
+        Raises
+        ------
+        ValueError
+            If the 'wait' parameter is not a boolean value.
+        CLIOrionisRuntimeError
+            If an error occurs during the shutdown process.
         """
 
-        # Validate that the wait parameter is a boolean.
+        # Ensure the 'wait' parameter is a boolean value.
         if not isinstance(wait, bool):
             raise ValueError("The 'wait' parameter must be a boolean value.")
 
+        # If the scheduler is not running, there is nothing to shut down.
+        if not self.__scheduler.running:
+            return
+
+        try:
+            # Shut down the AsyncIOScheduler. If 'wait' is True, it waits for currently executing jobs to finish.
+            self.__scheduler.shutdown(wait=wait)
+
+            # If 'wait' is True, allow a small delay to ensure proper cleanup of resources.
+            if wait:
+                await asyncio.sleep(0)
+
+        except Exception as e:
+
+            # Raise a runtime error if the shutdown process fails.
+            raise CLIOrionisRuntimeError(f"Failed to shut down the scheduler: {str(e)}") from e
+
+    def pause(self, signature: str) -> bool:
+        """
+        Pause a scheduled job in the AsyncIO scheduler.
+
+        This method pauses a job in the AsyncIOScheduler identified by its unique signature.
+        It validates the provided signature to ensure it is a non-empty string and attempts
+        to pause the job. If the operation is successful, it logs the action and returns True.
+        If the job cannot be paused (e.g., it does not exist), the method returns False.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature (ID) of the job to pause. This must be a non-empty string.
+
+        Returns
+        -------
+        bool
+            True if the job was successfully paused.
+            False if the job does not exist or an error occurred.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the `signature` parameter is not a non-empty string.
+        """
+
+        # Validate that the signature is a non-empty string
+        if not isinstance(signature, str) or not signature.strip():
+            raise CLIOrionisValueError("Signature must be a non-empty string.")
+
         try:
 
-            # Shut down the AsyncIOScheduler, waiting for jobs if specified.
-            if self.__scheduler.running:
+            # Attempt to pause the job with the given signature
+            self.__scheduler.pause_job(signature)
+
+            # Log the successful pausing of the job
+            self.__logger.info(f"Job '{signature}' has been paused.")
+            return True
+
+        except Exception:
+
+            # Return False if the job could not be paused (e.g., it does not exist)
+            return False
+
+    def resume(self, signature: str) -> bool:
+        """
+        Resume a paused job in the AsyncIO scheduler.
+
+        This method attempts to resume a job that was previously paused in the AsyncIOScheduler.
+        It validates the provided job signature, ensures it is a non-empty string, and then
+        resumes the job if it exists and is currently paused. If the operation is successful,
+        it logs the action and returns True. If the job cannot be resumed (e.g., it does not exist),
+        the method returns False.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature (ID) of the job to resume. This must be a non-empty string.
+
+        Returns
+        -------
+        bool
+            True if the job was successfully resumed, False if the job does not exist or an error occurred.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the `signature` parameter is not a non-empty string.
+        """
+
+        # Validate that the signature is a non-empty string
+        if not isinstance(signature, str) or not signature.strip():
+            raise CLIOrionisValueError("Signature must be a non-empty string.")
 
-                # For AsyncIOScheduler, shutdown can be called normally
-                # but we await any pending operations
-                self.__scheduler.shutdown(wait=wait)
+        try:
+            # Attempt to resume the job with the given signature
+            self.__scheduler.resume_job(signature)
 
-                # Give a small delay to ensure proper cleanup
-                if wait:
-                    await asyncio.sleep(0.1)
+            # Log the successful resumption of the job
+            self.__logger.info(f"Job '{signature}' has been resumed.")
+            return True
 
         except Exception:
 
-            # AsyncIOScheduler may not be running or may have issues in shutdown
-            pass
+            # Return False if the job could not be resumed (e.g., it does not exist)
+            return False
 
-    async def remove(self, signature: str) -> bool:
+    def remove(self, signature: str) -> bool:
         """
-        Remove a scheduled job from the AsyncIO scheduler asynchronously.
+        Remove a scheduled job from the AsyncIO scheduler.
 
-        This method removes a job with the specified signature from both the internal
-        jobs dictionary and the AsyncIOScheduler instance. Using async ensures proper
-        cleanup in asyncio environments.
+        This method removes a job from the AsyncIOScheduler using its unique signature (ID).
+        It validates the provided signature to ensure it is a non-empty string, attempts to
+        remove the job from the scheduler, and updates the internal jobs list accordingly.
+        If the operation is successful, it logs the action and returns True. If the job
+        cannot be removed (e.g., it does not exist), the method returns False.
 
         Parameters
         ----------
         signature : str
-            The signature of the command/job to remove from the scheduler.
+            The unique signature (ID) of the job to remove. This must be a non-empty string.
 
         Returns
         -------
         bool
-            Returns True if the job was successfully removed, False if the job was not found.
+            True if the job was successfully removed from the scheduler.
+            False if the job does not exist or an error occurred.
 
         Raises
         ------
-        ValueError
-            If the signature is not a non-empty string.
+        CLIOrionisValueError
+            If the `signature` parameter is not a non-empty string.
         """
 
         # Validate that the signature is a non-empty string
         if not isinstance(signature, str) or not signature.strip():
-            raise ValueError("Signature must be a non-empty string.")
+            raise CLIOrionisValueError("Signature must be a non-empty string.")
 
         try:
 
-            # Remove from the scheduler
+            # Attempt to remove the job from the scheduler using its signature
             self.__scheduler.remove_job(signature)
 
-            # Remove from internal jobs dictionary
-            if signature in self.__jobs:
-                del self.__jobs[signature]
+            # Iterate through the internal jobs list to find and remove the job
+            for job in self.__jobs:
+                if job['signature'] == signature:
+                    self.__jobs.remove(job)  # Remove the job from the internal list
+                    break
 
-            # Give a small delay to ensure proper cleanup
-            await asyncio.sleep(0.01)
-
-            # Log the removal of the job
+            # Log the successful removal of the job
             self.__logger.info(f"Job '{signature}' has been removed from the scheduler.")
-
-            # Return True to indicate successful removal
             return True
 
         except Exception:
 
-            # Job not found or other error
+            # Return False if the job could not be removed (e.g., it does not exist)
             return False
 
     def events(self) -> list: