orionis 0.478.0__py3-none-any.whl → 0.480.0__py3-none-any.whl

orionis/console/tasks/schedule.py

@@ -1,24 +1,26 @@
 import asyncio
 import logging
-from datetime import datetime
-from typing import List, Optional
+from typing import Dict, List, Optional
 import pytz
+from apscheduler.events import EVENT_JOB_MISSED, EVENT_JOB_ERROR
 from apscheduler.schedulers.asyncio import AsyncIOScheduler as APSAsyncIOScheduler
-from apscheduler.triggers.cron import CronTrigger
-from apscheduler.triggers.date import DateTrigger
-from apscheduler.triggers.interval import IntervalTrigger
-from orionis.app import Orionis
 from orionis.console.contracts.reactor import IReactor
-from orionis.console.enums.task import Task
+from orionis.console.contracts.schedule import ISchedule
 from orionis.console.exceptions import CLIOrionisRuntimeError
-from orionis.console.exceptions.cli_orionis_value_error import CLIOrionisValueError
+from orionis.console.output.contracts.console import IConsole
+from orionis.console.tasks.event import Event
+from orionis.console.tasks.exception_report import ScheduleErrorReporter
+from orionis.foundation.contracts.application import IApplication
 from orionis.services.log.contracts.log_service import ILogger
 
-class Scheduler():
+class Scheduler(ISchedule):
 
     def __init__(
         self,
-        reactor: IReactor
+        reactor: IReactor,
+        app: IApplication,
+        console: IConsole,
+        error_reporter: ScheduleErrorReporter
     ) -> None:
         """
         Initialize a new instance of the Scheduler class.
@@ -41,7 +43,13 @@ class Scheduler():
         """
 
         # Store the application instance for configuration access.
-        self.__app = Orionis()
+        self.__app = app
+
+        # Store the console instance for output operations.
+        self.__console = console
+
+        # Store the error reporter instance for handling exceptions.
+        self.__error_reporter = error_reporter
 
         # Initialize AsyncIOScheduler instance with timezone configuration.
         self.__scheduler: APSAsyncIOScheduler = APSAsyncIOScheduler(
@@ -50,8 +58,11 @@ class Scheduler():
 
         # Clear the APScheduler logger to prevent conflicts with other loggers.
         # This is necessary to avoid duplicate log messages or conflicts with other logging configurations.
-        logging.getLogger("apscheduler").handlers.clear()
-        logging.getLogger("apscheduler").propagate = False
+        for name in ["apscheduler", "apscheduler.scheduler", "apscheduler.executors.default"]:
+            logger = logging.getLogger(name)
+            logger.handlers.clear()
+            logger.propagate = False
+            logger.disabled = True
 
         # Initialize the logger from the application instance.
         self.__logger: ILogger = self.__app.make('x-orionis.services.log.log_service')
@@ -62,16 +73,57 @@ class Scheduler():
         # Retrieve and store all available commands from the reactor.
         self.__available_commands = self.__getCommands()
 
-        # Dictionary to hold all scheduled jobs and their details.
-        self.__jobs: dict = {}
+        # Initialize the jobs dictionary to keep track of scheduled jobs.
+        self.__events: Dict[str, Event] = {}
 
-        # Properties to track the current scheduling context.
-        self.__command: str = None      # The command signature to be scheduled.
-        self.__args: List[str] = None   # Arguments for the command.
-        self.__purpose: str = None      # Purpose or description of the scheduled job.
+        # Initialize the jobs list to keep track of all scheduled jobs.
+        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)
 
         # Log the initialization of the Scheduler.
-        self.__logger.info("Scheduler initialized.")
+        self.__logger.info("Orionis scheduler initialized.")
+
+    def __listener(self, event):
+        """
+        Handle job events by logging errors and missed jobs.
+
+        This method acts as a listener for job events emitted by the scheduler. It processes
+        two main types of events: job execution errors and missed job executions. When a job
+        raises an exception during execution, the method logs the error and delegates reporting
+        to the error reporter. If a job is missed (i.e., not executed at its scheduled time),
+        the method logs a warning and notifies the error reporter accordingly.
+
+        Parameters
+        ----------
+        event : apscheduler.events.JobEvent
+            The job event object containing information about the job execution, such as
+            job_id, exception, traceback, code, and scheduled_run_time.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs logging and error reporting
+            based on the event type.
+        """
+
+        # If the event contains an exception, log the error and report it
+        if event.exception:
+            self.__logger.error(f"Job {event.job_id} raised an exception: {event.exception}")
+            self.__error_reporter.reportException(
+                job_id=event.job_id,
+                exception=event.exception,
+                traceback=event.traceback
+            )
+
+        # If the event indicates a missed job, log a warning and report it
+        elif event.code == EVENT_JOB_MISSED:
+            self.__logger.warning(f"Job {event.job_id} was missed, scheduled for {event.scheduled_run_time}")
+            self.__error_reporter.reportMissed(
+                job_id=event.job_id,
+                scheduled_time=event.scheduled_run_time
+            )
 
     def __getCommands(
         self
@@ -166,56 +218,77 @@ class Scheduler():
         # Return the description if the command exists, otherwise return None
         return command_entry['description'] if command_entry else None
 
-    def __reset(
+    def __loadEvents(
         self
     ) -> None:
         """
-        Reset the internal state of the Scheduler instance.
+        Load all scheduled events from the AsyncIOScheduler into the internal jobs dictionary.
 
-        This method clears the current command, arguments, and purpose attributes, 
-        effectively resetting the scheduler's configuration to its initial state. 
-        This can be useful for preparing the scheduler for a new command or job 
-        scheduling without retaining any previous settings.
+        This method retrieves all jobs currently managed by the AsyncIOScheduler and populates
+        the internal jobs dictionary with their details, including signature, arguments, purpose,
+        type, trigger, start date, and end date.
 
         Returns
         -------
         None
-            This method does not return any value. It modifies the internal state of the Scheduler.
+            This method does not return any value. It updates the internal jobs dictionary.
         """
 
-        self.__command = None
-        self.__args = None
-        self.__purpose = None
+        # Only load events if the jobs list is empty
+        if not self.__jobs:
+
+            # Iterate through all scheduled jobs in the AsyncIOScheduler
+            for signature, event in self.__events.items():
+
+                # Convert the event to its entity representation
+                entity = event.toEntity()
+
+                # Add the job to the internal jobs list
+                self.__jobs.append(entity.toDict())
+
+                # Create a unique key for the job based on its signature
+                self.__scheduler.add_job(
+                    func= lambda command=signature, args=list(entity.args): self.__reactor.call(
+                        command,
+                        args
+                    ),
+                    trigger=entity.trigger,
+                    id=signature,
+                    name=signature,
+                    replace_existing=True
+                )
 
     def command(
         self,
         signature: str,
         args: Optional[List[str]] = None
-    ) -> 'Scheduler':
+    ) -> 'Event':
         """
-        Register a command to be scheduled with the specified signature and optional arguments.
+        Prepare an Event instance for a given command signature and its arguments.
 
-        This method validates the provided command signature and arguments, checks if the command
-        is available in the list of registered commands, and stores the command details internally
-        for scheduling. The command's description is also retrieved and stored for reference.
+        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. If not provided, an empty list is used.
+            A list of string arguments to be passed to the command. Defaults to None.
 
         Returns
         -------
-        Scheduler
-            Returns the current instance of the Scheduler to allow method chaining.
+        Event
+            An Event instance containing the command signature, arguments, and its description.
 
         Raises
         ------
         ValueError
-            If the signature is not a non-empty string, if the arguments are not a list or None,
-            or if the command signature is not available among registered commands.
+            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.
         """
 
         # Validate that the command signature is a non-empty string
@@ -230,215 +303,15 @@ class Scheduler():
         if not self.__isAvailable(signature):
             raise ValueError(f"The command '{signature}' is not available or does not exist.")
 
-        # Store the command signature
-        self.__command = signature
-
-        # If purpose is not already set, retrieve and set the command's description
-        if self.__purpose is None:
-            self.__purpose = self.__getDescription(signature)
-
-        # Store the provided arguments or default to an empty list
-        self.__args = args if args is not None else []
-
-        # Return self to support method chaining
-        return self
-
-    def purpose(
-        self,
-        purpose: str
-    ) -> 'Scheduler':
-        """
-        Set the purpose or description for the scheduled command.
-
-        This method assigns a human-readable purpose or description to the command
-        that is being scheduled. The purpose must be a non-empty string. This can
-        be useful for documentation, logging, or displaying information about the
-        scheduled job.
-
-        Parameters
-        ----------
-        purpose : str
-            The purpose or description to associate with the scheduled command.
-            Must be a non-empty string.
-
-        Returns
-        -------
-        Scheduler
-            Returns the current instance of the Scheduler to allow method chaining.
-
-        Raises
-        ------
-        ValueError
-            If the provided purpose is not a non-empty string.
-        """
-
-        # Validate that the purpose is a non-empty string
-        if not isinstance(purpose, str) or not purpose.strip():
-            raise ValueError("The purpose must be a non-empty string.")
-
-        # Set the internal purpose attribute
-        self.__purpose = purpose
-
-        # Return self to support method chaining
-        return self
-
-    def onceAt(
-        self,
-        date: datetime
-    ) -> bool:
-        """
-        Schedule a command to run once at a specific date and time.
-
-        This method schedules the currently registered command to execute exactly once at the
-        specified datetime using the AsyncIOScheduler. The job is registered internally and 
-        added to the scheduler instance.
-
-        Parameters
-        ----------
-        date : datetime.datetime
-            The date and time at which the command should be executed. Must be a valid `datetime` instance.
-
-        Returns
-        -------
-        bool
-            Returns True if the job was successfully scheduled.
-
-        Raises
-        ------
-        CLIOrionisRuntimeError
-            If the provided date is not a `datetime` instance or if there is an error while scheduling the job.
-        """
-
-        try:
-
-            # Ensure the provided date is a valid datetime instance.
-            if not isinstance(date, datetime):
-                raise CLIOrionisRuntimeError(
-                    "The date must be an instance of datetime."
-                )
-
-            # Register the job details internally.
-            self.__jobs[self.__command] = Task(
-                signature=self.__command,
-                args=self.__args,
-                purpose=self.__purpose,
-                trigger='once_at',
-                details=f"Date: {date.strftime('%Y-%m-%d %H:%M:%S')}, Timezone: {str(date.tzinfo) if date.tzinfo else 'UTC'}"
-            )
-
-            # Add the job to the scheduler.
-            self.__scheduler.add_job(
-                func= lambda command=self.__command, args=list(self.__args): self.__reactor.call(
-                    command,
-                    args
-                ),
-                trigger=DateTrigger(
-                    run_date=date
-                ),
-                id=self.__command,
-                name=self.__command,
-                replace_existing=True
-            )
-
-            # Log the scheduling of the command.
-            self.__logger.info(
-                f"Scheduled command '{self.__command}' to run once at {date.strftime('%Y-%m-%d %H:%M:%S')}"
-            )
-
-            # Reset the internal state for future scheduling.
-            self.__reset()
-
-            # Return True to indicate successful scheduling.
-            return True
-
-        except Exception as e:
-
-            # Reraise known CLIOrionisRuntimeError exceptions.
-            if isinstance(e, CLIOrionisRuntimeError):
-                raise e
-
-            # Wrap and raise any other exceptions as CLIOrionisRuntimeError.
-            raise CLIOrionisRuntimeError(f"Error scheduling the job: {str(e)}")
-
-    def everySeconds(
-        self,
-        seconds: int,
-        start_date: Optional[datetime] = None,
-        end_date: Optional[datetime] = None
-    ) -> 'Scheduler':
-        """
-        Schedule a command to run at regular intervals in seconds.
-
-        This method sets the interval for the currently registered command to execute
-        every specified number of seconds. The job is registered internally and added
-        to the scheduler instance.
-
-        Parameters
-        ----------
-        seconds : int
-            The interval in seconds at which the command should be executed. Must be a positive integer.
-
-        Returns
-        -------
-        Scheduler
-            Returns the current instance of the Scheduler to allow method chaining.
-
-        Raises
-        ------
-        ValueError
-            If the provided seconds is not a positive integer.
-        """
-
-        try:
-
-            # Validate that the seconds parameter is a positive integer.
-            if not isinstance(seconds, int) or seconds <= 0:
-                raise CLIOrionisValueError("The interval must be a positive integer.")
-
-            # If start_date is provided, ensure it is a datetime instance.
-            if start_date is not None and not isinstance(start_date, datetime):
-                raise CLIOrionisValueError("Start date must be a datetime instance.")
-
-            # If end_date is provided, ensure it is a datetime instance.
-            if end_date is not None and not isinstance(end_date, datetime):
-                raise CLIOrionisValueError("End date must be a datetime instance.")
-
-            # Store the interval in the jobs dictionary.
-            self.__jobs[self.__command] = Task(
-                signature=self.__command,
-                args=self.__args,
-                purpose=self.__purpose,
-                trigger='every_seconds',
-                details=f"Interval: {seconds} seconds, Start Date: {start_date.strftime('%Y-%m-%d %H:%M:%S') if start_date else 'None'}, End Date: {end_date.strftime('%Y-%m-%d %H:%M:%S') if end_date else 'None'}"
-            )
-
-            # Add the job to the scheduler with an interval trigger.
-            self.__scheduler.add_job(
-                func=lambda command=self.__command, args=list(self.__args): self.__reactor.call(
-                    command,
-                    args
-                ),
-                trigger=IntervalTrigger(
-                    seconds=seconds,
-                    start_date=start_date,
-                    end_date=end_date
-                ),
-                id=self.__command,
-                name=self.__command,
-                replace_existing=True
-            )
-
-            # Return self to support method chaining.
-            return self
-
-        except Exception as e:
-
-            # Reraise known CLIOrionisValueError exceptions.
-            if isinstance(e, CLIOrionisValueError):
-                raise e
+        # Store the command and its arguments for scheduling
+        self.__events[signature] = Event(
+            signature=signature,
+            args=args or [],
+            purpose=self.__getDescription(signature)
+        )
 
-            # Wrap and raise any other exceptions as CLIOrionisRuntimeError.
-            raise CLIOrionisRuntimeError(f"Error scheduling the job: {str(e)}")
+        # Return the Event instance for further scheduling configuration
+        return self.__events[signature]
 
     async def start(self) -> None:
         """
@@ -457,6 +330,9 @@ class Scheduler():
         # Start the AsyncIOScheduler to handle asynchronous jobs.
         try:
 
+            # Load existing events into the scheduler
+            self.events()
+
             # Ensure we're in an asyncio context
             asyncio.get_running_loop()
 
@@ -467,14 +343,10 @@ class Scheduler():
 
             # Keep the event loop alive to process scheduled jobs
             try:
-
-                # Wait for the scheduler to start and keep it running
-                while True:
+                while self.__scheduler.running and self.__scheduler.get_jobs():
                     await asyncio.sleep(1)
-
-            except KeyboardInterrupt:
-
-                # Handle graceful shutdown on keyboard interrupt
+            except (KeyboardInterrupt, asyncio.CancelledError):
+                # Handle graceful shutdown on keyboard interrupt or cancellation
                 await self.shutdown()
 
         except Exception as e:
@@ -577,22 +449,46 @@ class Scheduler():
             # Job not found or other error
             return False
 
-    def jobs(self) -> dict:
+    def events(self) -> list:
         """
         Retrieve all scheduled jobs currently managed by the Scheduler.
 
-        This method returns a dictionary containing information about all jobs that have been
-        registered and scheduled through this Scheduler instance. Each entry in the dictionary
-        represents a scheduled job, where the key is the command signature and the value is a
-        dictionary with details such as the signature, arguments, purpose, type, trigger, start time,
-        and end time.
+        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
         -------
-        dict
-            A dictionary mapping command signatures to their corresponding job details. Each value
-            is a dictionary containing information about the scheduled job.
+        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.
         """
 
-        # Return the internal dictionary holding all scheduled jobs and their details.
-        return self.__jobs
+        # Ensure all events are loaded into the internal jobs list
+        self.__loadEvents()
+
+        # Initialize a list to hold details of each scheduled job
+        events: list = []
+
+        # Iterate over each job in the internal jobs list
+        for job in self.__jobs:
+            # Append a dictionary with relevant job details to the events list
+            events.append({
+                'signature': job['signature'],
+                'args': job['args'],
+                'purpose': job['purpose'],
+                'random_delay': job['random_delay'],
+                'start_date': job['start_date'].strftime('%Y-%m-%d %H:%M:%S') if job['start_date'] else None,
+                'end_date': job['end_date'].strftime('%Y-%m-%d %H:%M:%S') if job['end_date'] else None,
+                'details': job['details']
+            })
+
+        # Return the list of scheduled job details
+        return events

orionis/container/container.py

@@ -511,35 +511,46 @@ class Container(IContainer):
         registered in the container under both the abstract and the alias.
         """
 
-        # Ensure that the abstract is an abstract class
-        IsAbstractClass(abstract, f"Instance {Lifetime.SINGLETON}")
+        # Validate the enforce_decoupling parameter
+        if isinstance(enforce_decoupling, bool):
 
-        # Ensure that the instance is a valid instance
-        IsInstance(instance)
+            # Ensure that the abstract is an abstract class
+            IsAbstractClass(abstract, f"Instance {Lifetime.SINGLETON}")
 
-        # Ensure that instance is NOT a subclass of abstract
-        if enforce_decoupling:
-            IsNotSubclass(abstract, instance.__class__)
+            # Ensure that the instance is a valid instance
+            IsInstance(instance)
 
-        # Validate that instance is a subclass of abstract
-        else:
-            IsSubclass(abstract, instance.__class__)
+            # Ensure that instance is NOT a subclass of abstract
+            if enforce_decoupling:
+                IsNotSubclass(abstract, instance.__class__)
 
-        # Ensure implementation
-        ImplementsAbstractMethods(
-            abstract=abstract,
-            instance=instance
-        )
+            # Validate that instance is a subclass of abstract
+            else:
+                IsSubclass(abstract, instance.__class__)
+
+            # Ensure implementation
+            ImplementsAbstractMethods(
+                abstract=abstract,
+                instance=instance
+            )
+
+            # Ensure that the alias is a valid string if provided
+            if alias:
+                IsValidAlias(alias)
+            else:
+                rf_asbtract = ReflectionAbstract(abstract)
+                alias = rf_asbtract.getModuleWithClassName()
+
+            # If the service is already registered, drop it
+            self.drop(abstract, alias)
 
-        # Ensure that the alias is a valid string if provided
-        if alias:
-            IsValidAlias(alias)
         else:
-            rf_asbtract = ReflectionAbstract(abstract)
-            alias = rf_asbtract.getModuleWithClassName()
 
-        # If the service is already registered, drop it
-        self.drop(abstract, alias)
+            # Drop the existing alias if it exists
+            self.drop(alias=alias)
+
+            # If enforce_decoupling is not a boolean, set it to False
+            enforce_decoupling = False
 
         # Register the instance with the abstract type
         self.__bindings[abstract] = Binding(

orionis/container/facades/facade.py

@@ -1,6 +1,7 @@
 from typing import Any
+from orionis.app import Orionis
 from orionis.container.exceptions import OrionisContainerAttributeError, OrionisContainerException
-from orionis.foundation.application import Application, IApplication
+from orionis.foundation.application import IApplication
 from typing import TypeVar, Any
 
 T = TypeVar('T')
@@ -34,7 +35,7 @@ class FacadeMeta(type):
 class Facade(metaclass=FacadeMeta):
 
     # Application instance to resolve services
-    _app: IApplication = Application()
+    _app: IApplication = Orionis()
 
     @classmethod
     def getFacadeAccessor(cls) -> str:

orionis/foundation/application.py

@@ -181,6 +181,7 @@ class Application(Container, IApplication):
         from orionis.foundation.providers.executor_provider import ConsoleExecuteProvider
         from orionis.foundation.providers.reactor_provider import ReactorProvider
         from orionis.foundation.providers.performance_counter_provider import PerformanceCounterProvider
+        from orionis.foundation.providers.scheduler_provider import ScheduleProvider
 
         # Core framework providers
         core_providers = [
@@ -193,7 +194,8 @@ class Application(Container, IApplication):
             InspirationalProvider,
             ConsoleExecuteProvider,
             ReactorProvider,
-            PerformanceCounterProvider
+            PerformanceCounterProvider,
+            ScheduleProvider
         ]
 
         # Register each core provider
@@ -1812,7 +1814,7 @@ class Application(Container, IApplication):
         self,
         key: str = None,
         default: Any = None
-    ) -> Any:
+    ) -> str:
         """
         Retrieve application path configuration values using dot notation.
 
@@ -1832,7 +1834,7 @@ class Application(Container, IApplication):
 
         Returns
         -------
-        Any
+        str
             The path configuration value corresponding to the given key, the entire
             paths dictionary if key is None, or the default value if the key is
             not found.
@@ -1923,6 +1925,9 @@ class Application(Container, IApplication):
         # Check if already booted
         if not self.__booted:
 
+            # Register the application instance in the container
+            self.instance(IApplication, self, alias="x-orionis.foundation.application", enforce_decoupling='X-ORIONIS')
+
             # Load configuration if not already set
             self.__loadConfig()