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

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