orionis 0.513.0__tar.gz → 0.514.0__tar.gz

{orionis-0.513.0/orionis.egg-info → orionis-0.514.0}/PKG-INFO

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

{orionis-0.513.0 → orionis-0.514.0}/orionis/console/base/scheduler_event_listener.py

@@ -1,4 +1,3 @@
-from orionis.console.contracts.schedule import ISchedule
 from orionis.console.contracts.schedule_event_listener import IScheduleEventListener
 from orionis.console.entities.job_error import JobError
 from orionis.console.entities.job_executed import JobExecuted
@@ -18,7 +17,7 @@ class BaseScheduleEventListener(IScheduleEventListener):
     specific behavior for each event type.
     """
 
-    async def before(self, event: JobSubmitted, schedule: ISchedule):
+    async def before(self, event: JobSubmitted, schedule):
         """
         Called before processing a job submission event.
 
@@ -31,7 +30,7 @@ class BaseScheduleEventListener(IScheduleEventListener):
         """
         pass
 
-    async def after(self, event: JobExecuted, schedule: ISchedule):
+    async def after(self, event: JobExecuted, schedule):
         """
         Called after processing a job execution event.
 
@@ -44,7 +43,7 @@ class BaseScheduleEventListener(IScheduleEventListener):
         """
         pass
 
-    async def onSuccess(self, event: JobExecuted, schedule: ISchedule):
+    async def onSuccess(self, event: JobExecuted, schedule):
         """
         Called when a job is successfully executed.
 
@@ -57,7 +56,7 @@ class BaseScheduleEventListener(IScheduleEventListener):
         """
         pass
 
-    async def onFailure(self, event: JobError, schedule: ISchedule):
+    async def onFailure(self, event: JobError, schedule):
         """
         Called when a job execution fails.
 
@@ -70,7 +69,7 @@ class BaseScheduleEventListener(IScheduleEventListener):
         """
         pass
 
-    async def onMissed(self, event: JobMissed, schedule: ISchedule):
+    async def onMissed(self, event: JobMissed, schedule):
         """
         Called when a job execution is missed.
 
@@ -83,7 +82,7 @@ class BaseScheduleEventListener(IScheduleEventListener):
         """
         pass
 
-    async def onMaxInstances(self, event: JobMaxInstances, schedule: ISchedule):
+    async def onMaxInstances(self, event: JobMaxInstances, schedule):
         """
         Called when a job exceeds the maximum allowed instances.
 
@@ -96,7 +95,7 @@ class BaseScheduleEventListener(IScheduleEventListener):
         """
         pass
 
-    async def onPaused(self, event: JobPause, schedule: ISchedule):
+    async def onPaused(self, event: JobPause, schedule):
         """
         Called when the scheduler is paused.
 
@@ -109,7 +108,7 @@ class BaseScheduleEventListener(IScheduleEventListener):
         """
         pass
 
-    async def onResumed(self, event: JobResume, schedule: ISchedule):
+    async def onResumed(self, event: JobResume, schedule):
         """
         Called when the scheduler is resumed.
 
@@ -122,7 +121,7 @@ class BaseScheduleEventListener(IScheduleEventListener):
         """
         pass
 
-    async def onRemoved(self, event: JobRemoved, schedule: ISchedule):
+    async def onRemoved(self, event: JobRemoved, schedule):
         """
         Called when a job is removed from the scheduler.
 

{orionis-0.513.0 → orionis-0.514.0}/orionis/console/commands/scheduler_list.py

@@ -38,7 +38,7 @@ class ScheduleListCommand(BaseCommand):
     # Command description
     description: str = "Executes the scheduled tasks defined in the application."
 
-    def handle(self, app: IApplication, console: Console) -> bool:
+    async def handle(self, app: IApplication, console: Console) -> bool:
         """
         Displays a table of scheduled jobs defined in the application.
 
@@ -64,13 +64,13 @@ class ScheduleListCommand(BaseCommand):
         try:
 
             # Retrieve the Scheduler instance from the application
-            Scheduler = app.getScheduler()
+            scheduler = app.getScheduler()
 
             # Create an instance of the ISchedule service
             schedule_service: ISchedule = app.make(ISchedule)
 
             # Register scheduled tasks using the Scheduler's tasks method
-            Scheduler.tasks(schedule_service)
+            await scheduler.tasks(schedule_service)
 
             # Retrieve the list of scheduled jobs/events
             list_tasks = schedule_service.events()

{orionis-0.513.0 → orionis-0.514.0}/orionis/console/commands/scheduler_work.py

@@ -1,14 +1,11 @@
 from datetime import datetime
 from rich.console import Console
 from rich.panel import Panel
-from rich.text import Text
 from orionis.console.base.command import BaseCommand
 from orionis.console.contracts.schedule import ISchedule
 from orionis.console.enums.listener import ListeningEvent
 from orionis.console.exceptions import CLIOrionisRuntimeError
-from orionis.container.exceptions.exception import OrionisContainerException
 from orionis.foundation.contracts.application import IApplication
-from orionis.foundation.exceptions.runtime import OrionisRuntimeError
 
 class ScheduleWorkCommand(BaseCommand):
     """
@@ -94,33 +91,39 @@ class ScheduleWorkCommand(BaseCommand):
                 return True
 
             # If there are scheduled jobs and the scheduler has an onStarted method
-            if hasattr(scheduler, "onStarted"):
-                schedule_service._setListener(ListeningEvent.SCHEDULER_STARTED.value, scheduler.onStarted)
+            if hasattr(scheduler, "onStarted") and callable(scheduler.onStarted):
+                schedule_service.setListener(ListeningEvent.SCHEDULER_STARTED, scheduler.onStarted)
 
             # If the scheduler has an onPaused method
-            if hasattr(scheduler, "onPaused"):
-                schedule_service._setListener(ListeningEvent.SCHEDULER_PAUSED.value, scheduler.onPaused)
+            if hasattr(scheduler, "onPaused") and callable(scheduler.onPaused):
+                schedule_service.setListener(ListeningEvent.SCHEDULER_PAUSED, scheduler.onPaused)
 
             # If the scheduler has an onResumed method
-            if hasattr(scheduler, "onResumed"):
-                schedule_service._setListener(ListeningEvent.SCHEDULER_RESUMED.value, scheduler.onResumed)
+            if hasattr(scheduler, "onResumed") and callable(scheduler.onResumed):
+                schedule_service.setListener(ListeningEvent.SCHEDULER_RESUMED, scheduler.onResumed)
 
             # If the scheduler has an onFinalized method
-            if hasattr(scheduler, "onFinalized"):
-                schedule_service._setListener(ListeningEvent.SCHEDULER_SHUTDOWN.value, scheduler.onFinalized)
+            if hasattr(scheduler, "onFinalized") and callable(scheduler.onFinalized):
+                schedule_service.setListener(ListeningEvent.SCHEDULER_SHUTDOWN, scheduler.onFinalized)
 
             # If the scheduler has an onError method
-            if hasattr(scheduler, "onError"):
-                schedule_service._setListener(ListeningEvent.SCHEDULER_ERROR.value, scheduler.onError)
+            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 isinstance(scheduler.PAUSE_AT, datetime):
+            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, "RESUME_AT") and isinstance(scheduler.RESUME_AT, datetime):
+            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)
 
-            if hasattr(scheduler, "FINALIZE_AT") and isinstance(scheduler.FINALIZE_AT, datetime):
+            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)
 
             # Start the scheduler worker asynchronously

orionis-0.514.0/orionis/console/contracts/schedule.py

@@ -0,0 +1,327 @@
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import List, Optional, Union
+from orionis.console.contracts.schedule_event_listener import IScheduleEventListener
+from orionis.console.enums.listener import ListeningEvent
+from orionis.console.tasks.event import Event
+
+class ISchedule(ABC):
+
+    @abstractmethod
+    def command(
+        self,
+        signature: str,
+        args: Optional[List[str]] = None
+    ) -> 'Event':
+        """
+        Prepare an Event instance for a given command signature and its arguments.
+
+        This method validates the provided command signature and arguments, ensuring
+        that the command exists among the registered commands and that the arguments
+        are in the correct format. If validation passes, it creates and returns an
+        Event object representing the scheduled command, including its signature,
+        arguments, and description.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature identifying the command to be scheduled. Must be a non-empty string.
+        args : Optional[List[str]], optional
+            A list of string arguments to be passed to the command. Defaults to None.
+
+        Returns
+        -------
+        Event
+            An Event instance containing the command signature, arguments, and its description.
+
+        Raises
+        ------
+        ValueError
+            If the command signature is not a non-empty string, if the arguments are not a list
+            of strings or None, or if the command does not exist among the registered commands.
+        """
+        pass
+
+    @abstractmethod
+    def setListener(
+        self,
+        event: Union[str, ListeningEvent],
+        listener: Union[IScheduleEventListener, callable]
+    ) -> None:
+        """
+        Register a listener callback for a specific scheduler event.
+
+        This method registers a listener function or an instance of IScheduleEventListener
+        to be invoked when the specified scheduler event occurs. The event can be a global
+        event name (e.g., 'scheduler_started') or a specific job ID. The listener must be
+        callable and should accept the event object as a parameter.
+
+        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 : IScheduleEventListener or callable
+            A callable function or an instance of IScheduleEventListener that will be invoked
+            when the specified event occurs. The listener 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
+            or an instance of IScheduleEventListener.
+        """
+        pass
+
+    @abstractmethod
+    def pauseEverythingAt(
+        self,
+        at: datetime
+    ) -> None:
+        """
+        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.
+
+        Parameters
+        ----------
+        at : datetime
+            The datetime at which the scheduler should be paused. Must be a valid
+            datetime object.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It schedules a job to pause the
+            scheduler at the specified datetime.
+
+        Raises
+        ------
+        ValueError
+            If the 'at' parameter is not a valid datetime object.
+        """
+        pass
+
+    @abstractmethod
+    def resumeEverythingAt(
+        self,
+        at: datetime
+    ) -> None:
+        """
+        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.
+
+        Parameters
+        ----------
+        at : datetime
+            The datetime at which the scheduler should be resumed. Must be a valid
+            datetime object.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It schedules a job to resume the
+            scheduler at the specified datetime.
+
+        Raises
+        ------
+        ValueError
+            If the 'at' parameter is not a valid datetime object.
+        """
+        pass
+
+    @abstractmethod
+    def shutdownEverythingAt(
+        self,
+        at: datetime
+    ) -> 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.
+
+        Parameters
+        ----------
+        at : datetime
+            The datetime at which the scheduler should be shut down. Must be a valid
+            datetime object.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It schedules a job to shut down the
+            scheduler at the specified datetime.
+
+        Raises
+        ------
+        ValueError
+            If the 'at' parameter is not a valid datetime object.
+        """
+        pass
+
+    @abstractmethod
+    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.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It starts the AsyncIO scheduler and keeps it running.
+        """
+        pass
+
+    @abstractmethod
+    async def shutdown(self, wait=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.
+
+        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.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs the shutdown operation for the AsyncIO scheduler.
+
+        Raises
+        ------
+        ValueError
+            If the 'wait' parameter is not a boolean value.
+        CLIOrionisRuntimeError
+            If an error occurs during the shutdown process.
+        """
+        pass
+
+    @abstractmethod
+    def pause(self, signature: str) -> bool:
+        """
+        Pause a scheduled job in the AsyncIO scheduler.
+
+        This method pauses a job in the AsyncIOScheduler identified by its unique signature.
+        It validates the provided signature to ensure it is a non-empty string and attempts
+        to pause the job. If the operation is successful, it logs the action and returns True.
+        If the job cannot be paused (e.g., it does not exist), the method returns False.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature (ID) of the job to pause. This must be a non-empty string.
+
+        Returns
+        -------
+        bool
+            True if the job was successfully paused.
+            False if the job does not exist or an error occurred.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the `signature` parameter is not a non-empty string.
+        """
+        pass
+
+    @abstractmethod
+    def resume(self, signature: str) -> bool:
+        """
+        Resume a paused job in the AsyncIO scheduler.
+
+        This method attempts to resume a job that was previously paused in the AsyncIOScheduler.
+        It validates the provided job signature, ensures it is a non-empty string, and then
+        resumes the job if it exists and is currently paused. If the operation is successful,
+        it logs the action and returns True. If the job cannot be resumed (e.g., it does not exist),
+        the method returns False.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature (ID) of the job to resume. This must be a non-empty string.
+
+        Returns
+        -------
+        bool
+            True if the job was successfully resumed, False if the job does not exist or an error occurred.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the `signature` parameter is not a non-empty string.
+        """
+        pass
+
+    @abstractmethod
+    def remove(self, signature: str) -> bool:
+        """
+        Remove a scheduled job from the AsyncIO scheduler.
+
+        This method removes a job from the AsyncIOScheduler using its unique signature (ID).
+        It validates the provided signature to ensure it is a non-empty string, attempts to
+        remove the job from the scheduler, and updates the internal jobs list accordingly.
+        If the operation is successful, it logs the action and returns True. If the job
+        cannot be removed (e.g., it does not exist), the method returns False.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature (ID) of the job to remove. This must be a non-empty string.
+
+        Returns
+        -------
+        bool
+            True if the job was successfully removed from the scheduler.
+            False if the job does not exist or an error occurred.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the `signature` parameter is not a non-empty string.
+        """
+        pass
+
+    @abstractmethod
+    def events(self) -> list:
+        """
+        Retrieve all scheduled jobs currently managed by the Scheduler.
+
+        This method loads and returns a list of dictionaries, each representing a scheduled job
+        managed by this Scheduler instance. Each dictionary contains details such as the command
+        signature, arguments, purpose, random delay, start and end dates, and additional job details.
+
+        Returns
+        -------
+        list of dict
+            A list where each element is a dictionary containing information about a scheduled job.
+            Each dictionary includes the following keys:
+                - 'signature': str, the command signature.
+                - 'args': list, the arguments passed to the command.
+                - 'purpose': str, the description or purpose of the job.
+                - 'random_delay': any, the random delay associated with the job (if any).
+                - 'start_date': str or None, the formatted start date and time of the job, or None if not set.
+                - '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

{orionis-0.513.0 → orionis-0.514.0}/orionis/console/contracts/schedule_event_listener.py

@@ -81,40 +81,6 @@ class IScheduleEventListener(ABC):
         # 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):
         """

{orionis-0.513.0 → orionis-0.514.0}/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-0.514.0/orionis/console/enums/event.py

@@ -0,0 +1,63 @@
+from dataclasses import dataclass, field
+from typing import List, Optional, Union
+from datetime import datetime
+from apscheduler.triggers.cron import CronTrigger
+from apscheduler.triggers.date import DateTrigger
+from apscheduler.triggers.interval import IntervalTrigger
+from orionis.console.contracts.schedule_event_listener import IScheduleEventListener
+
+@dataclass(kw_only=True)
+class Event:
+    """
+    Represents an event with scheduling and execution details.
+
+    Attributes
+    ----------
+    signature : str
+        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. Defaults to an empty list if not provided.
+    purpose : Optional[str]
+        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) to be applied before the event is triggered. Can be None.
+    start_date : Optional[datetime]
+        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. If None, the event does not have a defined end time.
+    trigger : Optional[Union[CronTrigger, DateTrigger, IntervalTrigger]]
+        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
+
+    # List of arguments for the event, defaults to empty list if not provided
+    args: Optional[List[str]] = field(default_factory=list)
+
+    # Description of the event's purpose
+    purpose: Optional[str] = None
+
+    # Optional random delay (in seconds) before the event is triggered
+    random_delay: Optional[int] = None
+
+    # Start date and time for the event
+    start_date: Optional[datetime] = None
+
+    # End date and time for the event
+    end_date: Optional[datetime] = None
+
+    # Trigger mechanism for the event (cron, date, or interval)
+    trigger: Optional[Union[CronTrigger, DateTrigger, IntervalTrigger]] = None
+
+    # Optional details about the event
+    details: Optional[str] = None
+
+    # Optional listener that implements IScheduleEventListener
+    listener: Optional[IScheduleEventListener] = None