orionis 0.520.0__py3-none-any.whl → 0.522.0__py3-none-any.whl

orionis/console/base/scheduler.py

@@ -18,6 +18,171 @@ class BaseScheduler(IBaseScheduler):
     # Finalize Global Scheduler at a specific time
     FINALIZE_AT: datetime = None
 
+    def pauseAt(self, timezone: str = None) -> datetime:
+        """
+        Retrieves the datetime at which the global scheduler should be paused.
+
+        This method returns the `PAUSE_AT` attribute as a timezone-aware datetime object.
+        If `PAUSE_AT` is not set (i.e., `None`), the method will return `None`.
+        If a timezone is provided, it converts the naive datetime to a timezone-aware
+        datetime using the specified timezone. If no timezone is provided, the naive
+        datetime is returned as is.
+
+        Parameters
+        ----------
+        timezone : str, optional
+            The name of the timezone to use for converting the naive datetime
+            to a timezone-aware datetime. For example, "UTC" or "America/New_York".
+            If not provided, the method returns the naive datetime.
+
+        Returns
+        -------
+        datetime or None
+            - A timezone-aware datetime object representing the pause time of the scheduler
+              if `PAUSE_AT` is set and a valid timezone is provided.
+            - A naive datetime object representing the pause time if `PAUSE_AT` is set
+              but no timezone is provided.
+            - `None` if `PAUSE_AT` is not set.
+
+        Notes
+        -----
+        - The `PAUSE_AT` attribute is expected to be a naive datetime object.
+        - The method uses the `pytz` library to localize the naive datetime to the specified timezone.
+        - If the `PAUSE_AT` attribute is `None`, the method will return `None` without performing any conversion.
+        """
+
+        # Retrieve the naive datetime value for the pause time
+        dt_naive = self.PAUSE_AT
+
+        # If no pause time is set, return None
+        if dt_naive is None:
+            return None
+
+        # If no timezone is provided, return the naive datetime as is
+        if timezone is None:
+            return dt_naive
+
+        # Import the pytz library for timezone handling
+        import pytz
+
+        # Get the specified timezone using pytz
+        # This will raise an exception if the timezone string is invalid
+        tz = pytz.timezone(timezone)
+
+        # Convert the naive datetime to a timezone-aware datetime
+        # This ensures the datetime is localized to the specified timezone
+        return tz.localize(dt_naive)
+
+    def resumeAt(self, timezone: str = None) -> datetime:
+        """
+        Retrieves the datetime at which the global scheduler should be resumed.
+
+        This method returns the `RESUME_AT` attribute as a timezone-aware datetime object.
+        If `RESUME_AT` is not set (i.e., `None`), the method will return `None`.
+        If a timezone is provided, it converts the naive datetime to a timezone-aware
+        datetime using the specified timezone. If no timezone is provided, the naive
+        datetime is returned as is.
+
+        Parameters
+        ----------
+        timezone : str, optional
+            The name of the timezone to use for converting the naive datetime
+            to a timezone-aware datetime. For example, "UTC" or "America/New_York".
+            If not provided, the method returns the naive datetime.
+
+        Returns
+        -------
+        datetime or None
+            - A timezone-aware datetime object representing the resume time of the scheduler
+              if `RESUME_AT` is set and a valid timezone is provided.
+            - A naive datetime object representing the resume time if `RESUME_AT` is set
+              but no timezone is provided.
+            - `None` if `RESUME_AT` is not set.
+
+        Notes
+        -----
+        - The `RESUME_AT` attribute is expected to be a naive datetime object.
+        - The method uses the `pytz` library to localize the naive datetime to the specified timezone.
+        - If the `RESUME_AT` attribute is `None`, the method will return `None` without performing any conversion.
+        """
+
+        # Retrieve the naive datetime value for the resume time
+        dt_naive = self.RESUME_AT
+
+        # If no resume time is set, return None
+        if dt_naive is None:
+            return None
+
+        # If no timezone is provided, return the naive datetime as is
+        if timezone is None:
+            return dt_naive
+
+        # Import the pytz library for timezone handling
+        import pytz
+
+        # Get the specified timezone using pytz
+        # This will raise an exception if the timezone string is invalid
+        tz = pytz.timezone(timezone)
+
+        # Convert the naive datetime to a timezone-aware datetime
+        # This ensures the datetime is localized to the specified timezone
+        return tz.localize(dt_naive)
+
+    def finalizeAt(self, timezone: str = None) -> datetime:
+        """
+        Retrieves the datetime at which the global scheduler should be finalized.
+
+        This method returns the `FINALIZE_AT` attribute as a timezone-aware datetime object.
+        If `FINALIZE_AT` is not set (i.e., `None`), the method will return `None`.
+        If a timezone is provided, it converts the naive datetime to a timezone-aware
+        datetime using the specified timezone. If no timezone is provided, the naive
+        datetime is returned as is.
+
+        Parameters
+        ----------
+        timezone : str, optional
+            The name of the timezone to use for converting the naive datetime
+            to a timezone-aware datetime. For example, "UTC" or "America/New_York".
+            If not provided, the method returns the naive datetime.
+
+        Returns
+        -------
+        datetime or None
+            - A timezone-aware datetime object representing the finalize time of the scheduler
+              if `FINALIZE_AT` is set and a valid timezone is provided.
+            - A naive datetime object representing the finalize time if `FINALIZE_AT` is set
+              but no timezone is provided.
+            - `None` if `FINALIZE_AT` is not set.
+
+        Notes
+        -----
+        - The `FINALIZE_AT` attribute is expected to be a naive datetime object.
+        - The method uses the `pytz` library to localize the naive datetime to the specified timezone.
+        - If the `FINALIZE_AT` attribute is `None`, the method will return `None` without performing any conversion.
+        """
+
+        # Retrieve the naive datetime value for the finalize time
+        dt_naive = self.FINALIZE_AT
+
+        # If no finalize time is set, return None
+        if dt_naive is None:
+            return None
+
+        # If no timezone is provided, return the naive datetime as is
+        if timezone is None:
+            return dt_naive
+
+        # Import the pytz library for timezone handling
+        import pytz
+
+        # Get the specified timezone using pytz
+        # This will raise an exception if the timezone string is invalid
+        tz = pytz.timezone(timezone)
+
+        # Convert the naive datetime to a timezone-aware datetime
+        # This ensures the datetime is localized to the specified timezone
+        return tz.localize(dt_naive)
+
     async def tasks(self, schedule: ISchedule):
         """
         Defines and registers scheduled tasks for the application.

orionis/console/commands/scheduler_work.py

@@ -110,21 +110,21 @@ class ScheduleWorkCommand(BaseCommand):
             if hasattr(scheduler, "onError") and callable(scheduler.onError):
                 schedule_service.setListener(ListeningEvent.SCHEDULER_ERROR, scheduler.onError)
 
-            # Check if the scheduler has specific pause, resume, and finalize times
-            if hasattr(scheduler, "PAUSE_AT") and scheduler.PAUSE_AT is not None:
-                if not isinstance(scheduler.PAUSE_AT, datetime):
-                    raise CLIOrionisRuntimeError("PAUSE_AT must be a datetime instance.")
-                schedule_service.pauseEverythingAt(scheduler.PAUSE_AT)
+            if hasattr(scheduler, "FINALIZE_AT") and scheduler.FINALIZE_AT is not None:
+                if not isinstance(scheduler.FINALIZE_AT, datetime):
+                    raise CLIOrionisRuntimeError("FINALIZE_AT must be a datetime instance.")
+                schedule_service.shutdownEverythingAt(scheduler.finalizeAt())
 
             if hasattr(scheduler, "RESUME_AT") and scheduler.RESUME_AT is not None:
                 if not isinstance(scheduler.RESUME_AT, datetime):
                     raise CLIOrionisRuntimeError("RESUME_AT must be a datetime instance.")
-                schedule_service.resumeEverythingAt(scheduler.RESUME_AT)
+                schedule_service.resumeEverythingAt(scheduler.resumeAt())
 
-            if hasattr(scheduler, "FINALIZE_AT") and scheduler.FINALIZE_AT is not None:
-                if not isinstance(scheduler.FINALIZE_AT, datetime):
-                    raise CLIOrionisRuntimeError("FINALIZE_AT must be a datetime instance.")
-                schedule_service.shutdownEverythingAt(scheduler.FINALIZE_AT)
+            # Check if the scheduler has specific pause, resume, and finalize times
+            if hasattr(scheduler, "PAUSE_AT") and scheduler.PAUSE_AT is not None:
+                if not isinstance(scheduler.PAUSE_AT, datetime):
+                    raise CLIOrionisRuntimeError("PAUSE_AT must be a datetime instance.")
+                schedule_service.pauseEverythingAt(scheduler.pauseAt())
 
             # Start the scheduler worker asynchronously
             await schedule_service.start()
@@ -137,4 +137,4 @@ class ScheduleWorkCommand(BaseCommand):
             # Raise any unexpected exceptions as CLIOrionisRuntimeError
             raise CLIOrionisRuntimeError(
                 f"An unexpected error occurred while starting the scheduler worker: {e}"
-            )
+            )

orionis/console/tasks/schedule.py

@@ -50,7 +50,6 @@ class Scheduler(ISchedule):
         self,
         reactor: IReactor,
         app: IApplication,
-        console: IConsole,
         rich_console: Console
     ) -> None:
         """
@@ -74,10 +73,7 @@ class Scheduler(ISchedule):
         """
 
         # Store the application instance for configuration access.
-        self.__app = app
-
-        # Store the console instance for output operations.
-        self.__console = console
+        self.__app: IApplication = app
 
         # Store the rich console instance for advanced output formatting.
         self.__rich_console = rich_console
@@ -99,7 +95,7 @@ class Scheduler(ISchedule):
         self.__logger: ILogger = self.__app.make('x-orionis.services.log.log_service')
 
         # Store the reactor instance for command management.
-        self.__reactor = reactor
+        self.__reactor: IReactor = reactor
 
         # Retrieve and store all available commands from the reactor.
         self.__available_commands = self.__getCommands()
@@ -113,6 +109,9 @@ class Scheduler(ISchedule):
         # Initialize the listeners dictionary to manage event listeners.
         self.__listeners: Dict[str, callable] = {}
 
+        # Add this line to the existing __init__ method
+        self._stop_event: Optional[asyncio.Event] = None
+
     def __getCurrentTime(
         self
     ) -> str:
@@ -263,7 +262,7 @@ class Scheduler(ISchedule):
         """
 
         # Prevent adding new commands while the scheduler is running
-        if self.__scheduler.running:
+        if self.isRunning():
             raise CLIOrionisRuntimeError("Cannot add new commands while the scheduler is running.")
 
         # Validate that the command signature is a non-empty string
@@ -278,8 +277,10 @@ class Scheduler(ISchedule):
         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
+        # Import Event here to avoid circular dependency issues
         from orionis.console.tasks.event import Event
+
+        # Store the command and its arguments for scheduling
         self.__events[signature] = Event(
             signature=signature,
             args=args or [],
@@ -363,6 +364,8 @@ class Scheduler(ISchedule):
 
         # Check if a listener is registered for the specified event
         if scheduler_event in self.__listeners:
+
+            # Retrieve the listener for the specified event
             listener = self.__listeners[scheduler_event]
 
             # Ensure the listener is callable before invoking it
@@ -372,21 +375,29 @@ class Scheduler(ISchedule):
 
                     # If the listener is a coroutine, schedule it as an asyncio task
                     if asyncio.iscoroutinefunction(listener):
+
+                        # Try to get the running event loop
                         try:
-                            # Try to get the running event loop
                             loop = asyncio.get_running_loop()
                             loop.create_task(listener(event_data, self))
+
+                        # If no event loop is running, log a warning instead of creating one
                         except RuntimeError:
-                            # If no event loop is running, create a new one
-                            asyncio.run(listener(event_data, self))
+
+                            # Raise an error to inform the caller that the listener could not be invoked
+                            raise CLIOrionisRuntimeError(
+                                f"Cannot run async listener for '{scheduler_event}': no event loop running"
+                            )
+
                     # Otherwise, invoke the listener directly as a regular function
                     else:
                         listener(event_data, self)
 
                 except Exception as e:
 
-                    # Log any exceptions that occur during listener invocation
-                    self.__logger.error(f"Error invoking global listener for event '{scheduler_event}': {str(e)}")
+                    # Re-raise CLIOrionisRuntimeError exceptions
+                    if isinstance(e, CLIOrionisRuntimeError):
+                        raise e
 
                     # Raise a runtime error if listener invocation fails
                     raise CLIOrionisRuntimeError(
@@ -449,19 +460,43 @@ class Scheduler(ISchedule):
 
                 # Check if the listener has a method corresponding to the event type
                 if hasattr(listener, scheduler_event) and callable(getattr(listener, scheduler_event)):
+
+                    # Retrieve the method from the listener
                     listener_method = getattr(listener, scheduler_event)
 
+                    # Try to invoke the listener method
                     try:
+
                         # 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))
+
+                            # Try to get the running event loop
+                            try:
+                                loop = asyncio.get_running_loop()
+                                loop.create_task(listener_method(event_data, self))
+
+                            # If no event loop is running, log a warning
+                            except RuntimeError:
+
+                                # Raise an error to inform the caller that the listener could not be invoked
+                                raise CLIOrionisRuntimeError(
+                                    f"Cannot run async listener for '{scheduler_event}' on job '{event_data.job_id}': no event loop running"
+                                )
+
+                        # Call the regular listener method directly
                         else:
-                            # Call the regular listener method directly
                             listener_method(event_data, self)
+
                     except Exception as e:
-                        # Log any exceptions that occur during listener invocation
-                        self.__logger.error(f"Error invoking listener method '{scheduler_event}' for job '{event_data.job_id}': {str(e)}")
+
+                        # Re-raise CLIOrionisRuntimeError exceptions
+                        if isinstance(e, CLIOrionisRuntimeError):
+                            raise e
+
+                        # Raise a runtime error if listener invocation fails
+                        raise CLIOrionisRuntimeError(
+                            f"An error occurred while invoking the listener for event '{scheduler_event}' on job '{event_data.job_id}': {str(e)}"
+                        )
 
     def __startedListener(
         self,
@@ -899,27 +934,36 @@ class Scheduler(ISchedule):
             # Iterate through all scheduled jobs in the AsyncIOScheduler
             for signature, event in self.__events.items():
 
-                # Convert the event to its entity representation
-                entity = event.toEntity()
-
-                # Add the job to the internal jobs list
-                self.__jobs.append(entity)
+                try:
+                    # Convert the event to its entity representation
+                    entity = event.toEntity()
+
+                    # Add the job to the internal jobs list
+                    self.__jobs.append(entity)
+
+                    # Create a unique key for the job based on its signature
+                    def create_job_func(cmd, args_list):
+                        return lambda: self.__reactor.call(cmd, args_list)
+
+                    # Add the job to the scheduler with the specified trigger and parameters
+                    self.__scheduler.add_job(
+                        func=create_job_func(signature, list(entity.args)),
+                        trigger=entity.trigger,
+                        id=signature,
+                        name=signature,
+                        replace_existing=True
+                    )
 
-                # Create a unique key for the job based on its signature
-                def create_job_func(cmd, args_list):
-                    return lambda: self.__reactor.call(cmd, args_list)
+                    # If a listener is associated with the event, register it
+                    if entity.listener:
+                        self.setListener(signature, entity.listener)
 
-                self.__scheduler.add_job(
-                    func=create_job_func(signature, list(entity.args)),
-                    trigger=entity.trigger,
-                    id=signature,
-                    name=signature,
-                    replace_existing=True
-                )
+                except Exception as e:
 
-                # If a listener is associated with the event, register it
-                if entity.listener:
-                    self.setListener(signature, entity.listener)
+                    # Raise a runtime error if loading the scheduled event fails
+                    raise CLIOrionisRuntimeError(
+                        f"Failed to load scheduled event '{signature}': {str(e)}"
+                    ) from e
 
     def setListener(
         self,
@@ -978,9 +1022,9 @@ class Scheduler(ISchedule):
         """
         Schedule the scheduler to pause all operations at a specific datetime.
 
-        This method allows you to schedule a job that will pause the AsyncIOScheduler
-        at the specified datetime. The job is added to the scheduler with a 'date'
-        trigger, ensuring it executes exactly at the given time.
+        This method schedules a job that pauses the AsyncIOScheduler at the specified datetime.
+        The job is added to the scheduler with a 'date' trigger, ensuring it executes exactly
+        at the given time. If a pause job already exists, it is replaced to avoid conflicts.
 
         Parameters
         ----------
@@ -997,21 +1041,43 @@ class Scheduler(ISchedule):
         Raises
         ------
         ValueError
-            If the 'at' parameter is not a valid datetime object.
+            If the 'at' parameter is not a valid datetime object or is not in the future.
+        CLIOrionisRuntimeError
+            If the scheduler is not running or if an error occurs during job scheduling.
         """
 
         # Validate that the 'at' parameter is a datetime object
         if not isinstance(at, datetime):
             raise ValueError("The 'at' parameter must be a datetime object.")
 
-        # Add a job to the scheduler to pause it at the specified datetime
-        self.__scheduler.add_job(
-            func=self.__scheduler.pause,                    # Function to pause the scheduler
-            trigger=DateTrigger(run_date=at),               # Trigger type is 'date' for one-time execution
-            id=ListeningEvent.SCHEDULER_PAUSED.value,       # Unique job ID for pausing the scheduler
-            name=ListeningEvent.SCHEDULER_PAUSED.value,     # Descriptive name for the job
-            replace_existing=True                           # Replace any existing job with the same ID
-        )
+        # Define a function to pause the scheduler
+        def schedule_pause():
+            if self.isRunning():
+                self.__scheduler.pause()
+
+        try:
+            # Remove any existing pause job to avoid conflicts
+            try:
+                self.__scheduler.remove_job("scheduler_pause_at")
+            except:
+                pass  # If the job doesn't exist, it's fine to proceed
+
+            # Add a job to the scheduler to pause it at the specified datetime
+            self.__scheduler.add_job(
+                func=schedule_pause,                            # Function to pause the scheduler
+                trigger=DateTrigger(run_date=at),               # Trigger type is 'date' for one-time execution
+                id="scheduler_pause_at",                        # Unique job ID for pausing the scheduler
+                name="Pause Scheduler",                         # Descriptive name for the job
+                replace_existing=True                           # Replace any existing job with the same ID
+            )
+
+            # Log the scheduled pause
+            self.__logger.info(f"Scheduler pause scheduled for {at.strftime('%Y-%m-%d %H:%M:%S')}")
+
+        except Exception as e:
+
+            # Handle exceptions that may occur during job scheduling
+            raise CLIOrionisRuntimeError(f"Failed to schedule scheduler pause: {str(e)}") from e
 
     def resumeEverythingAt(
         self,
@@ -1020,9 +1086,9 @@ class Scheduler(ISchedule):
         """
         Schedule the scheduler to resume all operations at a specific datetime.
 
-        This method allows you to schedule a job that will resume the AsyncIOScheduler
-        at the specified datetime. The job is added to the scheduler with a 'date'
-        trigger, ensuring it executes exactly at the given time.
+        This method schedules a job that resumes the AsyncIOScheduler at the specified datetime.
+        The job is added to the scheduler with a 'date' trigger, ensuring it executes exactly
+        at the given time. If a resume job already exists, it is replaced to avoid conflicts.
 
         Parameters
         ----------
@@ -1039,38 +1105,65 @@ class Scheduler(ISchedule):
         Raises
         ------
         ValueError
-            If the 'at' parameter is not a valid datetime object.
+            If the 'at' parameter is not a valid datetime object or is not in the future.
+        CLIOrionisRuntimeError
+            If the scheduler is not running or if an error occurs during job scheduling.
         """
 
         # Validate that the 'at' parameter is a datetime object
         if not isinstance(at, datetime):
             raise ValueError("The 'at' parameter must be a datetime object.")
 
-        # Add a job to the scheduler to resume it at the specified datetime
-        self.__scheduler.add_job(
-            func=self.__scheduler.resume,                   # Function to resume the scheduler
-            trigger=DateTrigger(run_date=at),               # Trigger type is 'date' for one-time execution
-            id=ListeningEvent.SCHEDULER_RESUMED.value,      # Unique job ID for resuming the scheduler
-            name=ListeningEvent.SCHEDULER_RESUMED.value,    # Descriptive name for the job
-            replace_existing=True                           # Replace any existing job with the same ID
-        )
+        # Define a function to resume the scheduler
+        def schedule_resume():
+            if self.isRunning():
+                self.__scheduler.resume()
+
+        try:
+
+            # Remove any existing resume job to avoid conflicts
+            try:
+                self.__scheduler.remove_job("scheduler_resume_at")
+            except:
+                pass  # If the job doesn't exist, it's fine to proceed
+
+            # Add a job to the scheduler to resume it at the specified datetime
+            self.__scheduler.add_job(
+                func=schedule_resume,                           # Function to resume the scheduler
+                trigger=DateTrigger(run_date=at),               # Trigger type is 'date' for one-time execution
+                id="scheduler_resume_at",                       # Unique job ID for resuming the scheduler
+                name="Resume Scheduler",                        # Descriptive name for the job
+                replace_existing=True                           # Replace any existing job with the same ID
+            )
+
+            # Log the scheduled resume
+            self.__logger.info(f"Scheduler resume scheduled for {at.strftime('%Y-%m-%d %H:%M:%S')}")
+
+        except Exception as e:
+
+            # Handle exceptions that may occur during job scheduling
+            raise CLIOrionisRuntimeError(f"Failed to schedule scheduler resume: {str(e)}") from e
 
     def shutdownEverythingAt(
         self,
-        at: datetime
+        at: datetime,
+        wait: bool = True
     ) -> None:
         """
         Schedule the scheduler to shut down all operations at a specific datetime.
 
-        This method allows you to schedule a job that will shut down the AsyncIOScheduler
-        at the specified datetime. The job is added to the scheduler with a 'date'
-        trigger, ensuring it executes exactly at the given time.
+        This method schedules a job that shuts down the AsyncIOScheduler at the specified datetime.
+        The job is added to the scheduler with a 'date' trigger, ensuring it executes exactly
+        at the given time. If a shutdown job already exists, it is replaced to avoid conflicts.
 
         Parameters
         ----------
         at : datetime
             The datetime at which the scheduler should be shut down. Must be a valid
             datetime object.
+        wait : bool, optional
+            Whether to wait for currently running jobs to complete before shutdown.
+            Default is True.
 
         Returns
         -------
@@ -1081,88 +1174,144 @@ class Scheduler(ISchedule):
         Raises
         ------
         ValueError
-            If the 'at' parameter is not a valid datetime object.
+            If the 'at' parameter is not a valid datetime object or 'wait' is not boolean,
+            or if the scheduled time is not in the future.
+        CLIOrionisRuntimeError
+            If the scheduler is not running or if an error occurs during job scheduling.
         """
 
         # Validate that the 'at' parameter is a datetime object
         if not isinstance(at, datetime):
             raise ValueError("The 'at' parameter must be a datetime object.")
 
-        # Add a job to the scheduler to shut it down at the specified datetime
-        self.__scheduler.add_job(
-            func=self.__scheduler.shutdown,                 # Function to shut down the scheduler
-            trigger=DateTrigger(run_date=at),               # Trigger type is 'date' for one-time execution
-            id=ListeningEvent.SCHEDULER_SHUTDOWN.value,     # Unique job ID for shutting down the scheduler
-            name=ListeningEvent.SCHEDULER_SHUTDOWN.value,   # Descriptive name for the job
-            replace_existing=True                           # Replace any existing job with the same ID
-        )
+        # Validate that the 'wait' parameter is a boolean
+        if not isinstance(wait, bool):
+            raise ValueError("The 'wait' parameter must be a boolean value.")
+
+        # Define a function to shut down the scheduler
+        def schedule_shutdown():
+            if self.isRunning():
+                self.__scheduler.shutdown(wait=wait)
+                # Signal the stop event to break the wait in start()
+                if self._stop_event and not self._stop_event.is_set():
+                    self._stop_event.set()
+
+        try:
+
+            # Remove any existing shutdown job to avoid conflicts
+            try:
+                self.__scheduler.remove_job("scheduler_shutdown_at")
+            except:
+                pass  # If the job doesn't exist, it's fine to proceed
+
+            # Add a job to the scheduler to shut it down at the specified datetime
+            self.__scheduler.add_job(
+                func=schedule_shutdown,                        # Function to shut down the scheduler
+                trigger=DateTrigger(run_date=at),               # Trigger type is 'date' for one-time execution
+                id="scheduler_shutdown_at",                     # Unique job ID for shutting down the scheduler
+                name="Shutdown Scheduler",                      # Descriptive name for the job
+                replace_existing=True                           # Replace any existing job with the same ID
+            )
+
+            # Log the scheduled shutdown
+            self.__logger.info(f"Scheduler shutdown scheduled for {at.strftime('%Y-%m-%d %H:%M:%S')} (wait={wait})")
+
+        except Exception as e:
+
+            # Handle exceptions that may occur during job scheduling
+            raise CLIOrionisRuntimeError(f"Failed to schedule scheduler shutdown: {str(e)}") from e
 
     async def start(self) -> None:
         """
         Start the AsyncIO scheduler instance and keep it running.
 
-        This method initiates the AsyncIOScheduler which integrates with asyncio event loops
-        for asynchronous job execution. It ensures the scheduler starts properly within
-        an asyncio context and maintains the event loop active to process scheduled jobs.
+        This method initializes and starts the AsyncIOScheduler, which integrates with the asyncio event loop
+        to manage asynchronous job execution. It ensures that all scheduled events are loaded, listeners are
+        subscribed, and the scheduler is started within an asyncio context. The method keeps the scheduler
+        running until a stop signal is received, handling graceful shutdowns and interruptions.
 
         Returns
         -------
         None
-            This method does not return any value. It starts the AsyncIO scheduler and keeps it running.
-        """
+            This method does not return any value. It starts the AsyncIO scheduler, keeps it running, and
+            ensures proper cleanup during shutdown.
 
-        # Start the AsyncIOScheduler to handle asynchronous jobs.
+        Raises
+        ------
+        CLIOrionisRuntimeError
+            If the scheduler fails to start due to missing an asyncio event loop or other runtime issues.
+        """
         try:
 
-            # Ensure we're in an asyncio context
-            asyncio.get_running_loop()
+            # Ensure the method is called within an asyncio event loop
+            loop = asyncio.get_running_loop()
 
-            # Ensure all events are loaded into the internal jobs list
+            # Create an asyncio event to manage clean shutdowns
+            self._stop_event = asyncio.Event()
+
+            # Load all scheduled events into the internal jobs list
             self.__loadEvents()
 
-            # Subscribe to scheduler events
+            # Subscribe to scheduler events for monitoring and handling
             self.__subscribeListeners()
 
-            # Start the scheduler
-            if not self.__scheduler.running:
+            # Start the scheduler if it is not already running
+            if not self.isRunning():
                 self.__scheduler.start()
 
-            # Keep the event loop alive to process scheduled jobs
-            try:
+            # Log that the scheduler is now active and waiting for events
+            self.__logger.info("Scheduler is now active and waiting for events...")
 
-                # Run indefinitely until interrupted
-                while self.__scheduler.running:
-                    await asyncio.sleep(1)
+            try:
+                # Wait for the stop event to be set, which signals a shutdown
+                # This avoids using a busy loop and is more efficient
+                await self._stop_event.wait()
 
             except (KeyboardInterrupt, asyncio.CancelledError):
-                await self.shutdown()
+
+                # Handle graceful shutdown when an interruption signal is received
+                self.__logger.info("Received shutdown signal, stopping scheduler...")
+                await self.shutdown(wait=True)
+
             except Exception as e:
-                raise CLIOrionisRuntimeError(f"Failed to start the scheduler: {str(e)}") from e
 
+                # Log and raise any unexpected exceptions during scheduler operation
+                self.__logger.error(f"Error during scheduler operation: {str(e)}")
+                raise CLIOrionisRuntimeError(f"Scheduler operation failed: {str(e)}") from e
+
+            finally:
+
+                # Ensure the scheduler is shut down properly, even if an error occurs
+                if self.__scheduler.running:
+                    await self.shutdown(wait=False)
+
+        except RuntimeError as e:
+
+            # Handle the case where no asyncio event loop is running
+            if "no running event loop" in str(e):
+                raise CLIOrionisRuntimeError("Scheduler must be started within an asyncio event loop") from e
+            raise CLIOrionisRuntimeError(f"Failed to start the scheduler: {str(e)}") from e
 
         except Exception as e:
 
-            # Handle exceptions that may occur during scheduler startup
-            raise CLIOrionisRuntimeError(f"Failed to start the scheduler: {str(e)}")
+            # Raise a runtime error for any other issues during startup
+            raise CLIOrionisRuntimeError(f"Failed to start the scheduler: {str(e)}") from e
 
-    async def shutdown(self, wait=True) -> None:
+    async def shutdown(self, wait: bool = True) -> None:
         """
         Shut down the AsyncIO scheduler instance asynchronously.
 
-        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.
+        This method gracefully stops the AsyncIOScheduler and signals the main event loop
+        to stop waiting, allowing for clean application shutdown.
 
         Parameters
         ----------
         wait : bool, optional
-            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.
+            If True, waits for currently executing jobs to complete. Default is True.
 
         Returns
         -------
         None
-            This method does not return any value. It performs the shutdown operation for the AsyncIO scheduler.
 
         Raises
         ------
@@ -1172,25 +1321,36 @@ class Scheduler(ISchedule):
             If an error occurs during the shutdown process.
         """
 
-        # Ensure the 'wait' parameter is a boolean value.
+        # Validate the wait parameter
         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:
+        # If the scheduler is not running, there's nothing to shut down
+        if not self.isRunning():
             return
 
         try:
-            # Shut down the AsyncIOScheduler. If 'wait' is True, it waits for currently executing jobs to finish.
+
+            # Log the shutdown process
+            self.__logger.info(f"Shutting down scheduler (wait={wait})...")
+
+            # Shut down the AsyncIOScheduler
             self.__scheduler.shutdown(wait=wait)
 
-            # If 'wait' is True, allow a small delay to ensure proper cleanup of resources.
+            # Signal the stop event to break the wait in start()
+            if self._stop_event and not self._stop_event.is_set():
+                self._stop_event.set()
+
+            # Allow time for cleanup if waiting
             if wait:
-                await asyncio.sleep(0)
+                await asyncio.sleep(0.1)
+
+            # Log the successful shutdown
+            self.__logger.info("Scheduler shutdown completed successfully.")
 
         except Exception as e:
 
-            # Raise a runtime error if the shutdown process fails.
+            # Handle exceptions that may occur during shutdown
             raise CLIOrionisRuntimeError(f"Failed to shut down the scheduler: {str(e)}") from e
 
     def pause(self, signature: str) -> bool:
@@ -1322,7 +1482,7 @@ class Scheduler(ISchedule):
 
             # Iterate through the internal jobs list to find and remove the job
             for job in self.__jobs:
-                if job['signature'] == signature:
+                if job.signature == signature:
                     self.__jobs.remove(job)  # Remove the job from the internal list
                     break
 
@@ -1388,4 +1548,182 @@ class Scheduler(ISchedule):
             })
 
         # Return the list of scheduled job details
-        return events
+        return events
+
+    def cancelScheduledPause(self) -> bool:
+        """
+        Cancel a previously scheduled pause operation.
+
+        This method attempts to remove a job from the scheduler that was set to pause
+        the scheduler at a specific time. If the job exists, it is removed, and a log entry
+        is created to indicate the cancellation. If no such job exists, the method returns False.
+
+        Returns
+        -------
+        bool
+            True if the scheduled pause job was successfully cancelled.
+            False if no pause job was found or an error occurred during the cancellation process.
+        """
+        try:
+            # Attempt to remove the pause job with the specific ID
+            self.__scheduler.remove_job("scheduler_pause_at")
+
+            # Log the successful cancellation of the pause operation
+            self.__logger.info("Scheduled pause operation cancelled.")
+
+            # Return True to indicate the pause job was successfully cancelled
+            return True
+
+        except:
+            # Return False if the pause job does not exist or an error occurred
+            return False
+
+    def cancelScheduledResume(self) -> bool:
+        """
+        Cancel a previously scheduled resume operation.
+
+        This method attempts to remove a job from the scheduler that was set to resume
+        the scheduler at a specific time. If the job exists, it is removed, and a log entry
+        is created to indicate the cancellation. If no such job exists, the method returns False.
+
+        Returns
+        -------
+        bool
+            True if the scheduled resume job was successfully cancelled.
+            False if no resume job was found or an error occurred during the cancellation process.
+        """
+        try:
+            # Attempt to remove the resume job with the specific ID
+            self.__scheduler.remove_job("scheduler_resume_at")
+
+            # Log the successful cancellation of the resume operation
+            self.__logger.info("Scheduled resume operation cancelled.")
+
+            # Return True to indicate the resume job was successfully cancelled
+            return True
+
+        except:
+
+            # Return False if the resume job does not exist or an error occurred
+            return False
+
+    def cancelScheduledShutdown(self) -> bool:
+        """
+        Cancel a previously scheduled shutdown operation.
+
+        This method attempts to remove a job from the scheduler that was set to shut down
+        the scheduler at a specific time. If the job exists, it is removed, and a log entry
+        is created to indicate the cancellation. If no such job exists, the method returns False.
+
+        Returns
+        -------
+        bool
+            True if the scheduled shutdown job was successfully cancelled.
+            False if no shutdown job was found or an error occurred during the cancellation process.
+        """
+        try:
+            # Attempt to remove the shutdown job with the specific ID
+            self.__scheduler.remove_job("scheduler_shutdown_at")
+
+            # Log the successful cancellation of the shutdown operation
+            self.__logger.info("Scheduled shutdown operation cancelled.")
+
+            # Return True to indicate the shutdown job was successfully cancelled
+            return True
+
+        except:
+
+            # Return False if the shutdown job does not exist or an error occurred
+            return False
+
+    def isRunning(self) -> bool:
+        """
+        Determine if the scheduler is currently active and running.
+
+        This method checks the internal state of the AsyncIOScheduler instance to determine
+        whether it is currently running. The scheduler is considered running if it has been
+        started and has not been paused or shut down.
+
+        Returns
+        -------
+        bool
+            True if the scheduler is running, False otherwise.
+        """
+
+        # Return the running state of the scheduler
+        return self.__scheduler.running
+
+    async def waitUntilStopped(self) -> None:
+        """
+        Wait for the scheduler to stop gracefully.
+
+        This method blocks the execution until the scheduler is stopped. It waits for the
+        internal stop event to be set, which signals that the scheduler has been shut down.
+        This is useful for ensuring that the scheduler completes its operations before
+        proceeding with other tasks.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It waits until the scheduler is stopped.
+        """
+
+        # Check if the stop event is initialized
+        if self._stop_event:
+
+            # Wait for the stop event to be set, signaling the scheduler has stopped
+            await self._stop_event.wait()
+
+    def forceStop(self) -> None:
+        """
+        Forcefully stop the scheduler immediately without waiting for jobs to complete.
+
+        This method shuts down the AsyncIOScheduler instance without waiting for currently
+        running jobs to finish. It is intended for emergency situations where an immediate
+        stop is required. The method also signals the internal stop event to ensure that
+        the scheduler's main loop is interrupted and the application can proceed with
+        shutdown procedures.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It forcefully stops the scheduler and
+            signals the stop event.
+        """
+
+        # Check if the scheduler is currently running
+        if self.__scheduler.running:
+            # Shut down the scheduler immediately without waiting for jobs to complete
+            self.__scheduler.shutdown(wait=False)
+
+        # Check if the stop event exists and has not already been set
+        if self._stop_event and not self._stop_event.is_set():
+            # Signal the stop event to interrupt the scheduler's main loop
+            self._stop_event.set()
+
+    def stop(self) -> None:
+        """
+        Stop the scheduler synchronously by setting the stop event.
+
+        This method signals the scheduler to stop by setting the internal stop event.
+        It can be called from non-async contexts to initiate a shutdown. If the asyncio
+        event loop is running, the stop event is set in a thread-safe manner. Otherwise,
+        the stop event is set directly.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It signals the scheduler to stop.
+        """
+
+        # Check if the stop event exists and has not already been set
+        if self._stop_event and not self._stop_event.is_set():
+            # Get the current asyncio event loop
+            loop = asyncio.get_event_loop()
+
+            # If the event loop is running, set the stop event in a thread-safe manner
+            if loop.is_running():
+                loop.call_soon_threadsafe(self._stop_event.set)
+            else:
+                # Otherwise, set the stop event directly
+                self._stop_event.set()

orionis/metadata/framework.py

@@ -5,7 +5,7 @@
 NAME = "orionis"
 
 # Current version of the framework
-VERSION = "0.520.0"
+VERSION = "0.522.0"
 
 # Full name of the author or maintainer of the project
 AUTHOR = "Raul Mauricio Uñate Castro"

{orionis-0.520.0.dist-info → orionis-0.522.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.520.0
+Version: 0.522.0
 Summary: Orionis Framework – Elegant, Fast, and Powerful.
 Home-page: https://github.com/orionis-framework/framework
 Author: Raul Mauricio Uñate Castro

{orionis-0.520.0.dist-info → orionis-0.522.0.dist-info}/RECORD

@@ -8,14 +8,14 @@ orionis/console/args/enums/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJ
 orionis/console/args/enums/actions.py,sha256=S3T-vWS6DJSGtANrq3od3-90iYAjPvJwaOZ2V02y34c,1222
 orionis/console/base/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/console/base/command.py,sha256=OM4xqVgpv_1RZVyVG8BzOHl1sP9FT5mPUwZjMil8IRg,6637
-orionis/console/base/scheduler.py,sha256=w86p-4KjfMqMcGlQBsmiBASpzv33M-PWLbgYza7Um9g,8030
+orionis/console/base/scheduler.py,sha256=LFzWUFk07LrcpKFL7sS7exHzTkxFRd1DPDSqDSpRcOk,15157
 orionis/console/base/scheduler_event_listener.py,sha256=5qWPmf6jmiRwUz6U1ZvpQCG5eovOpeCl0KAb8kKDkfU,3905
 orionis/console/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/console/commands/cache.py,sha256=8DsYoRzSBLn0P9qkGVItRbo0R6snWBDBg0_Xa7tmVhs,2322
 orionis/console/commands/help.py,sha256=zfSw0pYaOnFN-_Ozdn4veBQDYMgSSDY10nPDCi-7tTY,3199
 orionis/console/commands/publisher.py,sha256=FUg-EUzK7LLXsla10ZUZro8V0Z5S-KjmsaSdRHSSGbA,21381
 orionis/console/commands/scheduler_list.py,sha256=A2N_mEXEJDHO8DX2TDrL1ROeeRhFSkWD3rCw64Hrf0o,4763
-orionis/console/commands/scheduler_work.py,sha256=yHTbnDH1frAmyvPaUgn0a5q34Eym9QYMXdqYZWwodFs,6336
+orionis/console/commands/scheduler_work.py,sha256=FHBQ8Ajs1zacuQFXaG-KLVRy07m9FqwyJRNVmp7cDg0,6337
 orionis/console/commands/test.py,sha256=-EmQwFwMBuby3OI9HwqMIwuJzd2CGbWbOqmwrR25sOE,2402
 orionis/console/commands/version.py,sha256=SUuNDJ40f2uq69OQUmPQXJKaa9Bm_iVRDPmBd7zc1Yc,3658
 orionis/console/commands/workflow.py,sha256=NYOmjTSvm2o6AE4h9LSTZMFSYPQreNmEJtronyOxaYk,2451
@@ -81,7 +81,7 @@ orionis/console/request/cli_request.py,sha256=7-sgYmNUCipuHLVAwWLJiHv0cJCDmsM1Lu
 orionis/console/tasks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/console/tasks/event.py,sha256=l4J-HEPaj1mxB_PYQMgG9dRHUe01wUag8fKLLnR2N2M,164395
 orionis/console/tasks/listener.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/console/tasks/schedule.py,sha256=y6fnvxofKw_sd-Br2ICzsvinCyV5HDLygLJtDlyTCLw,58292
+orionis/console/tasks/schedule.py,sha256=Lpm_P0Brw8XHiqA-Me9SMevNlo0CzUf-rrt2PKTFW_I,72389
 orionis/container/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/container/container.py,sha256=aF_b6lTUpG4YCo9yFJEzsntTdIzgMMXFW5LyWqAJVBQ,87987
 orionis/container/context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -239,7 +239,7 @@ orionis/foundation/providers/scheduler_provider.py,sha256=72SoixFog9IOE9Ve9Xcfw6
 orionis/foundation/providers/testing_provider.py,sha256=SrJRpdvcblx9WvX7x9Y3zc7OQfiTf7la0HAJrm2ESlE,3725
 orionis/foundation/providers/workers_provider.py,sha256=oa_2NIDH6UxZrtuGkkoo_zEoNIMGgJ46vg5CCgAm7wI,3926
 orionis/metadata/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/metadata/framework.py,sha256=9ERo-wA31Fhf-QLk4fPAYjSxTyE4FM6xHG0dXUxPL_0,4109
+orionis/metadata/framework.py,sha256=LNUd5w9wDJVTDwfg_BIGNlRYyyCu3UpQnvpmOQsMlIQ,4109
 orionis/metadata/package.py,sha256=k7Yriyp5aUcR-iR8SK2ec_lf0_Cyc-C7JczgXa-I67w,16039
 orionis/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/services/asynchrony/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -415,7 +415,7 @@ orionis/test/validators/web_report.py,sha256=n9BfzOZz6aEiNTypXcwuWbFRG0OdHNSmCNu
 orionis/test/validators/workers.py,sha256=rWcdRexINNEmGaO7mnc1MKUxkHKxrTsVuHgbnIfJYgc,1206
 orionis/test/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/test/view/render.py,sha256=f-zNhtKSg9R5Njqujbg2l2amAs2-mRVESneLIkWOZjU,4082
-orionis-0.520.0.dist-info/licenses/LICENCE,sha256=JhC-z_9mbpUrCfPjcl3DhDA8trNDMzb57cvRSam1avc,1463
+orionis-0.522.0.dist-info/licenses/LICENCE,sha256=JhC-z_9mbpUrCfPjcl3DhDA8trNDMzb57cvRSam1avc,1463
 tests/container/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/container/context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/container/context/test_manager.py,sha256=wOwXpl9rHNfTTexa9GBKYMwK0_-KSQPbI-AEyGNkmAE,1356
@@ -561,8 +561,8 @@ tests/testing/validators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZ
 tests/testing/validators/test_testing_validators.py,sha256=WPo5GxTP6xE-Dw3X1vZoqOMpb6HhokjNSbgDsDRDvy4,16588
 tests/testing/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/testing/view/test_render.py,sha256=tnnMBwS0iKUIbogLvu-7Rii50G6Koddp3XT4wgdFEYM,1050
-orionis-0.520.0.dist-info/METADATA,sha256=UAhnPWMKxyQiTmmFb6zL_34hsjfhmzdPIjOrXhmJDYM,4801
-orionis-0.520.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-orionis-0.520.0.dist-info/top_level.txt,sha256=2bdoHgyGZhOtLAXS6Om8OCTmL24dUMC_L1quMe_ETbk,14
-orionis-0.520.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-orionis-0.520.0.dist-info/RECORD,,
+orionis-0.522.0.dist-info/METADATA,sha256=tcvGNIB23Yo-X3d9ClTaZfP9tChX79uyxXZPstmEyhs,4801
+orionis-0.522.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+orionis-0.522.0.dist-info/top_level.txt,sha256=2bdoHgyGZhOtLAXS6Om8OCTmL24dUMC_L1quMe_ETbk,14
+orionis-0.522.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+orionis-0.522.0.dist-info/RECORD,,