orionis 0.477.0__tar.gz → 0.479.0__tar.gz

{orionis-0.477.0/orionis.egg-info → orionis-0.479.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.477.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.479.0/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-0.479.0/orionis/console/contracts/schedule.py

@@ -0,0 +1,127 @@
+from abc import ABC, abstractmethod
+from typing import List, Optional
+from orionis.console.tasks.event import Event
+
+class ISchedule(ABC):
+
+    @abstractmethod
+    def command(
+        self,
+        signature: str,
+        args: Optional[List[str]] = None
+    ) -> 'Event':
+        """
+        Prepare an Event instance for a given command signature and its arguments.
+
+        This method validates the provided command signature and arguments, ensuring
+        that the command exists among the registered commands and that the arguments
+        are in the correct format. If validation passes, it creates and returns an
+        Event object representing the scheduled command, including its signature,
+        arguments, and description.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature identifying the command to be scheduled. Must be a non-empty string.
+        args : Optional[List[str]], optional
+            A list of string arguments to be passed to the command. Defaults to None.
+
+        Returns
+        -------
+        Event
+            An Event instance containing the command signature, arguments, and its description.
+
+        Raises
+        ------
+        ValueError
+            If the command signature is not a non-empty string, if the arguments are not a list
+            of strings or None, or if the command does not exist among the registered commands.
+        """
+        pass
+
+    @abstractmethod
+    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-0.479.0/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-0.479.0/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