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

orionis/console/base/command.py

@@ -2,7 +2,7 @@ from typing import Any, Dict, List
 from orionis.console.args.argument import CLIArgument
 from orionis.console.dynamic.progress_bar import ProgressBar
 from orionis.console.output.console import Console
-from orionis.console.base.contracts.command import IBaseCommand
+from orionis.console.contracts.command import IBaseCommand
 
 class BaseCommand(Console, ProgressBar, IBaseCommand):
     """

orionis/console/base/scheduler.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from orionis.console.base.contracts.scheduler import IBaseScheduler
+from orionis.console.contracts.scheduler import IBaseScheduler
 from orionis.console.contracts.schedule import ISchedule
 
 class BaseScheduler(IBaseScheduler):

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/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/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/console/contracts/schedule.py

@@ -1,31 +1,70 @@
 from abc import ABC, abstractmethod
-from typing import List, Optional
+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 _setListener(
+    def command(
         self,
-        event: str,
-        listener: callable
+        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 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.
+        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 : 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.
+        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
         -------
@@ -35,41 +74,101 @@ class ISchedule(ABC):
         Raises
         ------
         ValueError
-            If the event name is not a non-empty string or if the listener is not callable.
+            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 command(
+    def pauseEverythingAt(
         self,
-        signature: str,
-        args: Optional[List[str]] = None
-    ) -> 'Event':
+        at: datetime
+    ) -> None:
         """
-        Prepare an Event instance for a given command signature and its arguments.
+        Schedule the scheduler to pause all operations at a specific datetime.
 
-        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.
+        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
         ----------
-        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.
+        at : datetime
+            The datetime at which the scheduler should be paused. Must be a valid
+            datetime object.
 
         Returns
         -------
-        Event
-            An Event instance containing the command signature, arguments, and its description.
+        None
+            This method does not return any value. It schedules a job to pause the
+            scheduler at the specified datetime.
 
         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.
+            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
 
@@ -94,45 +193,112 @@ class ISchedule(ABC):
         """
         Shut down the AsyncIO scheduler instance asynchronously.
 
-        This method gracefully stops the AsyncIOScheduler that handles asynchronous job execution.
-        Using async ensures proper cleanup in asyncio environments.
+        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 will wait until all currently executing jobs are completed before shutting down the scheduler.
-            If False, the scheduler will be shut down immediately without waiting for running jobs to finish. Default is True.
+            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 shuts down the AsyncIO scheduler.
+            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
-    async def remove(self, signature: str) -> bool:
+    def pause(self, signature: str) -> bool:
         """
-        Remove a scheduled job from the AsyncIO scheduler asynchronously.
+        Pause a scheduled job in the AsyncIO scheduler.
 
-        This method removes a job with the specified signature from both the internal
-        jobs dictionary and the AsyncIOScheduler instance. Using async ensures proper
-        cleanup in asyncio environments.
+        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 signature of the command/job to remove from the scheduler.
+            The unique signature (ID) of the job to pause. This must be a non-empty string.
 
         Returns
         -------
         bool
-            Returns True if the job was successfully removed, False if the job was not found.
+            True if the job was successfully paused.
+            False if the job does not exist or an error occurred.
 
         Raises
         ------
-        ValueError
-            If the signature is not a non-empty string.
+        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
 

orionis/console/contracts/schedule_event_listener.py

@@ -1,5 +1,4 @@
 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
@@ -9,9 +8,6 @@ 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.
@@ -85,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):
         """