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

orionis/console/contracts/event.py

@@ -0,0 +1,178 @@
+from abc import ABC, abstractmethod
+from datetime import datetime
+from orionis.console.enums.event import Event as EventEntity
+
+class IEvent(ABC):
+
+    @abstractmethod
+    def toEntity(
+        self
+    ) -> EventEntity:
+        """
+        Retrieve the event details as an EventEntity instance.
+
+        This method gathers all relevant attributes of the current Event object,
+        such as its signature, arguments, purpose, random delay, start and end dates,
+        and trigger, and returns them encapsulated in an EventEntity object.
+
+        Returns
+        -------
+        EventEntity
+            An EventEntity instance containing the event's signature, arguments,
+            purpose, random delay, start date, end date, and trigger.
+        """
+        pass
+
+    @abstractmethod
+    def purpose(
+        self,
+        purpose: str
+    ) -> 'IEvent':
+        """
+        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
+        ------
+        CLIOrionisValueError
+            If the provided purpose is not a non-empty string.
+        """
+        pass
+
+    @abstractmethod
+    def startDate(
+        self,
+        start_date: datetime
+    ) -> 'IEvent':
+        """
+        Set the start date for the event execution.
+
+        This method allows you to specify a start date for when the event should
+        begin execution. The start date must be a datetime instance.
+
+        Parameters
+        ----------
+        start_date : datetime
+            The start date for the event execution.
+
+        Returns
+        -------
+        Event
+            Returns the current instance of the Event to allow method chaining.
+        """
+        pass
+
+    @abstractmethod
+    def endDate(
+        self,
+        end_date: datetime
+    ) -> 'IEvent':
+        """
+        Set the end date for the event execution.
+
+        This method allows you to specify an end date for when the event should
+        stop executing. The end date must be a datetime instance.
+
+        Parameters
+        ----------
+        end_date : datetime
+            The end date for the event execution.
+
+        Returns
+        -------
+        Event
+            Returns the current instance of the Event to allow method chaining.
+        """
+        pass
+
+    @abstractmethod
+    def randomDelay(
+        self,
+        max_seconds: int = 10
+    ) -> 'IEvent':
+        """
+        Set a random delay for the event execution.
+
+        This method allows you to specify a random delay up to a maximum
+        number of seconds before the event is executed. This can be useful for
+        distributing load or avoiding collisions in scheduled tasks.
+
+        Parameters
+        ----------
+        max_seconds : int
+            The maximum number of seconds to wait before executing the event.
+
+        Returns
+        -------
+        Event
+            Returns the current instance of the Event to allow method chaining.
+        """
+        pass
+
+    @abstractmethod
+    def onceAt(
+        self,
+        date: datetime
+    ) -> bool:
+        """
+        Schedule the event to run once at a specific date and time.
+
+        This method allows you to schedule the event to execute once at a specified
+        date and time. The date must be a datetime instance.
+
+        Parameters
+        ----------
+        date : datetime
+            The specific date and time when the event should run.
+
+        Returns
+        -------
+        bool
+            Returns True if the scheduling was successful.
+        """
+        pass
+
+    @abstractmethod
+    def everySeconds(
+        self,
+        seconds: int
+    ) -> bool:
+        """
+        Schedule the event to run at fixed intervals measured in seconds.
+
+        This method configures the event to execute repeatedly at a specified interval
+        (in seconds). Optionally, the event can be restricted to a time window using
+        previously set start and end dates. A random delay (jitter) can also be applied
+        if configured.
+
+        Parameters
+        ----------
+        seconds : int
+            The interval, in seconds, at which the event should be executed. Must be a positive integer.
+
+        Returns
+        -------
+        bool
+            Returns True if the interval scheduling was successfully configured.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If `seconds` is not a positive integer.
+        """
+        pass

orionis/console/contracts/schedule.py

@@ -1,4 +1,127 @@
 from abc import ABC, abstractmethod
+from typing import List, Optional
+from orionis.console.tasks.event import Event
 
 class ISchedule(ABC):
-    pass
+
+    @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
+    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 handles asynchronous job execution.
+        Using async ensures proper cleanup in asyncio environments.
+
+        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.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It shuts down the AsyncIO scheduler.
+        """
+        pass
+
+    @abstractmethod
+    async def remove(self, signature: str) -> bool:
+        """
+        Remove a scheduled job from the AsyncIO scheduler asynchronously.
+
+        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.
+
+        Parameters
+        ----------
+        signature : str
+            The signature of the command/job to remove from the scheduler.
+
+        Returns
+        -------
+        bool
+            Returns True if the job was successfully removed, False if the job was not found.
+
+        Raises
+        ------
+        ValueError
+            If the signature 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/console/enums/event.py

@@ -0,0 +1,55 @@
+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.support.entities.base import BaseEntity
+
+@dataclass(kw_only=True)
+class Event(BaseEntity):
+    """
+    Represents an event with scheduling and execution details.
+
+    Attributes
+    ----------
+    signature : str
+        The unique identifier or signature of the event.
+    args : Optional[List[str]]
+        A list of arguments associated with the event.
+    purpose : Optional[str]
+        A description of the event's purpose.
+    random_delay : Optional[int]
+        An optional random delay (in seconds) before the event is triggered.
+    start_date : Optional[datetime]
+        The start date and time for the event.
+    end_date : Optional[datetime]
+        The end date and time for the event.
+    trigger : Optional[Union[CronTrigger, DateTrigger, IntervalTrigger]]
+        The trigger mechanism for the event.
+    """
+
+
+    # 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

orionis/console/tasks/event.py

@@ -0,0 +1,332 @@
+import random
+from datetime import datetime
+from typing import List, Optional, Union
+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.enums.event import Event as EventEntity
+from orionis.console.exceptions import CLIOrionisValueError
+
+class Event(IEvent):
+
+    def __init__(
+        self,
+        signature: str,
+        args: Optional[List[str]],
+        purpose: Optional[str] = None,
+    ):
+        """
+        Initialize a new Event instance.
+
+        Parameters
+        ----------
+        signature : str
+            The unique identifier or signature for the event. This is typically
+            used to distinguish between different events in the system.
+        args : Optional[List[str]]
+            A list of arguments required by the event. If not provided, an empty
+            list will be used.
+        purpose : Optional[str], optional
+            A human-readable description or purpose for the event, by default None.
+
+        Returns
+        -------
+        None
+            This constructor does not return any value. It initializes the internal
+            state of the Event object.
+        """
+
+        # Store the event's signature
+        self.__signature: str = signature
+
+        # Store the event's arguments, defaulting to an empty list if None is provided
+        self.__args: Optional[List[str]] = args if args is not None else []
+
+        # Store the event's purpose or description
+        self.__purpose: Optional[str] = purpose
+
+        # Initialize the random delay attribute (in seconds) as None
+        self.__random_delay: Optional[int] = None
+
+        # Initialize the start date for the event as None
+        self.__start_date: Optional[datetime] = None
+
+        # Initialize the end date for the event as None
+        self.__end_date: Optional[datetime] = None
+
+        # Initialize the trigger for the event as None; can be set to a Cron, Date, or Interval trigger
+        self.__trigger: Optional[Union[CronTrigger, DateTrigger, IntervalTrigger]] = None
+
+        # Initialize the details for the event as None; can be used to store additional information
+        self.__details: Optional[str] = None
+
+    def toEntity(
+        self
+    ) -> EventEntity:
+        """
+        Retrieve the event details as an EventEntity instance.
+
+        This method gathers all relevant attributes of the current Event object,
+        such as its signature, arguments, purpose, random delay, start and end dates,
+        and trigger, and returns them encapsulated in an EventEntity object.
+
+        Returns
+        -------
+        EventEntity
+            An EventEntity instance containing the event's signature, arguments,
+            purpose, random delay, start date, end date, and trigger.
+        """
+
+        # Validate that the signature is set and is a non-empty string
+        if not self.__signature:
+            raise CLIOrionisValueError("Signature is required for the event.")
+        if not isinstance(self.__args, list):
+            raise CLIOrionisValueError("Args must be a list.")
+        if self.__purpose is not None and not isinstance(self.__purpose, str):
+            raise CLIOrionisValueError("Purpose must be a string or None.")
+
+        # Validate that start_date and end_date are datetime instances if they are set
+        if self.__start_date is not None and not isinstance(self.__start_date, datetime):
+            raise CLIOrionisValueError("Start date must be a datetime instance.")
+        if self.__end_date is not None and not isinstance(self.__end_date, datetime):
+            raise CLIOrionisValueError("End date must be a datetime instance.")
+
+        # Validate that trigger is one of the expected types if it is set
+        if self.__trigger is not None and not isinstance(self.__trigger, (CronTrigger, DateTrigger, IntervalTrigger)):
+            raise CLIOrionisValueError("Trigger must be a CronTrigger, DateTrigger, or IntervalTrigger.")
+
+        # Validate that random_delay is an integer if it is set
+        if self.__random_delay is not None and not isinstance(self.__random_delay, int):
+            raise CLIOrionisValueError("Random delay must be an integer or None.")
+
+        # Validate that details is a string if it is set
+        if self.__details is not None and not isinstance(self.__details, str):
+            raise CLIOrionisValueError("Details must be a string or None.")
+
+        # Construct and return an EventEntity with the current event's attributes
+        return EventEntity(
+            signature=self.__signature,
+            args=self.__args,
+            purpose=self.__purpose,
+            random_delay=self.__random_delay,
+            start_date=self.__start_date,
+            end_date=self.__end_date,
+            trigger=self.__trigger,
+            details=self.__details
+        )
+
+    def purpose(
+        self,
+        purpose: str
+    ) -> 'Event':
+        """
+        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
+        ------
+        CLIOrionisValueError
+            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 CLIOrionisValueError("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 startDate(
+        self,
+        start_date: datetime
+    ) -> 'Event':
+        """
+        Set the start date for the event execution.
+
+        This method allows you to specify a start date for when the event should
+        begin execution. The start date must be a datetime instance.
+
+        Parameters
+        ----------
+        start_date : datetime
+            The start date for the event execution.
+
+        Returns
+        -------
+        Event
+            Returns the current instance of the Event to allow method chaining.
+        """
+
+        # Validate that start_date is a datetime instance
+        if not isinstance(start_date, datetime):
+            raise CLIOrionisValueError("Start date must be a datetime instance.")
+
+        # Set the internal start date attribute
+        self.__start_date = start_date
+
+        # Return self to support method chaining
+        return self
+
+    def endDate(
+        self,
+        end_date: datetime
+    ) -> 'Event':
+        """
+        Set the end date for the event execution.
+
+        This method allows you to specify an end date for when the event should
+        stop executing. The end date must be a datetime instance.
+
+        Parameters
+        ----------
+        end_date : datetime
+            The end date for the event execution.
+
+        Returns
+        -------
+        Event
+            Returns the current instance of the Event to allow method chaining.
+        """
+
+        # Validate that end_date is a datetime instance
+        if not isinstance(end_date, datetime):
+            raise CLIOrionisValueError("End date must be a datetime instance.")
+
+        # Set the internal end date attribute
+        self.__end_date = end_date
+
+        # Return self to support method chaining
+        return self
+
+    def randomDelay(
+        self,
+        max_seconds: int = 10
+    ) -> 'Event':
+        """
+        Set a random delay for the event execution.
+
+        This method allows you to specify a random delay up to a maximum
+        number of seconds before the event is executed. This can be useful for
+        distributing load or avoiding collisions in scheduled tasks.
+
+        Parameters
+        ----------
+        max_seconds : int
+            The maximum number of seconds to wait before executing the event.
+
+        Returns
+        -------
+        Event
+            Returns the current instance of the Event to allow method chaining.
+        """
+
+        # Validate that max_seconds is a positive integer
+        if not isinstance(max_seconds, int) or max_seconds <= 0:
+            raise CLIOrionisValueError("max_seconds must be a positive integer.")
+
+        # Generate a random delay between 1 and max_seconds (inclusive)
+        self.__random_delay = random.randint(1, max_seconds)
+
+        # Return self to support method chaining
+        return self
+
+    def onceAt(
+        self,
+        date: datetime
+    ) -> bool:
+        """
+        Schedule the event to run once at a specific date and time.
+
+        This method allows you to schedule the event to execute once at a specified
+        date and time. The date must be a datetime instance.
+
+        Parameters
+        ----------
+        date : datetime
+            The specific date and time when the event should run.
+
+        Returns
+        -------
+        bool
+            Returns True if the scheduling was successful.
+        """
+
+        # Validate that date is a datetime instance
+        if not isinstance(date, datetime):
+            raise CLIOrionisValueError("The date must be a datetime instance.")
+
+        # Set the start and end dates to the specified date
+        self.__start_date = date
+        self.__end_date = date
+
+        # Set the trigger to a DateTrigger for the specified date
+        self.__trigger = DateTrigger(run_date=date)
+
+        # Optionally, set the details for the event
+        self.__details = f"Once At: {date.strftime('%Y-%m-%d %H:%M:%S')}"
+
+        # Return self to support method chaining
+        return True
+
+    def everySeconds(
+        self,
+        seconds: int
+    ) -> bool:
+        """
+        Schedule the event to run at fixed intervals measured in seconds.
+
+        This method configures the event to execute repeatedly at a specified interval
+        (in seconds). Optionally, the event can be restricted to a time window using
+        previously set start and end dates. A random delay (jitter) can also be applied
+        if configured.
+
+        Parameters
+        ----------
+        seconds : int
+            The interval, in seconds, at which the event should be executed. Must be a positive integer.
+
+        Returns
+        -------
+        bool
+            Returns True if the interval scheduling was successfully configured.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If `seconds` is not a positive integer.
+        """
+
+        # 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.")
+
+        # Configure the trigger to execute the event at the specified interval,
+        # using any previously set start_date, end_date, and random_delay (jitter).
+        self.__trigger = IntervalTrigger(
+            seconds=seconds,
+            start_date=self.__start_date,
+            end_date=self.__end_date,
+            jitter=self.__random_delay
+        )
+
+        # Indicate that the scheduling was successful.
+        return True

orionis/console/tasks/schedule.py

@@ -1,20 +1,16 @@
 import asyncio
 import logging
-from datetime import datetime
-from typing import List, Optional
+from typing import Dict, List, Optional
 import pytz
 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.tasks.event import Event
 from orionis.services.log.contracts.log_service import ILogger
 
-class Scheduler():
+class Scheduler(ISchedule):
 
     def __init__(
         self,
@@ -62,16 +58,14 @@ 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] = []
 
         # Log the initialization of the Scheduler.
-        self.__logger.info("Scheduler initialized.")
+        self.__logger.info("Orionis scheduler initialized.")
 
     def __getCommands(
         self
@@ -166,56 +160,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 +245,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 +272,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()
 
@@ -577,22 +395,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/metadata/framework.py

@@ -5,7 +5,7 @@
 NAME = "orionis"
 
 # Current version of the framework
-VERSION = "0.478.0"
+VERSION = "0.479.0"
 
 # Full name of the author or maintainer of the project
 AUTHOR = "Raul Mauricio Uñate Castro"

{orionis-0.478.0.dist-info → orionis-0.479.0.dist-info}/METADATA

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

{orionis-0.478.0.dist-info → orionis-0.479.0.dist-info}/RECORD

@@ -18,9 +18,10 @@ orionis/console/commands/test.py,sha256=mWPB_m_nUrsakCT1N6fcCBYU9mYj1IC39n3ICbQp
 orionis/console/commands/version.py,sha256=SUuNDJ40f2uq69OQUmPQXJKaa9Bm_iVRDPmBd7zc1Yc,3658
 orionis/console/commands/workflow.py,sha256=NYOmjTSvm2o6AE4h9LSTZMFSYPQreNmEJtronyOxaYk,2451
 orionis/console/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+orionis/console/contracts/event.py,sha256=pxoxNjk31bt6yGvUFRTo_TI_SaZZar6iSIJARWR6KbM,5170
 orionis/console/contracts/kernel.py,sha256=mh4LlhEYHh3FuGZZQ0GBhD6ZLa5YQvaNj2r01IIHI5Y,826
 orionis/console/contracts/reactor.py,sha256=Xeq7Zrw6WE5MV_XOQfiQEchAFbb6-0TjLpjWOxYW--g,4554
-orionis/console/contracts/schedule.py,sha256=A7yYPjPmRizDHOR9k4qvY3NuRPrWBmNuQs6ENGXWtBs,70
+orionis/console/contracts/schedule.py,sha256=eGjcOH7kgdf0fWDZRfOFUQsIx4E8G38ayX5JwpkpN8E,4977
 orionis/console/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/console/core/reactor.py,sha256=Hd7T-jNG_tzhpJXRztjDSKCtm7-3LOh5lcQ__cIchMk,30172
 orionis/console/dumper/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -33,7 +34,7 @@ orionis/console/dynamic/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeR
 orionis/console/dynamic/contracts/progress_bar.py,sha256=NYebL2h-vg2t2H6IhJjuC37gglRkpT-MW71wbJtpLNg,1784
 orionis/console/enums/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/console/enums/command.py,sha256=lCfVp2vnDojJN2gjdVxE_XU3mRjZZgOIxPfBVQYo9w4,1278
-orionis/console/enums/task.py,sha256=1oRR_VKfzsojCxxywYAMhpPvZQ8kSEEdXeXvCOfAXmg,1322
+orionis/console/enums/event.py,sha256=XRV7N14N5HHt-c0HqYhrbKv4n2P7ZOCcBT_3OAQzenU,1929
 orionis/console/exceptions/__init__.py,sha256=0qlHNuHMVZO87M-rP8lThUUyljRM1jSFNikaxSCjSbw,366
 orionis/console/exceptions/cli_exception.py,sha256=HsZ_vSeNiJWQ0gznVFNcIdhM0Bj_vkSRVBJs0wMjEKY,1141
 orionis/console/exceptions/cli_orionis_value_error.py,sha256=RQP0HRwxDG8hxFOT1kUoZ1Ab1CZ1KLoSIl5yqlmgG4M,1147
@@ -48,7 +49,8 @@ orionis/console/output/contracts/executor.py,sha256=7l3kwnvv6GlH9EYk0v94YE1olex_
 orionis/console/output/enums/__init__.py,sha256=LAaAxg-DpArCjf_jqZ0_9s3p8899gntDYkSU_ppTdC8,66
 orionis/console/output/enums/styles.py,sha256=6a4oQCOBOKMh2ARdeq5GlIskJ3wjiylYmh66tUKKmpQ,4053
 orionis/console/tasks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/console/tasks/schedule.py,sha256=qlll0aagyOzAa3EmluycrSM9zvxVqSMgP5bUOGm1zZA,22215
+orionis/console/tasks/event.py,sha256=NdOht_yXqKW0EIsIVrctIgOhQDWAR5fuMPEF05zTWtI,12029
+orionis/console/tasks/schedule.py,sha256=L0l8GqPWsVtIEX1rifw3MeKkcAAOvu9ODdLmhUyyKTA,16802
 orionis/container/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/container/container.py,sha256=p7kJ-hwnDattTWCArt0ypol4bW3M334hIZ2FAQhID-w,87570
 orionis/container/context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -194,7 +196,7 @@ orionis/foundation/providers/reactor_provider.py,sha256=P0KQcp4AFKTrD6BStGfCTqhG
 orionis/foundation/providers/testing_provider.py,sha256=SrJRpdvcblx9WvX7x9Y3zc7OQfiTf7la0HAJrm2ESlE,3725
 orionis/foundation/providers/workers_provider.py,sha256=oa_2NIDH6UxZrtuGkkoo_zEoNIMGgJ46vg5CCgAm7wI,3926
 orionis/metadata/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/metadata/framework.py,sha256=_RmAaDI2nx_VXNowa0s5vscpNmtmWyTr5s7UiHMkqpg,4109
+orionis/metadata/framework.py,sha256=PYshO2bwCnp97QmgRrzTX5U6DHY_qu1YKgy9kTlKVyc,4109
 orionis/metadata/package.py,sha256=k7Yriyp5aUcR-iR8SK2ec_lf0_Cyc-C7JczgXa-I67w,16039
 orionis/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/services/asynchrony/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -365,7 +367,7 @@ orionis/test/validators/web_report.py,sha256=n9BfzOZz6aEiNTypXcwuWbFRG0OdHNSmCNu
 orionis/test/validators/workers.py,sha256=rWcdRexINNEmGaO7mnc1MKUxkHKxrTsVuHgbnIfJYgc,1206
 orionis/test/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/test/view/render.py,sha256=f-zNhtKSg9R5Njqujbg2l2amAs2-mRVESneLIkWOZjU,4082
-orionis-0.478.0.dist-info/licenses/LICENCE,sha256=JhC-z_9mbpUrCfPjcl3DhDA8trNDMzb57cvRSam1avc,1463
+orionis-0.479.0.dist-info/licenses/LICENCE,sha256=JhC-z_9mbpUrCfPjcl3DhDA8trNDMzb57cvRSam1avc,1463
 tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/container/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/container/context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -512,8 +514,8 @@ tests/testing/validators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZ
 tests/testing/validators/test_testing_validators.py,sha256=WPo5GxTP6xE-Dw3X1vZoqOMpb6HhokjNSbgDsDRDvy4,16588
 tests/testing/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/testing/view/test_render.py,sha256=tnnMBwS0iKUIbogLvu-7Rii50G6Koddp3XT4wgdFEYM,1050
-orionis-0.478.0.dist-info/METADATA,sha256=LI8ito8saDpADOaQ1uBmcGO17dm5DoY7s_Ahep3kECk,4801
-orionis-0.478.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-orionis-0.478.0.dist-info/top_level.txt,sha256=2bdoHgyGZhOtLAXS6Om8OCTmL24dUMC_L1quMe_ETbk,14
-orionis-0.478.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-orionis-0.478.0.dist-info/RECORD,,
+orionis-0.479.0.dist-info/METADATA,sha256=SJeq-4OG1PSuNSQA9NgyExYAVHasB7U6z54gMKgwQTY,4801
+orionis-0.479.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+orionis-0.479.0.dist-info/top_level.txt,sha256=2bdoHgyGZhOtLAXS6Om8OCTmL24dUMC_L1quMe_ETbk,14
+orionis-0.479.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+orionis-0.479.0.dist-info/RECORD,,

orionis/console/enums/task.py

@@ -1,42 +0,0 @@
-from dataclasses import dataclass
-from typing import List, Optional
-from orionis.support.entities.base import BaseEntity
-
-@dataclass(kw_only=True)
-class Task(BaseEntity):
-    """
-    Represents a task entity containing metadata for execution and description.
-
-    Parameters
-    ----------
-    signature : str
-        The unique identifier or signature of the task.
-    args : Optional[List[str]], optional
-        List of arguments required by the task, by default None.
-    purpose : str, optional
-        Brief description of the task's purpose, by default None.
-    trigger : str, optional
-        Event or condition that triggers the task, by default None.
-    details : str, optional
-        Additional details or information about the task, by default None.
-
-    Returns
-    -------
-    Task
-        An instance of the Task class with the specified metadata.
-    """
-
-    # Unique identifier for the task
-    signature: str
-
-    # List of arguments required by the task (optional)
-    args: Optional[List[str]] = None
-
-    # Brief description of the task's purpose (optional)
-    purpose: str = None
-
-    # Event or condition that triggers the task (optional)
-    trigger: str = None
-
-    # Additional details or information about the task (optional)
-    details: str = None