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

orionis/console/contracts/schedule.py

@@ -4,6 +4,40 @@ from orionis.console.tasks.event import Event
 
 class ISchedule(ABC):
 
+    @abstractmethod
+    def _setListener(
+        self,
+        event: str,
+        listener: callable
+    ) -> None:
+        """
+        Register a listener callback for a specific scheduler event.
+
+        This method allows the registration of a callable listener function that will be
+        invoked when the specified scheduler event occurs. The event can be one of the
+        predefined global events or a specific job ID. The listener must be a callable
+        function that accepts a single argument, which will be the event object.
+
+        Parameters
+        ----------
+        event : str
+            The name of the event to listen for. This can be a global event name (e.g., 'scheduler_started')
+            or a specific job ID.
+        listener : callable
+            A callable function that will be invoked when the specified event occurs.
+            The function should accept one parameter, which will be the event object.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It registers the listener for the specified event.
+
+        Raises
+        ------
+        ValueError
+            If the event name is not a non-empty string or if the listener is not callable.
+        """
+
     @abstractmethod
     def command(
         self,

orionis/console/contracts/schedule_event_listener.py

@@ -0,0 +1,324 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+from orionis.console.entities.job_error import JobError
+from orionis.console.entities.job_executed import JobExecuted
+from orionis.console.entities.job_max_instances import JobMaxInstances
+from orionis.console.entities.job_missed import JobMissed
+from orionis.console.entities.job_pause import JobPause
+from orionis.console.entities.job_removed import JobRemoved
+from orionis.console.entities.job_resume import JobResume
+from orionis.console.entities.job_submitted import JobSubmitted
+
+if TYPE_CHECKING:
+    from orionis.console.contracts.schedule import ISchedule
+
+class IScheduleEventListener(ABC):
+    """
+    Interface for event listeners that handle various stages of event processing.
+    """
+
+    @abstractmethod
+    async def before(self, event: JobSubmitted, schedule):
+        """
+        Hook method called before the main event handling logic.
+
+        This method is invoked prior to processing the event, allowing for any
+        pre-processing or setup tasks to be performed. It can be overridden to
+        implement custom logic that should execute before the event is handled.
+
+        Parameters
+        ----------
+        event : JobSubmitted
+            The event object that is about to be processed. This contains
+            information about the job submission.
+        schedule : ISchedule
+            The schedule object associated with the event. This provides
+            context about the scheduling system.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        Override this method to define actions or checks that should occur
+        before the event is processed.
+        """
+
+        # This is an abstract method, so it does not contain any implementation.
+        # Subclasses must override this method to provide specific behavior.
+        pass
+
+    @abstractmethod
+    async def after(self, event: JobExecuted, schedule):
+        """
+        Hook method called after an event is processed.
+
+        This method is invoked once the event processing is complete, allowing
+        for any post-processing or cleanup tasks to be performed. It can be
+        overridden to implement custom logic that should execute after the
+        event is handled.
+
+        Parameters
+        ----------
+        event : JobExecuted
+            The event object that was processed. This contains information
+            about the job execution, such as its status and metadata.
+        schedule : ISchedule
+            The schedule object associated with the event. This provides
+            context about the scheduling system and its state.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        Override this method to define actions or checks that should occur
+        after the event is processed, such as logging, resource cleanup, or
+        triggering subsequent tasks.
+        """
+
+        # This is an abstract method, so it does not contain any implementation.
+        # Subclasses must override this method to provide specific behavior.
+        pass
+
+    @abstractmethod
+    async def onSuccess(self, event: JobExecuted, schedule):
+        """
+        Handle actions to be performed when an event is successfully processed.
+
+        This method is invoked after an event is processed successfully, allowing
+        for any follow-up actions, such as logging, notifications, or triggering
+        dependent tasks. Subclasses should override this method to define custom
+        behavior for handling successful event processing.
+
+        Parameters
+        ----------
+        event : JobExecuted
+            The event object containing details about the successfully executed job,
+            such as its status, metadata, and execution results.
+        schedule : ISchedule
+            The schedule object associated with the event, providing context about
+            the scheduling system and its state.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        Override this method to implement specific actions or checks that should
+        occur after an event is successfully processed.
+        """
+
+        # This is an abstract method, so it does not contain any implementation.
+        # Subclasses must override this method to provide specific behavior.
+        pass
+
+    @abstractmethod
+    async def onFailure(self, event: JobError, schedule):
+        """
+        Handle the event when a failure occurs during event processing.
+
+        This method is invoked whenever an error or failure occurs during the
+        processing of an event. It allows for custom error handling logic to be
+        implemented, such as logging the error, notifying relevant parties, or
+        performing cleanup tasks. Subclasses should override this method to
+        define specific actions to take in response to failures.
+
+        Parameters
+        ----------
+        event : JobError
+            The event object containing detailed information about the failure,
+            including the error message, stack trace, and any relevant metadata.
+        schedule : ISchedule
+            The schedule object associated with the event, providing context
+            about the scheduling system and its state at the time of the failure.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It is intended for handling
+            side effects or performing actions in response to the failure.
+
+        Notes
+        -----
+        Override this method to implement specific error handling logic that
+        aligns with the application's requirements.
+        """
+
+        # This is an abstract method, so it does not contain any implementation.
+        # Subclasses must override this method to provide specific behavior.
+        pass
+
+    @abstractmethod
+    async def onMissed(self, event: JobMissed, schedule):
+        """
+        Handle the event triggered when an expected job execution is missed.
+
+        This method is invoked whenever a scheduled job is missed, allowing for
+        custom handling logic to be implemented. Subclasses should override this
+        method to define specific actions to take in response to missed events,
+        such as logging, notifications, or corrective measures.
+
+        Parameters
+        ----------
+        event : JobMissed
+            The event object containing details about the missed job, including
+            its metadata and the reason it was missed.
+        schedule : ISchedule
+            The schedule object associated with the event, providing context
+            about the scheduling system and its state at the time of the missed event.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It is intended for handling
+            side effects or performing actions in response to the missed event.
+
+        Notes
+        -----
+        Override this method to implement specific logic that aligns with the
+        application's requirements for handling missed job executions.
+        """
+
+        # Abstract method: Subclasses must provide an implementation for this.
+        pass
+
+    @abstractmethod
+    async def onMaxInstances(self, event: JobMaxInstances, schedule):
+        """
+        Handle the event triggered when a job exceeds the maximum allowed instances.
+
+        This method is invoked whenever a job attempts to run but is blocked
+        because it has reached its maximum number of concurrent instances.
+        Subclasses should override this method to define specific actions to
+        take in response to this event, such as logging, notifications, or
+        implementing backoff strategies.
+
+        Parameters
+        ----------
+        event : JobMaxInstances
+            The event object containing details about the job that exceeded
+            its maximum instances, including its metadata and the configured limit.
+        schedule : ISchedule
+            The schedule object associated with the event, providing context
+            about the scheduling system and its state at the time of the event.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It is intended for handling
+            side effects or performing actions in response to the max instances event.
+
+        Notes
+        -----
+        Override this method to implement specific logic that aligns with the
+        application's requirements for handling jobs that exceed their maximum instances.
+        """
+
+        # Abstract method: Subclasses must provide an implementation for this.
+        pass
+
+    @abstractmethod
+    async def onPaused(self, event: JobPause, schedule):
+        """
+        Handle the event triggered when the scheduler is paused.
+
+        This method is invoked whenever the scheduler is paused, allowing for
+        custom handling logic to be implemented. Subclasses should override this
+        method to define specific actions to take in response to the pause event,
+        such as logging, notifications, or resource management.
+
+        Parameters
+        ----------
+        event : JobPause
+            The event object containing details about the pause event.
+        schedule : ISchedule
+            The schedule object associated with the event, providing context
+            about the scheduling system and its state at the time of the pause event.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It is intended for handling
+            side effects or performing actions in response to the pause event.
+
+        Notes
+        -----
+        Override this method to implement specific logic that aligns with the
+        application's requirements for handling scheduler pause events.
+        """
+
+        # Abstract method: Subclasses must provide an implementation for this.
+        pass
+
+    @abstractmethod
+    async def onResumed(self, event: JobResume, schedule):
+        """
+        Handle the event triggered when the scheduler is resumed.
+
+        This method is invoked whenever the scheduler is resumed, allowing for
+        custom handling logic to be implemented. Subclasses should override this
+        method to define specific actions to take in response to the resume event,
+        such as logging, notifications, or resource management.
+
+        Parameters
+        ----------
+        event : JobResume
+            The event object containing details about the resume event.
+        schedule : ISchedule
+            The schedule object associated with the event, providing context
+            about the scheduling system and its state at the time of the resume event.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It is intended for handling
+            side effects or performing actions in response to the resume event.
+
+        Notes
+        -----
+        Override this method to implement specific logic that aligns with the
+        application's requirements for handling scheduler resume events.
+        """
+
+        # Abstract method: Subclasses must provide an implementation for this.
+        pass
+
+    @abstractmethod
+    async def onRemoved(self, event: JobRemoved, schedule):
+        """
+        Handle the event triggered when a job is removed from the scheduler.
+
+        This method is invoked whenever a job is removed, allowing for custom
+        handling logic to be implemented. Subclasses should override this method
+        to define specific actions to take in response to the job removal event,
+        such as logging, notifications, or resource cleanup.
+
+        Parameters
+        ----------
+        event : JobRemoved
+            The event object containing details about the removed job.
+        schedule : ISchedule
+            The schedule object associated with the event, providing context
+            about the scheduling system and its state at the time of the job removal.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It is intended for handling
+            side effects or performing actions in response to the job removal event.
+
+        Notes
+        -----
+        Override this method to implement specific logic that aligns with the
+        application's requirements for handling job removal events.
+        """
+
+        # Abstract method: Subclasses must provide an implementation for this.
+        pass

orionis/console/entities/all_jobs_removed.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+from orionis.console.entities.scheduler_event_data import SchedulerEventData
+
+@dataclass(kw_only=True)
+class AllJobsRemoved(SchedulerEventData):
+    """
+    Represents an event triggered when all jobs are removed from a specific job store.
+
+    This event is typically used to notify that a job store has been cleared of all its jobs.
+
+    Attributes
+    ----------
+    jobstore : str
+        The alias or identifier of the job store from which all jobs were removed.
+
+    Returns
+    -------
+    None
+        This class does not return a value; it is used to encapsulate event data.
+    """
+
+    # The alias of the job store from which jobs were removed
+    jobstore: str

orionis/console/entities/executor_added.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+from orionis.console.entities.scheduler_event_data import SchedulerEventData
+
+@dataclass(kw_only=True)
+class ExecutorAdded(SchedulerEventData):
+    """
+    Represents an event triggered when an executor is added to the system.
+
+    This event is used to notify that a new executor has been successfully added.
+
+    Attributes
+    ----------
+    alias : str
+        The unique alias or identifier of the added executor.
+
+    Returns
+    -------
+    ExecutorAdded
+        An instance of the ExecutorAdded event containing the alias of the added executor.
+    """
+
+    # The alias of the added executor, used to uniquely identify it
+    alias: str

orionis/console/entities/executor_removed.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+from orionis.console.entities.scheduler_event_data import SchedulerEventData
+
+@dataclass(kw_only=True)
+class ExecutorRemoved(SchedulerEventData):
+    """
+    Represents an event triggered when an executor is removed.
+
+    This event is used to notify the system that a specific executor, identified 
+    by its alias, has been removed from the scheduler.
+
+    Attributes
+    ----------
+    alias : str
+        The alias (unique identifier) of the removed executor.
+
+    Returns
+    -------
+    None
+        This class does not return a value; it is used as a data structure 
+        to encapsulate event information.
+    """
+
+    # The alias of the removed executor
+    alias: str

orionis/console/entities/job_added.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass
+from orionis.console.entities.job_event_data import JobEventData
+
+@dataclass(kw_only=True)
+class JobAdded(JobEventData):
+    """
+    Represents an event triggered when a job is added to a job store.
+
+    This class extends the `JobEventData` base class, inheriting its attributes
+    and functionality. It is used to encapsulate data related to the addition
+    of a job in the system.
+
+    Attributes
+    ----------
+    Inherits all attributes from the `JobEventData` base class.
+
+    Returns
+    -------
+    JobAdded
+        An instance of the `JobAdded` class containing data about the added job.
+    """
+
+    # This class currently does not define additional attributes or methods.
+    # It serves as a specialized event type for job addition events.

orionis/console/entities/job_error.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+from datetime import datetime
+from orionis.console.entities.job_event_data import JobEventData
+
+@dataclass(kw_only=True)
+class JobError(JobEventData):
+    """
+    Represents an event triggered when a job raises an exception during execution.
+
+    This class is used to encapsulate information about an error that occurred
+    during the execution of a scheduled job, including the time the job was
+    scheduled to run, the exception raised, and the traceback details.
+
+    Attributes
+    ----------
+    scheduled_run_time : datetime
+        The datetime when the job was scheduled to run.
+    exception : Exception
+        The exception instance raised by the job during execution.
+    traceback : str
+        The traceback string providing details about where the exception occurred.
+
+    Returns
+    -------
+    JobError
+        An instance of the `JobError` class containing details about the job error event.
+    """
+    # The time the job was scheduled to run
+    scheduled_run_time: datetime
+
+    # The exception raised during the job's execution
+    exception: Exception
+
+    # The traceback string providing details about the exception
+    traceback: str

orionis/console/entities/job_event_data.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from typing import Optional
+from orionis.console.entities.scheduler_event_data import SchedulerEventData
+
+@dataclass(kw_only=True)
+class JobEventData(SchedulerEventData):
+    """
+    Represents the base class for events related to jobs in the scheduler system.
+
+    This class extends `SchedulerEventData` and provides additional attributes
+    specific to job-related events, such as the job's identifier and the job store
+    where it resides.
+
+    Attributes
+    ----------
+    code : int
+        A numeric code that uniquely identifies the type of event within the
+        scheduler system. (Inherited from `SchedulerEventData`)
+    alias : str, optional
+        An optional string providing additional context or identifying specific
+        components (e.g., executors or job stores) related to the event.
+        (Inherited from `SchedulerEventData`)
+    job_id : str
+        The unique identifier of the job associated with the event.
+    jobstore : str, optional
+        The name of the job store where the job is located. If not specified,
+        it defaults to `None`.
+
+    Returns
+    -------
+    JobEventData
+        An instance of the `JobEventData` class containing information about
+        the job-related event.
+    """
+
+    # The unique identifier of the job
+    job_id: str
+
+    # The name of the job store where the job resides (optional)
+    jobstore: Optional[str] = None

orionis/console/entities/job_executed.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+from orionis.console.entities.job_event_data import JobEventData
+
+@dataclass(kw_only=True)
+class JobExecuted(JobEventData):
+    """
+    Represents an event triggered when a job completes successfully.
+
+    This class is used to encapsulate information about a successfully executed job, 
+    including the time it was scheduled to run and the return value of the job function.
+
+    Attributes
+    ----------
+    scheduled_run_time : datetime
+        The datetime when the job was scheduled to execute.
+    retval : Any
+        The return value produced by the job function upon successful execution.
+
+    Returns
+    -------
+    JobExecuted
+        An instance of the `JobExecuted` class containing details about the executed job.
+    """
+
+    # The datetime when the job was scheduled to run
+    scheduled_run_time: datetime
+
+    # The return value of the job function
+    retval: Any

orionis/console/entities/job_max_instances.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+from datetime import datetime
+from orionis.console.entities.job_event_data import JobEventData
+
+@dataclass(kw_only=True)
+class JobMaxInstances(JobEventData):
+    """
+    Represents an event triggered when a job exceeds its maximum allowed instances.
+
+    This class is a specialized event data structure that inherits from `JobEventData`. 
+    It is used to capture and store information about the event when a job exceeds 
+    the maximum number of instances it is allowed to run.
+
+    Attributes
+    ----------
+    run_time : datetime
+        The datetime when the job was scheduled to run. This indicates the time 
+        the job was supposed to execute before exceeding the instance limit.
+
+    Returns
+    -------
+    JobMaxInstances
+        An instance of the `JobMaxInstances` class containing the event details.
+    """
+
+    # The time the job was scheduled to run
+    run_time: datetime

orionis/console/entities/job_missed.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+from datetime import datetime
+from orionis.console.entities.job_event_data import JobEventData
+
+@dataclass(kw_only=True)
+class JobMissed(JobEventData):
+    """
+    Represents an event triggered when a scheduled job run is missed due to scheduler constraints.
+
+    This class extends `JobEventData` and provides additional information about the missed job event, 
+    specifically the time the job was originally scheduled to run.
+
+    Attributes
+    ----------
+    scheduled_run_time : datetime
+        The datetime when the job was originally scheduled to execute.
+
+    Returns
+    -------
+    None
+        This class does not return a value; it is used to encapsulate event data.
+    """
+
+    # The datetime when the job was supposed to run but was missed
+    scheduled_run_time: datetime

orionis/console/entities/job_modified.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+from orionis.console.entities.job_event_data import JobEventData
+
+@dataclass(kw_only=True)
+class JobModified(JobEventData):
+    """
+    Represents an event triggered when a job is modified in a job store.
+
+    This class is a data structure that extends `JobEventData` to provide
+    additional context or functionality specific to job modification events.
+
+    Attributes
+    ----------
+    (Inherited from JobEventData)
+
+    Returns
+    -------
+    None
+        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.

orionis/console/entities/job_pause.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+from orionis.console.entities.job_event_data import JobEventData
+
+@dataclass(kw_only=True)
+class JobPause(JobEventData):
+    """
+    Represents an event triggered when a job is paused in the job store.
+
+    This class extends `JobEventData` to provide additional context or
+    functionality specific to the pausing of a job.
+
+    Attributes
+    ----------
+    (Inherited from JobEventData)
+
+    Returns
+    -------
+    JobPause
+        An instance of the `JobPause` class representing the pause event.
+    """
+    # This class does not define additional attributes or methods.
+    # It serves as a specialized event type for job pausing.