orionis 0.536.0__tar.gz → 0.538.0__tar.gz

{orionis-0.536.0/orionis.egg-info → orionis-0.538.0}/PKG-INFO

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

{orionis-0.536.0 → orionis-0.538.0}/orionis/console/contracts/event.py

@@ -5,24 +5,32 @@ from orionis.console.enums.event import Event as EventEntity
 
 class IEvent(ABC):
 
-    @abstractmethod
-    def toEntity(
-        self
-    ) -> EventEntity:
+    def misfireGraceTime(
+        self,
+        seconds: int = 60
+    ) -> 'IEvent':
         """
-        Retrieve the event details as an EventEntity instance.
+        Set the misfire grace time for the event.
 
-        This method gathers all relevant attributes of the current Event object,
-        such as its signature, arguments, purpose, random delay, start and end dates,
-        and trigger, and returns them encapsulated in an EventEntity object.
+        This method allows you to specify a grace period (in seconds) during which
+        a missed execution of the event can still be executed. If the event is not
+        executed within this time frame after its scheduled time, it will be skipped.
+
+        Parameters
+        ----------
+        seconds : int
+            The number of seconds to allow for a misfire grace period. Must be a positive integer.
 
         Returns
         -------
-        EventEntity
-            An EventEntity instance containing the event's signature, arguments,
-            purpose, random delay, start date, end date, and trigger.
+        Event
+            Returns the current instance of the Event to allow method chaining.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the provided seconds is not a positive integer.
         """
-        pass
 
     @abstractmethod
     def purpose(

{orionis-0.536.0 → orionis-0.538.0}/orionis/console/contracts/schedule.py

@@ -218,7 +218,7 @@ class ISchedule(ABC):
         pass
 
     @abstractmethod
-    def pause(self, signature: str) -> bool:
+    def pauseTask(self, signature: str) -> bool:
         """
         Pause a scheduled job in the AsyncIO scheduler.
 
@@ -246,7 +246,7 @@ class ISchedule(ABC):
         pass
 
     @abstractmethod
-    def resume(self, signature: str) -> bool:
+    def resumeTask(self, signature: str) -> bool:
         """
         Resume a paused job in the AsyncIO scheduler.
 
@@ -274,7 +274,7 @@ class ISchedule(ABC):
         pass
 
     @abstractmethod
-    def remove(self, signature: str) -> bool:
+    def removeTask(self, signature: str) -> bool:
         """
         Remove a scheduled job from the AsyncIO scheduler.
 
@@ -324,4 +324,107 @@ class ISchedule(ABC):
                 - 'end_date': str or None, the formatted end date and time of the job, or None if not set.
                 - 'details': any, additional details about the job.
         """
+        pass
+
+    @abstractmethod
+    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.
+        """
+        pass
+
+    @abstractmethod
+    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.
+        """
+        pass
+
+    @abstractmethod
+    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.
+        """
+        pass
+
+    @abstractmethod
+    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.
+        """
+        pass
+
+    @abstractmethod
+    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.
+        """
+        pass
+
+    @abstractmethod
+    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.
+        """
         pass

{orionis-0.536.0 → orionis-0.538.0}/orionis/console/enums/event.py

@@ -60,4 +60,10 @@ class Event:
     details: Optional[str] = None
 
     # Optional listener that implements IScheduleEventListener
-    listener: Optional[IScheduleEventListener] = None
+    listener: Optional[IScheduleEventListener] = None
+
+    # Maximum number of concurrent instances allowed for the event
+    max_instances: int = 1
+
+    # Grace time in seconds for misfired events
+    misfire_grace_time : Optional[int] = None

{orionis-0.536.0 → orionis-0.538.0}/orionis/console/tasks/event.py

@@ -77,6 +77,9 @@ class Event(IEvent):
         # Initialize the maximum instances attribute as None
         self.__max_instances: Optional[int] = None
 
+        # Initialize the misfire grace time attribute as None
+        self.__misfire_grace_time: Optional[int] = None
+
     def toEntity(
         self
     ) -> EventEntity:
@@ -128,6 +131,14 @@ class Event(IEvent):
         if self.__listener is not None and not issubclass(self.__listener, IScheduleEventListener):
             raise CLIOrionisValueError("Listener must implement IScheduleEventListener interface or be None.")
 
+        # Validate that max_instances is a positive integer if it is set
+        if self.__max_instances is not None and (not isinstance(self.__max_instances, int) or self.__max_instances <= 0):
+            raise CLIOrionisValueError("Max instances must be a positive integer or None.")
+
+        # Validate that misfire_grace_time is a positive integer if it is set
+        if self.__misfire_grace_time is not None and (not isinstance(self.__misfire_grace_time, int) or self.__misfire_grace_time <= 0):
+            raise CLIOrionisValueError("Misfire grace time must be a positive integer or None.")
+
         # Construct and return an EventEntity with the current event's attributes
         return EventEntity(
             signature=self.__signature,
@@ -138,9 +149,48 @@ class Event(IEvent):
             end_date=self.__end_date,
             trigger=self.__trigger,
             details=self.__details,
-            listener=self.__listener
+            listener=self.__listener,
+            max_instances=self.__max_instances,
+            misfire_grace_time=self.__misfire_grace_time
         )
 
+    def misfireGraceTime(
+        self,
+        seconds: int = 60
+    ) -> 'Event':
+        """
+        Set the misfire grace time for the event.
+
+        This method allows you to specify a grace period (in seconds) during which
+        a missed execution of the event can still be executed. If the event is not
+        executed within this time frame after its scheduled time, it will be skipped.
+
+        Parameters
+        ----------
+        seconds : int
+            The number of seconds to allow for a misfire grace period. Must be a positive integer.
+
+        Returns
+        -------
+        Event
+            Returns the current instance of the Event to allow method chaining.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the provided seconds is not a positive integer.
+        """
+
+        # Validate that the seconds parameter is a positive integer
+        if not isinstance(seconds, int) or seconds <= 0:
+            raise CLIOrionisValueError("Misfire grace time must be a positive integer.")
+
+        # Set the internal misfire grace time attribute
+        self.__misfire_grace_time = seconds
+
+        # Return self to support method chaining
+        return self
+
     def purpose(
         self,
         purpose: str

{orionis-0.536.0 → orionis-0.538.0}/orionis/console/tasks/schedule.py

@@ -37,7 +37,6 @@ from orionis.console.exceptions import CLIOrionisRuntimeError
 from orionis.console.exceptions.cli_orionis_value_error import CLIOrionisValueError
 from orionis.failure.contracts.catch import ICatch
 from orionis.foundation.contracts.application import IApplication
-from orionis.services.asynchrony.coroutines import Coroutine
 from orionis.services.log.contracts.log_service import ILogger
 
 class Schedule(ISchedule):
@@ -167,7 +166,7 @@ class Schedule(ISchedule):
             # Store each job's signature and description in the commands dictionary
             commands[job['signature']] = {
                 'signature': job['signature'],
-                'description': job.get('description', '')
+                'description': job.get('description', 'No description available.')
             }
 
         # Return the commands dictionary
@@ -268,7 +267,7 @@ class Schedule(ISchedule):
 
         # Prevent adding new commands while the scheduler is running
         if self.isRunning():
-            raise CLIOrionisRuntimeError("Cannot add new commands while the scheduler is running.")
+            self.__raiseException(CLIOrionisValueError("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():
@@ -465,7 +464,7 @@ class Schedule(ISchedule):
 
         # 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.")
+            self.__raiseException(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
@@ -481,16 +480,9 @@ class Schedule(ISchedule):
 
                 # Invoke the listener, handling both coroutine and regular functions
                 try:
-
-                    # Use Coroutine to handle both sync and async listeners
-                    Coroutine(listener).invoke(event_data, self)
-
+                    self.__app.invoke(listener, event_data, self)
                 except BaseException as e:
-
-                    # Construct and log error message
-                    error_msg = f"An error occurred while invoking the listener for event '{scheduler_event}': {str(e)}"
-                    self.__logger.error(error_msg)
-                    raise CLIOrionisRuntimeError(error_msg) from e
+                    self.__raiseException(e)
 
     def __taskCallableListener(
         self,
@@ -528,9 +520,7 @@ class Schedule(ISchedule):
 
         # Validate that the provided event is an instance of ListeningEvent
         if not isinstance(listening_vent, ListeningEvent):
-            error_msg = "The event must be an instance of ListeningEvent."
-            self.__logger.error(error_msg)
-            raise CLIOrionisValueError(error_msg)
+            self.__raiseException(CLIOrionisValueError("The event must be an instance of ListeningEvent."))
 
         # Validate that event_data is not None and has a id attribute
         if not isinstance(event_data, EventJob) or not hasattr(event_data, 'id') or not event_data.id:
@@ -548,38 +538,25 @@ class Schedule(ISchedule):
             # Check if the listener is an instance of IScheduleEventListener
             if issubclass(listener, IScheduleEventListener):
 
-                # Initialize the listener if it's a class
-                if isinstance(listener, type):
-                    listener = listener()
-
-                # 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)
-
-                    # Invoke the listener method, handling both coroutine and regular functions
-                    try:
-
-                        # Use Coroutine to handle both sync and async listener methods
-                        Coroutine(listener_method).invoke(event_data, self)
+                try:
 
-                    except Exception as e:
+                    # Initialize the listener if it's a class
+                    if isinstance(listener, type):
+                        listener = self.__app.make(listener)
 
-                        # Construct and log error message
-                        error_msg = f"An error occurred while invoking the listener_method for event '{scheduler_event}': {str(e)}"
-                        self.__logger.error(error_msg)
-                        raise CLIOrionisRuntimeError(error_msg) from e
+                    # Check if the listener has a method corresponding to the event type
+                    if hasattr(listener, scheduler_event) and callable(getattr(listener, scheduler_event)):
+                        self.__app.call(listener, scheduler_event, event_data, self)
 
-                else:
+                except BaseException as e:
 
-                    # Log a warning if the listener does not have the required method
-                    self.__logger.warning(f"The listener for job ID '{event_data.id}' does not have a method for event '{scheduler_event}'.")
+                    # If an error occurs while invoking the listener, raise an exception
+                    self.__raiseException(e)
 
             else:
 
-                # Log a warning if the listener is not an instance of IScheduleEventListener
-                self.__logger.warning(f"The listener for job ID '{event_data.id}' is not an instance of IScheduleEventListener.")
+                # If the listener is not a subclass of IScheduleEventListener, raise an exception
+                self.__raiseException(CLIOrionisValueError(f"The listener for job ID '{event_data.id}' must be a subclass of IScheduleEventListener."))
 
     def __startedListener(
         self,
@@ -727,10 +704,7 @@ class Schedule(ISchedule):
         self.__globalCallableListener(event_data, ListeningEvent.SCHEDULER_ERROR)
 
         # Catch any exceptions that occur during command handling
-        self.__catch.exception(self, CLIRequest(
-            command=job_event_data.id,
-            args=list(job_event_data.args) or []
-        ), event.exception)
+        self.__raiseException(event.exception)
 
     def __submittedListener(
         self,
@@ -929,7 +903,7 @@ class Schedule(ISchedule):
 
                 try:
                     # Convert the event to its entity representation
-                    entity = event.toEntity()
+                    entity: EventEntity = event.toEntity()
 
                     # Add the job to the internal jobs list
                     self.__jobs.append(entity)
@@ -944,7 +918,9 @@ class Schedule(ISchedule):
                         trigger=entity.trigger,
                         id=signature,
                         name=signature,
-                        replace_existing=True
+                        replace_existing=True,
+                        max_instances=entity.max_instances,
+                        misfire_grace_time=entity.misfire_grace_time
                     )
 
                     # If a listener is associated with the event, register it
@@ -965,6 +941,48 @@ class Schedule(ISchedule):
                     # Raise a runtime error if loading the scheduled event fails
                     raise CLIOrionisRuntimeError(error_msg)
 
+    def __raiseException(
+        self,
+        exception: BaseException
+    ) -> None:
+        """
+        Handle and propagate exceptions through the application's error handling system.
+
+        This private method serves as a centralized exception handler for the scheduler,
+        delegating exception processing to the application's error catching mechanism.
+        It ensures that all exceptions occurring within the scheduler context are
+        properly handled according to the application's error handling policies.
+
+        The method acts as a bridge between the scheduler's internal operations and
+        the application's global exception handling system, providing consistent
+        error handling behavior across the entire application.
+
+        Parameters
+        ----------
+        exception : BaseException
+            The exception instance that was raised during command execution. This can be
+            any type of exception that inherits from BaseException, including system
+            exceptions, custom application exceptions, and runtime errors.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It delegates exception handling
+            to the application's error catching mechanism and may re-raise the
+            exception depending on the configured error handling behavior.
+
+        Notes
+        -----
+        This method is intended for internal use within the scheduler and should not
+        be called directly by external code. The error catching mechanism may perform
+        various actions such as logging, reporting, or re-raising the exception based
+        on the application's configuration.
+        """
+
+        # Delegate exception handling to the application's error catching mechanism
+        # This ensures consistent error handling across the entire application
+        self.__catch.exception(self, CLIRequest(command="schedule:work", args=[]), exception)
+
     def setListener(
         self,
         event: Union[str, ListeningEvent],
@@ -995,7 +1013,7 @@ class Schedule(ISchedule):
 
         Raises
         ------
-        ValueError
+        CLIOrionisValueError
             If the event name is not a non-empty string or if the listener is not callable
             or an instance of IScheduleEventListener.
         """
@@ -1006,11 +1024,11 @@ class Schedule(ISchedule):
 
         # 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.")
+            raise CLIOrionisValueError("Event name must be a non-empty string.")
 
         # 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.")
+            raise CLIOrionisValueError("Listener must be a callable function or an instance of IScheduleEventListener.")
 
         # Register the listener for the specified event in the internal listeners dictionary
         self.__listeners[event] = listener
@@ -1101,19 +1119,13 @@ class Schedule(ISchedule):
             error reporting and debugging information.
             """
 
+            # Execute the asynchronous function using the container's invoke method
             try:
-                # Execute the asynchronous function using the Coroutine utility class
-                # The Coroutine class handles the event loop management and async execution
-                return Coroutine(func).invoke(*args, **kwargs)
+                self.__app.invoke(func, *args, **kwargs)
 
+            # If an error occurs during execution, raise a custom exception
             except Exception as e:
-
-                # Log the error with detailed information for debugging purposes
-                self.__logger.error(f"Error executing async function: {str(e)}")
-
-                # Re-raise the exception wrapped in a custom exception type
-                # This provides better error context and maintains the original stack trace
-                raise CLIOrionisRuntimeError(f"Failed to execute async function: {str(e)}") from e
+                self.__raiseException(e)
 
         # Return the synchronous wrapper function
         return sync_wrapper
@@ -1151,7 +1163,7 @@ class Schedule(ISchedule):
 
         # Validate that the 'at' parameter is a datetime object
         if not isinstance(at, datetime):
-            raise ValueError("The 'at' parameter must be a datetime object.")
+            CLIOrionisValueError("The 'at' parameter must be a datetime object.")
 
         # Define an async function to pause the scheduler
         async def schedule_pause():
@@ -1198,8 +1210,8 @@ class Schedule(ISchedule):
 
                         except Exception as e:
 
-                            # Log a warning if pausing a job fails, but continue with others
-                            self.__logger.warning(f"Failed to pause job '{job.id}': {str(e)}")
+                            # If an error occurs while pausing the job, raise an exception
+                            self.__raiseException(e)
 
                 # Execute the global callable listener after all jobs are paused
                 self.__globalCallableListener(SchedulerPaused(
@@ -1270,7 +1282,7 @@ class Schedule(ISchedule):
 
         # Validate that the 'at' parameter is a datetime object
         if not isinstance(at, datetime):
-            raise ValueError("The 'at' parameter must be a datetime object.")
+            raise CLIOrionisValueError("The 'at' parameter must be a datetime object.")
 
         # Define an async function to resume the scheduler
         async def schedule_resume():
@@ -1300,8 +1312,8 @@ class Schedule(ISchedule):
 
                         except Exception as e:
 
-                            # Log a warning if resuming a job fails, but continue with others
-                            self.__logger.warning(f"Failed to resume job '{job_id}': {str(e)}")
+                            # If an error occurs while resuming the job, raise an exception
+                            self.__raiseException(e)
 
                     # Clear the set after resuming all jobs
                     self.__pausedByPauseEverything.clear()
@@ -1407,8 +1419,7 @@ class Schedule(ISchedule):
                 except Exception as e:
 
                     # Log any errors that occur during shutdown
-                    error_msg = f"Error during scheduled shutdown: {str(e)}"
-                    self.__logger.error(error_msg)
+                    self.__logger.error(f"Error during scheduled shutdown: {str(e)}")
 
                     # Force stop if graceful shutdown fails
                     self.forceStop()
@@ -1542,7 +1553,7 @@ class Schedule(ISchedule):
 
         # Validate the wait parameter
         if not isinstance(wait, bool):
-            raise ValueError("The 'wait' parameter must be a boolean value.")
+            self.__raiseException(CLIOrionisValueError("The 'wait' parameter must be a boolean value."))
 
         # If the scheduler is not running, there's nothing to shut down
         if not self.isRunning():
@@ -1570,9 +1581,9 @@ class Schedule(ISchedule):
         except Exception as e:
 
             # Handle exceptions that may occur during shutdown
-            raise CLIOrionisRuntimeError(f"Failed to shut down the scheduler: {str(e)}") from e
+            self.__raiseException(CLIOrionisRuntimeError(f"Failed to shut down the scheduler: {str(e)}"))
 
-    def pause(self, signature: str) -> bool:
+    def pauseTask(self, signature: str) -> bool:
         """
         Pause a scheduled job in the AsyncIO scheduler.
 
@@ -1600,7 +1611,7 @@ class Schedule(ISchedule):
 
         # 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.")
+            self.__raiseException(CLIOrionisValueError("Signature must be a non-empty string."))
 
         try:
 
@@ -1618,7 +1629,7 @@ class Schedule(ISchedule):
             # Return False if the job could not be paused (e.g., it does not exist)
             return False
 
-    def resume(self, signature: str) -> bool:
+    def resumeTask(self, signature: str) -> bool:
         """
         Resume a paused job in the AsyncIO scheduler.
 
@@ -1646,7 +1657,7 @@ class Schedule(ISchedule):
 
         # 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.")
+            self.__raiseException(CLIOrionisValueError("Signature must be a non-empty string."))
 
         try:
             # Attempt to resume the job with the given signature
@@ -1663,7 +1674,7 @@ class Schedule(ISchedule):
             # Return False if the job could not be resumed (e.g., it does not exist)
             return False
 
-    def remove(self, signature: str) -> bool:
+    def removeTask(self, signature: str) -> bool:
         """
         Remove a scheduled job from the AsyncIO scheduler.
 
@@ -1692,7 +1703,7 @@ class Schedule(ISchedule):
 
         # 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.")
+            self.__raiseException(CLIOrionisValueError("Signature must be a non-empty string."))
 
         try: