orionis 0.512.0__py3-none-any.whl → 0.514.0__py3-none-any.whl

orionis/console/contracts/scheduler.py

@@ -0,0 +1,140 @@
+from abc import ABC, abstractmethod
+from datetime import datetime
+from orionis.console.contracts.schedule import ISchedule
+
+class IBaseScheduler(ABC):
+
+    # Pause Global Scheduler at a specific time
+    PAUSE_AT: datetime = None
+
+    # Resume Global Scheduler at a specific time
+    RESUME_AT: datetime = None
+
+    # Finalize Global Scheduler at a specific time
+    FINALIZE_AT: datetime = None
+
+    @abstractmethod
+    def tasks(self, schedule: ISchedule):
+        """
+        Defines and registers scheduled tasks for the application.
+
+        Parameters
+        ----------
+        schedule : ISchedule
+            The schedule object used to define and register scheduled commands. 
+            This object provides methods to add tasks to the scheduler.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It is intended to be overridden
+            by subclasses to specify scheduled tasks.
+
+        Notes
+        -----
+        This method serves as a contract for subclasses to implement task registration
+        logic. Subclasses should use the provided `schedule` object to define and
+        register tasks that the scheduler will execute.
+        """
+        # Abstract method to be implemented by subclasses for task registration
+        pass
+
+    @abstractmethod
+    def onStarted(self):
+        """
+        Called when the scheduler is started.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        Subclasses should override this method to implement custom behavior that
+        should occur when the scheduler starts running. This can include initializing
+        resources or logging the start event.
+        """
+        # Abstract method to define behavior when the scheduler starts
+        pass
+
+    @abstractmethod
+    def onPaused(self):
+        """
+        Called when the scheduler is paused.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        Subclasses should override this method to define custom behavior that occurs
+        when the scheduler enters a paused state. This can include saving the current
+        state or logging the pause event.
+        """
+        # Abstract method to define behavior when the scheduler is paused
+        pass
+
+    @abstractmethod
+    def onResumed(self):
+        """
+        Called when the scheduler is resumed from a paused state.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        Subclasses should override this method to implement any actions that need to
+        occur when the scheduler resumes operation. This can include restoring the
+        state or logging the resume event.
+        """
+        # Abstract method to define behavior when the scheduler is resumed
+        pass
+
+    @abstractmethod
+    def onFinalized(self):
+        """
+        Called when the scheduler has completed its execution and is being finalized.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        Subclasses can override this method to perform any necessary cleanup or
+        finalization tasks, such as releasing resources or logging the finalization
+        event.
+        """
+        # Abstract method to define behavior when the scheduler is finalized
+        pass
+
+    @abstractmethod
+    def onError(self, error: Exception):
+        """
+        Handles errors that occur within the scheduler.
+
+        Parameters
+        ----------
+        error : Exception
+            The exception instance representing the error that occurred.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        Subclasses can override this method to implement custom error handling logic
+        for the scheduler. This can include logging the error, notifying stakeholders,
+        or attempting to recover from the error.
+        """
+        # Abstract method to define behavior for handling errors in the scheduler
+        pass

orionis/console/core/reactor.py

@@ -4,7 +4,7 @@ import re
 from typing import Any, List, Optional
 from orionis.console.args.argument import CLIArgument
 from orionis.console.base.command import BaseCommand
-from orionis.console.base.contracts.command import IBaseCommand
+from orionis.console.contracts.command import IBaseCommand
 from orionis.console.contracts.reactor import IReactor
 from orionis.console.enums.command import Command
 from orionis.console.exceptions import CLIOrionisValueError

orionis/console/entities/job_modified.py

@@ -19,5 +19,4 @@ class JobModified(JobEventData):
         This class does not return a value; it is used as a data container.
     """
 
-    # This class inherits from JobEventData and does not add additional fields or methods.
-    # It serves as a specific type of event for job modifications.
+    next_run_time: str | None = None

orionis/console/enums/event.py

@@ -4,32 +4,37 @@ from datetime import datetime
 from apscheduler.triggers.cron import CronTrigger
 from apscheduler.triggers.date import DateTrigger
 from apscheduler.triggers.interval import IntervalTrigger
-from orionis.support.entities.base import BaseEntity
+from orionis.console.contracts.schedule_event_listener import IScheduleEventListener
 
 @dataclass(kw_only=True)
-class Event(BaseEntity):
+class Event:
     """
     Represents an event with scheduling and execution details.
 
     Attributes
     ----------
     signature : str
-        The unique identifier or signature of the event.
+        The unique identifier or signature of the event, used to distinguish it from other events.
     args : Optional[List[str]]
-        A list of arguments associated with the event.
+        A list of arguments associated with the event. Defaults to an empty list if not provided.
     purpose : Optional[str]
-        A description of the event's purpose.
+        A brief description of the event's purpose or intent. Can be None if not specified.
     random_delay : Optional[int]
-        An optional random delay (in seconds) before the event is triggered.
+        An optional random delay (in seconds) to be applied before the event is triggered. Can be None.
     start_date : Optional[datetime]
-        The start date and time for the event.
+        The start date and time for the event. If None, the event starts immediately or based on the trigger.
     end_date : Optional[datetime]
-        The end date and time for the event.
+        The end date and time for the event. If None, the event does not have a defined end time.
     trigger : Optional[Union[CronTrigger, DateTrigger, IntervalTrigger]]
-        The trigger mechanism for the event.
+        The trigger mechanism for the event, which determines when and how the event is executed.
+        Can be a CronTrigger, DateTrigger, or IntervalTrigger. Defaults to None.
+    details : Optional[str]
+        Additional details or metadata about the event. Can be None if not specified.
+    listener : Optional[IScheduleEventListener]
+        An optional listener object that implements the IScheduleEventListener interface. 
+        This listener can handle event-specific logic. Defaults to None.
     """
 
-
     # Unique identifier for the event
     signature: str
 
@@ -52,4 +57,7 @@ class Event(BaseEntity):
     trigger: Optional[Union[CronTrigger, DateTrigger, IntervalTrigger]] = None
 
     # Optional details about the event
-    details: Optional[str] = None
+    details: Optional[str] = None
+
+    # Optional listener that implements IScheduleEventListener
+    listener: Optional[IScheduleEventListener] = None

orionis/console/enums/listener.py

@@ -2,7 +2,11 @@ from enum import Enum
 
 class ListeningEvent(Enum):
     """
-    Enum representing global listener events.
+    Enumeration of events related to a scheduler and its jobs.
+
+    This class defines various events that can occur during the lifecycle of a scheduler
+    and its associated jobs. These events can be used to monitor and respond to changes
+    in the scheduler's state or the execution of jobs.
 
     Attributes
     ----------
@@ -13,63 +17,47 @@ class ListeningEvent(Enum):
     SCHEDULER_PAUSED : str
         Event triggered when the scheduler is paused.
     SCHEDULER_RESUMED : str
-        Event triggered when the scheduler resumes.
+        Event triggered when the scheduler is resumed.
     SCHEDULER_ERROR : str
         Event triggered when the scheduler encounters an error.
-    SCHEDULER_STARTED : str
-        Event triggered when the scheduler starts.
-    SCHEDULER_SHUTDOWN : str
-        Event triggered when the scheduler shuts down.
-    SCHEDULER_PAUSED : str
-        Event triggered when the scheduler is paused.
-    SCHEDULER_RESUMED : str
-        Event triggered when the scheduler resumes.
-    EXECUTOR_ADDED : str
-        Event triggered when an executor is added.
-    EXECUTOR_REMOVED : str
-        Event triggered when an executor is removed.
-    JOBSTORE_ADDED : str
-        Event triggered when a job store is added.
-    JOBSTORE_REMOVED : str
-        Event triggered when a job store is removed.
-    ALL_JOBS_REMOVED : str
-        Event triggered when all jobs are removed.
-    JOB_ADDED : str
-        Event triggered when a job is added.
-    JOB_REMOVED : str
-        Event triggered when a job is removed.
-    JOB_MODIFIED : str
-        Event triggered when a job is modified.
-    JOB_EXECUTED : str
-        Event triggered when a job is executed.
-    JOB_ERROR : str
-        Event triggered when a job encounters an error.
-    JOB_MISSED : str
+    JOB_BEFORE : str
+        Event triggered before a job is executed.
+    JOB_AFTER : str
+        Event triggered after a job is executed.
+    JOB_ON_SUCCESS : str
+        Event triggered when a job completes successfully.
+    JOB_ON_FAILURE : str
+        Event triggered when a job fails.
+    JOB_ON_MISSED : str
         Event triggered when a job is missed.
-    JOB_SUBMITTED : str
-        Event triggered when a job is submitted.
-    JOB_MAX_INSTANCES : str
-        Event triggered when a job exceeds max instances.
-    ALL : str
-        Event triggered for all events.
+    JOB_ON_MAXINSTANCES : str
+        Event triggered when a job exceeds its maximum allowed instances.
+    JOB_ON_PAUSED : str
+        Event triggered when a job is paused.
+    JOB_ON_RESUMED : str
+        Event triggered when a paused job is resumed.
+    JOB_ON_REMOVED : str
+        Event triggered when a job is removed.
+
+    Returns
+    -------
+    str
+        The string representation of the event name.
     """
 
-    SCHEDULER_STARTED = "X-ORIONIS-EVENT-SCHEDULER-STARTED"
-    SCHEDULER_SHUTDOWN = "X-ORIONIS-EVENT-SCHEDULER-SHUTDOWN"
-    SCHEDULER_PAUSED = "X-ORIONIS-EVENT-SCHEDULER-PAUSED"
-    SCHEDULER_RESUMED = "X-ORIONIS-EVENT-SCHEDULER-RESUMED"
-    SCHEDULER_ERROR = "X-ORIONIS-SCHEDULER-ERROR"
-    EXECUTOR_ADDED = "X-ORIONIS-EVENT-EXECUTOR-ADDED"
-    EXECUTOR_REMOVED = "X-ORIONIS-EVENT-EXECUTOR-REMOVED"
-    JOBSTORE_ADDED = "X-ORIONIS-EVENT-JOBSTORE-ADDED"
-    JOBSTORE_REMOVED = "X-ORIONIS-EVENT-JOBSTORE-REMOVED"
-    ALL_JOBS_REMOVED = "X-ORIONIS-EVENT-ALL-JOBS-REMOVED"
-    JOB_ADDED = "X-ORIONIS-EVENT-JOB-ADDED"
-    JOB_REMOVED = "X-ORIONIS-EVENT-JOB-REMOVED"
-    JOB_MODIFIED = "X-ORIONIS-EVENT-JOB-MODIFIED"
-    JOB_EXECUTED = "X-ORIONIS-EVENT-JOB-EXECUTED"
-    JOB_ERROR = "X-ORIONIS-EVENT-JOB-ERROR"
-    JOB_MISSED = "X-ORIONIS-EVENT-JOB-MISSED"
-    JOB_SUBMITTED = "X-ORIONIS-EVENT-JOB-SUBMITTED"
-    JOB_MAX_INSTANCES = "X-ORIONIS-EVENT-JOB-MAX-INSTANCES"
-    ALL = "X-ORIONIS-EVENT-ALL"
+    # Scheduler-related events
+    SCHEDULER_STARTED = "schedulerStarted"                  # Triggered when the scheduler starts
+    SCHEDULER_SHUTDOWN = "schedulerShutdown"                # Triggered when the scheduler shuts down
+    SCHEDULER_PAUSED = "schedulerPaused"                    # Triggered when the scheduler is paused
+    SCHEDULER_RESUMED = "schedulerResumed"                  # Triggered when the scheduler is resumed
+    SCHEDULER_ERROR = "schedulerError"                      # Triggered when the scheduler encounters an error
+
+    # Job-related events
+    JOB_BEFORE = "before"                                   # Triggered before a job is executed
+    JOB_AFTER = "after"                                     # Triggered after a job is executed
+    JOB_ON_FAILURE = "onFailure"                            # Triggered when a job fails
+    JOB_ON_MISSED = "onMissed"                              # Triggered when a job is missed
+    JOB_ON_MAXINSTANCES = "onMaxInstances"                  # Triggered when a job exceeds its max instances
+    JOB_ON_PAUSED = "onPaused"                              # Triggered when a job is paused
+    JOB_ON_RESUMED = "onResumed"                            # Triggered when a paused job is resumed
+    JOB_ON_REMOVED = "onRemoved"                            # Triggered when a job is removed

orionis/console/tasks/event.py

@@ -20,25 +20,34 @@ class Event(IEvent):
         """
         Initialize a new Event instance.
 
+        This constructor sets up the initial state of an Event object, including its
+        unique signature, arguments, purpose, and other optional attributes such as
+        random delay, start and end dates, trigger, details, listener, and maximum
+        instances. These attributes define the behavior and metadata of the event.
+
         Parameters
         ----------
         signature : str
-            The unique identifier or signature for the event. This is typically
-            used to distinguish between different events in the system.
-        args : Optional[List[str]]
-            A list of arguments required by the event. If not provided, an empty
-            list will be used.
-        purpose : Optional[str], optional
-            A human-readable description or purpose for the event, by default None.
+            A unique identifier for the event. This is required and must be a non-empty string.
+        args : list of str, optional
+            A list of arguments associated with the event. Defaults to an empty list if None is provided.
+        purpose : str, optional
+            A human-readable description or purpose of the event. Defaults to None.
 
         Returns
         -------
         None
-            This constructor does not return any value. It initializes the internal
-            state of the Event object.
+            This method does not return any value. It initializes the Event instance.
+
+        Notes
+        -----
+        The `__trigger` attribute is initially set to None and can later be configured
+        to a Cron, Date, or Interval trigger. Similarly, the `__listener` attribute is
+        set to None and can be assigned an instance of `IScheduleEventListener` to handle
+        event-specific logic.
         """
 
-        # Store the event's signature
+        # Store the event's unique signature
         self.__signature: str = signature
 
         # Store the event's arguments, defaulting to an empty list if None is provided
@@ -88,8 +97,12 @@ class Event(IEvent):
         # Validate that the signature is set and is a non-empty string
         if not self.__signature:
             raise CLIOrionisValueError("Signature is required for the event.")
+
+        # Validate arguments
         if not isinstance(self.__args, list):
             raise CLIOrionisValueError("Args must be a list.")
+
+        # Validate that purpose is a string if it is set
         if self.__purpose is not None and not isinstance(self.__purpose, str):
             raise CLIOrionisValueError("Purpose must be a string or None.")
 
@@ -111,6 +124,10 @@ class Event(IEvent):
         if self.__details is not None and not isinstance(self.__details, str):
             raise CLIOrionisValueError("Details must be a string or None.")
 
+        # Validate that listener is an IScheduleEventListener instance if it is set
+        if self.__listener is not None and not isinstance(self.__listener, IScheduleEventListener):
+            raise CLIOrionisValueError("Listener must implement IScheduleEventListener interface or be None.")
+
         # Construct and return an EventEntity with the current event's attributes
         return EventEntity(
             signature=self.__signature,
@@ -120,7 +137,8 @@ class Event(IEvent):
             start_date=self.__start_date,
             end_date=self.__end_date,
             trigger=self.__trigger,
-            details=self.__details
+            details=self.__details,
+            listener=self.__listener
         )
 
     def purpose(
@@ -332,9 +350,9 @@ class Event(IEvent):
         when the event is executed.
         """
 
-        # Validate that the provided listener implements the IScheduleEventListener interface
+        # Validate that the provided listener is an instance of IScheduleEventListener
         if not isinstance(listener, IScheduleEventListener):
-            raise CLIOrionisValueError("Listener must implement IScheduleEventListener interface.")
+            raise CLIOrionisValueError("Listener must be an instance of IScheduleEventListener.")
 
         # Assign the listener to the event's internal listener attribute
         self.__listener = listener