orionis 0.483.0__tar.gz → 0.485.0__tar.gz

{orionis-0.483.0/orionis.egg-info → orionis-0.485.0}/PKG-INFO

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

orionis-0.485.0/orionis/console/base/scheduler.py

@@ -0,0 +1,56 @@
+from datetime import datetime
+from orionis.console.contracts.schedule import ISchedule
+
+class BaseScheduler:
+
+    # 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
+
+    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.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It is intended to be overridden
+            by subclasses to specify scheduled tasks.
+
+        Notes
+        -----
+        This method should be implemented in subclasses to add specific tasks
+        to the scheduler using the provided `schedule` object.
+        """
+        # This method should be overridden in subclasses to define scheduled tasks.
+        pass
+
+    def onStarted(self):
+        # Called when the scheduler is started.
+        pass
+
+    def onPaused(self):
+        # Called when the scheduler is paused.
+        pass
+
+    def onResumed(self):
+        # Called when the scheduler is resumed.
+        pass
+
+    def onFinalized(self):
+        # Called when the scheduler is finalized.
+        pass
+
+    def onError(self, error: Exception):
+        # Called when an error occurs in the scheduler.
+        pass

{orionis-0.483.0 → orionis-0.485.0}/orionis/console/commands/scheduler_list.py

@@ -11,20 +11,23 @@ from orionis.foundation.contracts.application import IApplication
 
 class ScheduleListCommand(BaseCommand):
     """
-    Command class to display usage information for the Orionis CLI.
+    Command class to display a list of scheduled tasks defined in the Orionis application.
 
     Methods
     -------
-    handle(orionis: IApplication, console: Console) -> bool
-        Displays a table of scheduled tasks defined in the application.
-        Imports the scheduler module, retrieves scheduled jobs, and prints them
-        in a formatted table using the rich library.
+    handle(app: IApplication, console: Console) -> bool
+        Lists all scheduled jobs configured in the application by retrieving them from the
+        ISchedule service and displaying them in a formatted table using the rich library.
+
+    Attributes
+    ----------
+    timestamps : bool
+        Indicates whether timestamps will be shown in the command output.
+    signature : str
+        Command signature for invocation.
+    description : str
+        Description of the command.
 
-    Returns
-    -------
-    bool
-        Returns True if the scheduled jobs are listed successfully or if no jobs are found.
-        Raises CLIOrionisRuntimeError if an error occurs during execution.
     """
 
     # Indicates whether timestamps will be shown in the command output
@@ -36,18 +39,19 @@ class ScheduleListCommand(BaseCommand):
     # Command description
     description: str = "Executes the scheduled tasks defined in the application."
 
-    def handle(self, orionis: IApplication, console: Console) -> bool:
+    def handle(self, app: IApplication, console: Console) -> bool:
         """
         Displays a table of scheduled jobs defined in the application.
 
-        This method dynamically imports the scheduler module, retrieves the list of
-        scheduled jobs using the ISchedule service, and prints the jobs in a formatted
-        table. If no jobs are found, a message is displayed. Handles and reports errors
-        encountered during the process.
+        This method dynamically retrieves the scheduler instance and the ISchedule service
+        from the application, registers scheduled tasks, and fetches the list of scheduled
+        jobs. It then prints the jobs in a formatted table using the rich library. If no
+        jobs are found, a message is displayed. Any errors encountered during the process
+        are reported as CLIOrionisRuntimeError.
 
         Parameters
         ----------
-        orionis : IApplication
+        app : IApplication
             The application instance providing configuration and service resolution.
         console : Console
             The rich Console instance used for output.
@@ -58,45 +62,19 @@ class ScheduleListCommand(BaseCommand):
             Returns True if the scheduled jobs are listed successfully or if no jobs are found.
             Raises CLIOrionisRuntimeError if an error occurs during execution.
         """
-
         try:
 
-            # Get the absolute path of the scheduler from the application configuration
-            scheduler_path = orionis.path('console_scheduler')
-
-            # Get the base path from the current working directory
-            base_path = Path(os.getcwd()).resolve()
-            scheduler_path = Path(scheduler_path).resolve()
-            rel_path = scheduler_path.relative_to(base_path)
-
-            # Convert the path to a module name (replace separators with dots, remove .py)
-            module_name = ".".join(rel_path.with_suffix('').parts)
-
-            # Dynamically import the scheduler module
-            scheduler_module = importlib.import_module(module_name)
+            # Retrieve the Scheduler instance from the application
+            Scheduler = app.getScheduler()
 
-            # Retrieve the Scheduler class from the imported module
-            Scheduler = getattr(scheduler_module, "Scheduler", None)
+            # Create an instance of the ISchedule service
+            schedule_service: ISchedule = app.make(ISchedule)
 
-            # Raise an error if the Scheduler class is not found
-            if Scheduler is None:
-                raise CLIOrionisRuntimeError(f"Scheduler class not found in module {module_name}")
-
-            # Retrieve the 'tasks' method from the Scheduler class
-            task_method = getattr(Scheduler, "tasks", None)
-
-            # Raise an error if the 'tasks' method is not found
-            if task_method is None:
-                raise CLIOrionisRuntimeError(f"Method 'tasks' not found in Scheduler class in module {module_name}")
-
-            # Create an instance of ISchedule using the application container
-            schedule_serice: ISchedule = orionis.make(ISchedule)
-
-            # Initialize the scheduled tasks by calling the 'tasks' method
-            task_method(schedule_serice)
+            # Register scheduled tasks using the Scheduler's tasks method
+            Scheduler.tasks(schedule_service)
 
             # Retrieve the list of scheduled jobs/events
-            list_tasks = schedule_serice.events()
+            list_tasks = schedule_service.events()
 
             # Display a message if no scheduled jobs are found
             if not list_tasks:
@@ -134,6 +112,7 @@ class ScheduleListCommand(BaseCommand):
             return True
 
         except Exception as exc:
-
             # Catch any unexpected exceptions and raise as a CLIOrionisRuntimeError
-            raise CLIOrionisRuntimeError(f"An unexpected error occurred while clearing the cache: {exc}")
+            raise CLIOrionisRuntimeError(
+                f"An unexpected error occurred while listing the scheduled jobs: {exc}"
+            )

{orionis-0.483.0 → orionis-0.485.0}/orionis/console/commands/scheduler_work.py

@@ -1,7 +1,4 @@
-import importlib
-import os
 from datetime import datetime
-from pathlib import Path
 from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
@@ -47,18 +44,17 @@ class ScheduleWorkCommand(BaseCommand):
     # Command description
     description: str = "Executes the scheduled tasks defined in the application."
 
-    async def handle(self, orionis: IApplication, console: Console) -> bool:
+    async def handle(self, app: IApplication, console: Console) -> bool:
         """
         Executes the scheduled tasks defined in the application's scheduler.
 
-        This method dynamically loads the scheduler module specified in the application's configuration,
-        retrieves the `Scheduler` class and its `tasks` method, registers the scheduled tasks with the
-        ISchedule service, and starts the scheduler worker. It provides user feedback via the console and
-        handles errors by raising CLIOrionisRuntimeError exceptions.
+        This method retrieves the Scheduler instance from the application, registers scheduled tasks
+        with the ISchedule service, and starts the scheduler worker asynchronously. It provides user
+        feedback via the console and handles errors by raising CLIOrionisRuntimeError exceptions.
 
         Parameters
         ----------
-        orionis : IApplication
+        app : IApplication
             The application instance providing configuration and service resolution.
         console : Console
             The Rich console instance used for displaying output to the user.
@@ -66,8 +62,7 @@ class ScheduleWorkCommand(BaseCommand):
         Returns
         -------
         bool
-            Returns True if the scheduler worker starts successfully. If an error occurs during the process,
-            a CLIOrionisRuntimeError is raised.
+            True if the scheduler worker starts successfully.
 
         Raises
         ------
@@ -75,37 +70,15 @@ class ScheduleWorkCommand(BaseCommand):
             If the scheduler module, class, or tasks method cannot be found, or if any unexpected error occurs.
         """
         try:
-            # Get the absolute path to the scheduler module from the application configuration
-            scheduler_path = orionis.path('console_scheduler')
 
-            # Resolve the base path (current working directory)
-            base_path = Path(os.getcwd()).resolve()
-            scheduler_path = Path(scheduler_path).resolve()
-
-            # Compute the relative path from the base path to the scheduler module
-            rel_path = scheduler_path.relative_to(base_path)
-
-            # Convert the relative path to a Python module name (dot notation, no .py extension)
-            module_name = ".".join(rel_path.with_suffix('').parts)
-
-            # Dynamically import the scheduler module
-            scheduler_module = importlib.import_module(module_name)
-
-            # Retrieve the Scheduler class from the imported module
-            Scheduler = getattr(scheduler_module, "Scheduler", None)
-            if Scheduler is None:
-                raise CLIOrionisRuntimeError(f"Scheduler class not found in module {module_name}")
-
-            # Retrieve the 'tasks' method from the Scheduler class
-            task_method = getattr(Scheduler, "tasks", None)
-            if task_method is None:
-                raise CLIOrionisRuntimeError(f"Method 'tasks' not found in Scheduler class in module {module_name}")
+            # Retrieve the Scheduler instance from the application
+            Scheduler = app.getScheduler()
 
             # Create an instance of the ISchedule service
-            schedule_serice: ISchedule = orionis.make(ISchedule)
+            schedule_serice: ISchedule = app.make(ISchedule)
 
             # Register scheduled tasks using the Scheduler's tasks method
-            task_method(schedule_serice)
+            Scheduler.tasks(schedule_serice)
 
             # Display a start message for the scheduler worker
             console.line()
@@ -130,4 +103,6 @@ class ScheduleWorkCommand(BaseCommand):
 
         except Exception as exc:
             # Raise any unexpected exceptions as CLIOrionisRuntimeError
-            raise CLIOrionisRuntimeError(f"An unexpected error occurred while clearing the cache: {exc}")
+            raise CLIOrionisRuntimeError(
+                f"An unexpected error occurred while starting the scheduler worker: {exc}"
+            )

{orionis-0.483.0 → orionis-0.485.0}/orionis/console/commands/test.py

@@ -1,4 +1,3 @@
-from orionis.app import Orionis
 from orionis.console.base.command import BaseCommand
 from orionis.console.exceptions import CLIOrionisRuntimeError
 from orionis.foundation.contracts.application import IApplication

orionis-0.485.0/orionis/console/contracts/event_listener.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+
+class IEventListener(ABC):
+
+    @abstractmethod
+    def before(self, event):
+        pass
+
+    @abstractmethod
+    def after(self, event):
+        pass
+
+    @abstractmethod
+    def onSuccess(self, event):
+        pass
+
+    @abstractmethod
+    def onFailure(self, event):
+        pass
+
+    @abstractmethod
+    def onMissed(self, event):
+        pass
+
+    @abstractmethod
+    def onMaxInstances(self, event):
+        pass

{orionis-0.483.0 → orionis-0.485.0}/orionis/console/core/reactor.py

@@ -3,7 +3,6 @@ import os
 import re
 from pathlib import Path
 from typing import Any, List, Optional
-from orionis.app import Orionis
 from orionis.console.args.argument import CLIArgument
 from orionis.console.base.command import BaseCommand
 from orionis.console.base.contracts.command import IBaseCommand
@@ -51,7 +50,7 @@ class Reactor(IReactor):
         -----
         - Command discovery is performed automatically during initialization
         - The current working directory is used as the project root for module resolution
-        - Commands are loaded from the path specified by app.path('console_commands')
+        - Commands are loaded from the path specified by app.path('commands')
         - The internal command registry is initialized as an empty dictionary before loading
         """
 
@@ -59,13 +58,13 @@ class Reactor(IReactor):
         self.__app = app
 
         # Set the project root directory to current working directory for module path resolution
-        self.__root: str = str(Path.cwd())
+        self.__root = self.__app.path('root') or Path().cwd()
 
         # Initialize the internal command registry as an empty dictionary
         self.__commands: dict[str, Command] = {}
 
         # Automatically discover and load command classes from the console commands directory
-        self.__loadCommands(str(self.__app.path('console_commands')), self.__root)
+        self.__loadCommands(str(self.__app.path('commands')), self.__root)
 
         # Load core command classes provided by the Orionis framework
         self.__loadCoreCommands()

orionis-0.485.0/orionis/console/entities/listeners.py

@@ -0,0 +1,241 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+# ==============================================================
+# Base Events
+# ==============================================================
+
+@dataclass
+class SchedulerEventData:
+    """
+    Base class for scheduler-related events.
+
+    Attributes
+    ----------
+    code : int
+        The numeric event code indicating the event type.
+    """
+    code: int
+
+
+@dataclass
+class JobEventData(SchedulerEventData):
+    """
+    Base class for job-related events.
+
+    Attributes
+    ----------
+    code : int
+        The numeric event code indicating the event type.
+    job_id : str
+        The identifier of the job.
+    jobstore : str
+        The name of the job store where the job is located.
+    """
+    job_id: str
+    jobstore: str
+
+
+# ==============================================================
+# Scheduler Lifecycle Events
+# ==============================================================
+
+@dataclass
+class SchedulerStarted(SchedulerEventData):
+    """
+    Event triggered when the scheduler starts running.
+    """
+
+
+@dataclass
+class SchedulerShutdown(SchedulerEventData):
+    """
+    Event triggered when the scheduler shuts down.
+    """
+
+
+@dataclass
+class SchedulerPaused(SchedulerEventData):
+    """
+    Event triggered when the scheduler is paused.
+    """
+
+
+@dataclass
+class SchedulerResumed(SchedulerEventData):
+    """
+    Event triggered when the scheduler is resumed.
+    """
+
+
+# ==============================================================
+# Executor and JobStore Events
+# ==============================================================
+
+@dataclass
+class ExecutorAdded(SchedulerEventData):
+    """
+    Event triggered when an executor is added.
+
+    Attributes
+    ----------
+    alias : str
+        The alias of the added executor.
+    """
+    alias: str
+
+
+@dataclass
+class ExecutorRemoved(SchedulerEventData):
+    """
+    Event triggered when an executor is removed.
+
+    Attributes
+    ----------
+    alias : str
+        The alias of the removed executor.
+    """
+    alias: str
+
+
+@dataclass
+class JobstoreAdded(SchedulerEventData):
+    """
+    Event triggered when a job store is added.
+
+    Attributes
+    ----------
+    alias : str
+        The alias of the added job store.
+    """
+    alias: str
+
+
+@dataclass
+class JobstoreRemoved(SchedulerEventData):
+    """
+    Event triggered when a job store is removed.
+
+    Attributes
+    ----------
+    alias : str
+        The alias of the removed job store.
+    """
+    alias: str
+
+
+@dataclass
+class AllJobsRemoved(SchedulerEventData):
+    """
+    Event triggered when all jobs are removed from a job store.
+
+    Attributes
+    ----------
+    jobstore : str
+        The alias of the job store from which jobs were removed.
+    """
+    jobstore: str
+
+
+# ==============================================================
+# Job Management Events
+# ==============================================================
+
+@dataclass
+class JobAdded(JobEventData):
+    """
+    Event triggered when a job is added to a job store.
+    """
+
+
+@dataclass
+class JobRemoved(JobEventData):
+    """
+    Event triggered when a job is removed from a job store.
+    """
+
+
+@dataclass
+class JobModified(JobEventData):
+    """
+    Event triggered when a job is modified in a job store.
+    """
+
+
+@dataclass
+class JobSubmitted(JobEventData):
+    """
+    Event triggered when a job is submitted to an executor.
+
+    Attributes
+    ----------
+    run_time : datetime
+        The datetime when the job was scheduled to run.
+    """
+    run_time: datetime
+
+
+@dataclass
+class JobMaxInstances(JobEventData):
+    """
+    Event triggered when a job exceeds its maximum allowed instances.
+
+    Attributes
+    ----------
+    run_time : datetime
+        The datetime when the job was scheduled to run.
+    """
+    run_time: datetime
+
+
+# ==============================================================
+# Job Execution Events
+# ==============================================================
+
+@dataclass
+class JobExecuted(JobEventData):
+    """
+    Event triggered when a job finishes successfully.
+
+    Attributes
+    ----------
+    scheduled_run_time : datetime
+        The datetime when the job was scheduled to run.
+    retval : Any
+        The return value of the job function.
+    """
+    scheduled_run_time: datetime
+    retval: Any
+
+
+@dataclass
+class JobError(JobEventData):
+    """
+    Event triggered when a job raises an exception during execution.
+
+    Attributes
+    ----------
+    scheduled_run_time : datetime
+        The datetime when the job was scheduled to run.
+    exception : Exception
+        The exception raised by the job.
+    traceback : str
+        The traceback of the exception.
+    """
+    scheduled_run_time: datetime
+    exception: Exception
+    traceback: str
+
+
+@dataclass
+class JobMissed(JobEventData):
+    """
+    Event triggered when a job run is missed due to scheduler constraints.
+
+    Attributes
+    ----------
+    scheduled_run_time : datetime
+        The datetime when the job was originally scheduled to run.
+    """
+    scheduled_run_time: datetime

{orionis-0.483.0 → orionis-0.485.0}/orionis/console/tasks/event.py

@@ -5,6 +5,7 @@ from apscheduler.triggers.cron import CronTrigger
 from apscheduler.triggers.date import DateTrigger
 from apscheduler.triggers.interval import IntervalTrigger
 from orionis.console.contracts.event import IEvent
+from orionis.console.contracts.event_listener import IEventListener
 from orionis.console.enums.event import Event as EventEntity
 from orionis.console.exceptions import CLIOrionisValueError
 
@@ -249,6 +250,12 @@ class Event(IEvent):
         # Return self to support method chaining
         return self
 
+    def listener(
+        self,
+        listener: 'IEventListener'
+    ) -> 'Event':
+        return self
+
     def onceAt(
         self,
         date: datetime

{orionis-0.483.0 → orionis-0.485.0}/orionis/console/tasks/schedule.py

@@ -2,7 +2,7 @@ import asyncio
 import logging
 from typing import Dict, List, Optional
 import pytz
-from apscheduler.events import EVENT_JOB_MISSED, EVENT_JOB_ERROR
+from apscheduler.events import EVENT_JOB_MISSED, EVENT_JOB_ERROR, EVENT_ALL, EVENT_SCHEDULER_STARTED
 from apscheduler.schedulers.asyncio import AsyncIOScheduler as APSAsyncIOScheduler
 from orionis.console.contracts.reactor import IReactor
 from orionis.console.contracts.schedule import ISchedule
@@ -80,7 +80,8 @@ class Scheduler(ISchedule):
         self.__jobs: List[dict] = []
 
         # Add a listener to the scheduler to capture job events such as missed jobs or errors.
-        self.__scheduler.add_listener(self.__listener, EVENT_JOB_MISSED | EVENT_JOB_ERROR)
+        if self.__app.config('app.debug', False):
+            self.__scheduler.add_listener(self.__listener, EVENT_ALL)
 
         # Log the initialization of the Scheduler.
         self.__logger.info("Orionis scheduler initialized.")
@@ -313,6 +314,26 @@ class Scheduler(ISchedule):
         # Return the Event instance for further scheduling configuration
         return self.__events[signature]
 
+    def addListenerOnSchedulerStarted(
+        self,
+        listener: callable
+    ) -> None:
+        """
+        Add a listener for the scheduler started event.
+
+        This method allows you to register a callback function that will be called
+        when the scheduler starts. The callback should accept a single argument, which
+        is the event object containing details about the scheduler start event.
+
+        Parameters
+        ----------
+        listener : callable
+            A function that will be called when the scheduler starts.
+            It should accept one parameter, which is the event object.
+        """
+        # Register the listener for the scheduler started event
+        self.__scheduler.add_listener(listener, EVENT_SCHEDULER_STARTED)
+
     async def start(self) -> None:
         """
         Start the AsyncIO scheduler instance and keep it running.