orionis 0.478.0__tar.gz → 0.480.0__tar.gz

{orionis-0.478.0/orionis.egg-info → orionis-0.480.0}/PKG-INFO

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

orionis-0.480.0/orionis/console/commands/scheduler_work.py

@@ -0,0 +1,88 @@
+import importlib.util
+import os
+from pathlib import Path
+from orionis.console.base.command import BaseCommand
+from orionis.console.contracts.schedule import ISchedule
+from orionis.console.exceptions import CLIOrionisRuntimeError
+from orionis.foundation.contracts.application import IApplication
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+from datetime import datetime
+
+class ScheduleWorkCommand(BaseCommand):
+    """
+    Command class to display usage information for the Orionis CLI.
+    """
+
+    # Indicates whether timestamps will be shown in the command output
+    timestamps: bool = False
+
+    # Command signature and description
+    signature: str = "schedule:work"
+
+    # Command description
+    description: str = "Executes the scheduled tasks defined in the application."
+
+    async def handle(self, orionis: IApplication, console: Console) -> bool:
+
+        try:
+
+            # Obtener la ruta absoluta del scheduler desde la configuración de la aplicación
+            scheduler_path = orionis.path('console_scheduler')
+
+            # Obtener la base path desde la variable de entorno o desde la configuración local
+            base_path = Path(os.getcwd()).resolve()
+            scheduler_path = Path(scheduler_path).resolve()
+            rel_path = scheduler_path.relative_to(base_path)
+
+            # Reemplazar los separadores por puntos y quitar la extensión .py
+            module_name = ".".join(rel_path.with_suffix('').parts)
+
+            # Importar el módulo del scheduler
+            scheduler_module = importlib.import_module(module_name)
+
+            # Obtener la clase Scheduler del módulo importado
+            Scheduler = getattr(scheduler_module, "Scheduler", None)
+
+            # Check if the Scheduler class was found
+            if Scheduler is None:
+                raise CLIOrionisRuntimeError(f"Scheduler class not found in module {module_name}")
+
+            # Obtener el método tasks de la clase Scheduler
+            task_method = getattr(Scheduler, "tasks", None)
+
+            # Check if the method exists
+            if task_method is None:
+                raise CLIOrionisRuntimeError(f"Method 'tasks' not found in Scheduler class in module {module_name}")
+
+            # Crear una instancia de ISchedule
+            schedule_serice: ISchedule = orionis.make(ISchedule)
+
+            # Inicializar el metodo
+            task_method(schedule_serice)
+
+            # Display a professional start message for the scheduler worker
+            console.line()
+            start_time = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+            panel_content = Text.assemble(
+                (" Orionis Scheduler Worker ", "bold white on green"),
+                ("\n\n", ""),
+                ("The scheduled tasks worker has started successfully.\n", "white"),
+                (f"Started at: {start_time}\n", "dim"),
+                ("To stop the worker, press ", "white"),
+                ("Ctrl+C", "bold yellow"),
+                (".", "white")
+            )
+            console.print(
+                Panel(panel_content, border_style="green", padding=(1, 2))
+            )
+            console.line()
+
+            # Iniciar el scheduler
+            await schedule_serice.start()
+
+        except Exception as exc:
+
+            # Catch any unexpected exceptions and raise as a CLIOrionisRuntimeError
+            raise CLIOrionisRuntimeError(f"An unexpected error occurred while clearing the cache: {exc}")

{orionis-0.478.0 → orionis-0.480.0}/orionis/console/commands/test.py

@@ -1,6 +1,7 @@
 from orionis.app import Orionis
 from orionis.console.base.command import BaseCommand
 from orionis.console.exceptions import CLIOrionisRuntimeError
+from orionis.foundation.contracts.application import IApplication
 from orionis.test.contracts.kernel import ITestKernel
 
 class TestCommand(BaseCommand):
@@ -26,28 +27,34 @@ class TestCommand(BaseCommand):
     # Command description
     description: str = "Executes all automated tests using the configured test kernel for the Orionis application."
 
-    def handle(self) -> dict:
+    def handle(self, app: IApplication) -> dict:
         """
-        Executes the test command for the Orionis CLI.
+        Executes all automated tests using the configured test kernel.
 
-        This method initializes the Orionis application, retrieves the test kernel instance,
-        and runs the test suite using the kernel's handle method. If any exception occurs during
-        execution, it raises a CLIOrionisRuntimeError with the error details.
+        This method retrieves the test kernel instance from the application container
+        and executes the test suite by invoking the kernel's handle method. If any
+        exception occurs during execution, it raises a CLIOrionisRuntimeError with
+        the error details.
+
+        Parameters
+        ----------
+        app : IApplication
+            The Orionis application instance providing access to the service container.
 
         Returns
         -------
         dict
-            The result of the test execution, typically containing test results or status.
+            A dictionary containing the results of the test execution, such as test
+            statuses, counts, or other relevant information.
 
         Raises
         ------
         CLIOrionisRuntimeError
             If an unexpected error occurs during the execution of the test command.
         """
-        try:
 
-            # Initialize the Orionis application instance
-            app = Orionis()
+        # Attempt to execute the test suite using the test kernel
+        try:
 
             # Retrieve the test kernel instance from the application container
             kernel: ITestKernel = app.make(ITestKernel)

orionis-0.480.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.480.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.478.0 → orionis-0.480.0}/orionis/console/core/reactor.py

@@ -21,7 +21,7 @@ class Reactor(IReactor):
 
     def __init__(
         self,
-        app: Optional[IApplication] = None
+        app: IApplication
     ):
         """
         Initializes a new Reactor instance for command discovery and management.
@@ -56,7 +56,7 @@ class Reactor(IReactor):
         """
 
         # Initialize the application instance, using provided app or creating new Orionis instance
-        self.__app = app or Orionis()
+        self.__app = app
 
         # Set the project root directory to current working directory for module path resolution
         self.__root: str = str(Path.cwd())
@@ -111,6 +111,7 @@ class Reactor(IReactor):
         from orionis.console.commands.publisher import PublisherCommand
         from orionis.console.commands.workflow import WorkFlowGithubCommand
         from orionis.console.commands.cache import CacheClearCommand
+        from orionis.console.commands.scheduler_work import ScheduleWorkCommand
 
         # List of core command classes to load (extend this list as more core commands are added)
         core_commands = [
@@ -119,7 +120,8 @@ class Reactor(IReactor):
             TestCommand,
             PublisherCommand,
             WorkFlowGithubCommand,
-            CacheClearCommand
+            CacheClearCommand,
+            ScheduleWorkCommand
         ]
 
         # Iterate through the core command classes and register them

orionis-0.480.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.478.0 → orionis-0.480.0}/orionis/console/kernel.py

@@ -38,7 +38,7 @@ class KernelCLI(IKernelCLI):
 
         # Retrieve and initialize the reactor instance from the application container.
         # The reactor is responsible for dispatching CLI commands.
-        self.__reactor: IReactor = app.make('x-orionis.console.core.reactor', app)
+        self.__reactor: IReactor = app.make('x-orionis.console.core.reactor')
 
         # Retrieve and initialize the console instance for command output and error handling.
         self.__console: IConsole = app.make('x-orionis.console.output.console')