orionis 0.475.0__tar.gz → 0.476.0__tar.gz

{orionis-0.475.0/orionis.egg-info → orionis-0.476.0}/PKG-INFO

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

orionis-0.476.0/orionis/console/contracts/reactor.py

@@ -0,0 +1,110 @@
+from abc import ABC, abstractmethod
+from typing import Any, List, Optional
+
+class IReactor(ABC):
+
+    @abstractmethod
+    def info(self) -> List[dict]:
+        """
+        Retrieves a list of all registered commands with their metadata.
+
+        This method returns a list of dictionaries, each containing information about
+        a registered command, including its signature, description, and whether it has
+        timestamps enabled. This is useful for introspection and displaying available
+        commands to the user.
+
+        Returns
+        -------
+        List[dict]
+            A list of dictionaries representing the registered commands, where each dictionary
+            contains the command's signature, description, and timestamps status.
+        """
+        pass
+
+    @abstractmethod
+    def call(
+        self,
+        signature: str,
+        args: Optional[List[str]] = None
+    ) -> Optional[Any]:
+        """
+        Executes a registered command synchronously by its signature, optionally passing command-line arguments.
+
+        This method retrieves a command from the internal registry using its unique signature,
+        validates and parses any provided arguments using the command's argument parser,
+        and then executes the command's `handle` method synchronously. It manages execution timing,
+        logging, and error handling, and returns any output produced by the command.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature identifier of the command to execute.
+        args : Optional[List[str]], default None
+            List of command-line arguments to pass to the command. If None, no arguments are provided.
+
+        Returns
+        -------
+        Optional[Any]
+            The output produced by the command's `handle` method if execution is successful.
+            Returns None if the command does not produce a result or if an error occurs.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the command with the specified signature is not found in the registry.
+        SystemExit
+            If argument parsing fails due to invalid arguments provided (raised by argparse).
+        Exception
+            Propagates any exception raised during command execution after logging and error output.
+
+        Notes
+        -----
+        - Logs execution start, completion, and errors with timestamps if enabled.
+        - Handles argument parsing and injects parsed arguments into the command instance.
+        - All exceptions are logged and displayed in the console.
+        """
+        pass
+
+    @abstractmethod
+    async def callAsync(
+        self,
+        signature: str,
+        args: Optional[List[str]] = None
+    ) -> Optional[Any]:
+        """
+        Executes a registered command asynchronously by its signature, optionally passing command-line arguments.
+
+        This method locates a command in the internal registry using its unique signature,
+        validates and parses any provided arguments using the command's argument parser,
+        and then executes the command's `handle` method asynchronously. It manages execution timing,
+        logging, and error handling, and returns any output produced by the command.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature identifier of the command to execute.
+        args : Optional[List[str]], default None
+            List of command-line arguments to pass to the command. If None, no arguments are provided.
+
+        Returns
+        -------
+        Optional[Any]
+            The output produced by the command's `handle` method if execution is successful.
+            Returns None if the command does not produce a result or if an error occurs.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the command with the specified signature is not found in the registry.
+        SystemExit
+            If argument parsing fails due to invalid arguments provided (raised by argparse).
+        Exception
+            Propagates any exception raised during command execution after logging and error output.
+
+        Notes
+        -----
+        - Logs execution start, completion, and errors with timestamps if enabled.
+        - Handles argument parsing and injects parsed arguments into the command instance.
+        - All exceptions are logged and displayed in the console.
+        """
+        pass

{orionis-0.475.0 → orionis-0.476.0}/orionis/console/core/reactor.py

@@ -1,19 +1,21 @@
 import argparse
 import os
 import re
-import time
 from pathlib import Path
-from typing import List, Optional
+from typing import Any, List, Optional
 from orionis.app import Orionis
 from orionis.console.args.argument import CLIArgument
 from orionis.console.base.command import BaseCommand
 from orionis.console.base.contracts.command import IBaseCommand
 from orionis.console.contracts.reactor import IReactor
+from orionis.console.enums.command import Command
+from orionis.console.exceptions import CLIOrionisValueError
 from orionis.console.output.contracts.console import IConsole
 from orionis.console.output.contracts.executor import IExecutor
 from orionis.foundation.contracts.application import IApplication
 from orionis.services.introspection.modules.reflection import ReflectionModule
 from orionis.services.log.contracts.log_service import ILogger
+from orionis.support.performance.contracts.counter import IPerformanceCounter
 
 class Reactor(IReactor):
 
@@ -60,7 +62,7 @@ class Reactor(IReactor):
         self.__root: str = str(Path.cwd())
 
         # Initialize the internal command registry as an empty dictionary
-        self.__commands: dict = {}
+        self.__commands: dict[str, Command] = {}
 
         # Automatically discover and load command classes from the console commands directory
         self.__loadCommands(str(self.__app.path('console_commands')), self.__root)
@@ -77,6 +79,9 @@ class Reactor(IReactor):
         # Initialize the logger service for logging command execution details
         self.__logger: ILogger = self.__app.make('x-orionis.services.log.log_service')
 
+        # Initialize the performance counter for measuring command execution time
+        self.__performance_counter: IPerformanceCounter = self.__app.make('x-orionis.support.performance.counter')
+
     def __loadCoreCommands(self) -> None:
         """
         Loads and registers core command classes provided by the Orionis framework.
@@ -127,13 +132,13 @@ class Reactor(IReactor):
             args = self.__ensureArguments(obj)
 
             # Register the command in the internal registry with all its metadata
-            self.__commands[signature] = {
-                "class": obj,
-                "timestamps": timestamp,
-                "signature": signature,
-                "description": description,
-                "args": args
-            }
+            self.__commands[signature] = Command(
+                obj=obj,
+                timestamps=timestamp,
+                signature=signature,
+                description=description,
+                args=args
+            )
 
     def __loadCommands(self, commands_path: str, root_path: str) -> None:
         """
@@ -208,13 +213,13 @@ class Reactor(IReactor):
                             args = self.__ensureArguments(obj)
 
                             # Add the command to the internal registry
-                            self.__commands[signature] = {
-                                "class": obj,
-                                "timestamps": timestamp,
-                                "signature": signature,
-                                "description": description,
-                                "args": args
-                            }
+                            self.__commands[signature] = Command(
+                                obj=obj,
+                                timestamps=timestamp,
+                                signature=signature,
+                                description=description,
+                                args=args
+                            )
 
     def __ensureTimestamps(self, obj: IBaseCommand) -> bool:
         """
@@ -403,6 +408,61 @@ class Reactor(IReactor):
         # Return the configured ArgumentParser
         return arg_parser
 
+    def __parseArgs(
+        self,
+        command: Command,
+        args: Optional[List[str]] = None
+    ) -> dict:
+        """
+        Parses command-line arguments for a given command using its internal ArgumentParser.
+
+        This method takes a command object and an optional list of command-line arguments,
+        and parses them into a dictionary of argument names and values. If the command
+        defines an ArgumentParser (i.e., expects arguments), the arguments are parsed
+        accordingly. If no arguments are expected or provided, an empty dictionary is returned.
+
+        Parameters
+        ----------
+        command : Command
+            The command object containing the argument parser and metadata.
+        args : Optional[List[str]], default None
+            A list of command-line arguments to parse. If None, an empty list is used.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the parsed argument names and their corresponding values.
+            Returns an empty dictionary if no arguments are expected or provided.
+
+        Raises
+        ------
+        SystemExit
+            Raised by argparse if argument parsing fails or if help is requested.
+        """
+
+        # Initialize parsed_args to None
+        parsed_args = None
+
+        # If the command expects arguments, parse them using its ArgumentParser
+        if command.args is not None and isinstance(command.args, argparse.ArgumentParser):
+            if args is None:
+                args = []
+            try:
+                # Parse the provided arguments using the command's ArgumentParser
+                parsed_args = command.args.parse_args(args)
+            except SystemExit:
+                # Allow argparse to handle help/error messages and exit
+                raise
+
+        # Convert the parsed arguments to a dictionary and return
+        if isinstance(parsed_args, argparse.Namespace):
+            return vars(parsed_args)
+        elif isinstance(parsed_args, dict):
+            return parsed_args
+        else:
+            # Return an empty dictionary if no arguments were parsed
+            return {}
+
     def info(self) -> List[dict]:
         """
         Retrieves a list of all registered commands with their metadata.
@@ -426,8 +486,8 @@ class Reactor(IReactor):
         for command in self.__commands.values():
 
             # Extract command metadata
-            signature:str = command.get("signature")
-            description:str = command.get("description", "")
+            signature:str = command.signature
+            description:str = command.description
 
             # Skip internal commands (those with double underscores)
             if signature.startswith('__') and signature.endswith('__'):
@@ -446,103 +506,179 @@ class Reactor(IReactor):
         self,
         signature: str,
         args: Optional[List[str]] = None
-    ):
+    ) -> Optional[Any]:
         """
-        Executes a command by its signature with optional command-line arguments.
+        Executes a registered command synchronously by its signature, optionally passing command-line arguments.
 
-        This method retrieves a registered command by its signature, validates any provided
-        arguments against the command's argument parser, and executes the command's handle
-        method with the parsed arguments and application context.
+        This method retrieves a command from the internal registry using its unique signature,
+        validates and parses any provided arguments using the command's argument parser,
+        and then executes the command's `handle` method synchronously. It manages execution timing,
+        logging, and error handling, and returns any output produced by the command.
 
         Parameters
         ----------
         signature : str
             The unique signature identifier of the command to execute.
         args : Optional[List[str]], default None
-            Command-line arguments to pass to the command. If None, no arguments are provided.
+            List of command-line arguments to pass to the command. If None, no arguments are provided.
 
         Returns
         -------
-        None
-            This method does not return any value. The command's handle method is called
-            directly for execution.
+        Optional[Any]
+            The output produced by the command's `handle` method if execution is successful.
+            Returns None if the command does not produce a result or if an error occurs.
 
         Raises
         ------
-        ValueError
+        CLIOrionisValueError
             If the command with the specified signature is not found in the registry.
         SystemExit
-            If argument parsing fails due to invalid arguments provided.
+            If argument parsing fails due to invalid arguments provided (raised by argparse).
+        Exception
+            Propagates any exception raised during command execution after logging and error output.
+
+        Notes
+        -----
+        - Logs execution start, completion, and errors with timestamps if enabled.
+        - Handles argument parsing and injects parsed arguments into the command instance.
+        - All exceptions are logged and displayed in the console.
         """
 
-        # Retrieve the command from the registry
-        command: dict = self.__commands.get(signature)
+        # Retrieve the command from the registry by its signature
+        command: Command = self.__commands.get(signature)
         if command is None:
-            raise ValueError(f"Command '{signature}' not found.")
+            raise CLIOrionisValueError(f"Command '{signature}' not found.")
 
-        # Start execution timer
-        start_time = time.perf_counter()
+        # Start execution timer for performance measurement
+        self.__performance_counter.start()
 
-        # Get command details
-        command_class = command.get("class")
-        arg_parser: Optional[argparse.ArgumentParser] = command.get("args")
-        timestamps: bool = command.get("timestamps")
+        # Log the command execution start with RUNNING state if timestamps are enabled
+        if command.timestamps:
+            self.__executer.running(program=signature)
 
-        # Initialize parsed arguments
-        parsed_args = None
+        try:
+            # Instantiate the command class using the application container
+            command_instance: IBaseCommand = self.__app.make(command.obj)
 
-        # If the command has arguments and args were provided, validate them
-        if arg_parser is not None and isinstance(arg_parser, argparse.ArgumentParser):
-            if args is None:
-                args = []
-            try:
-                # Parse the provided arguments using the command's ArgumentParser
-                parsed_args = arg_parser.parse_args(args)
-            except SystemExit:
-                # Re-raise SystemExit to allow argparse to handle help/error messages
-                raise
+            # Inject parsed arguments into the command instance
+            command_instance._args = self.__parseArgs(command, args)
 
-        # Log the command execution start with RUNNING state
-        if timestamps:
+            # Execute the command's handle method and capture its output
+            output = self.__app.call(command_instance, 'handle')
+
+            # Calculate elapsed time and log completion with DONE state if command.timestamps are enabled
+            elapsed_time = round(self.__performance_counter.stop(), 2)
+            if command.timestamps:
+                self.__executer.done(program=signature, time=f"{elapsed_time}s")
+
+            # Log successful execution in the logger service
+            self.__logger.info(f"Command '{signature}' executed successfully in ({elapsed_time}) seconds.")
+
+            # Return the output produced by the command, if any
+            return output
+
+        except Exception as e:
+            # Display the error message in the console (without timestamp)
+            self.__console.error(f"An error occurred while executing command '{signature}': {e}", timestamp=False)
+
+            # Log the error in the logger service
+            self.__logger.error(f"Command '{signature}' execution failed: {e}")
+
+            # Calculate elapsed time and log failure with ERROR state if command.timestamps are enabled
+            elapsed_time = round(self.__performance_counter.stop(), 2)
+            if command.timestamps:
+                self.__executer.fail(program=signature, time=f"{elapsed_time}s")
+
+            # Propagate the exception after logging
+            raise
+
+    async def callAsync(
+        self,
+        signature: str,
+        args: Optional[List[str]] = None
+    ) -> Optional[Any]:
+        """
+        Executes a registered command asynchronously by its signature, optionally passing command-line arguments.
+
+        This method locates a command in the internal registry using its unique signature,
+        validates and parses any provided arguments using the command's argument parser,
+        and then executes the command's `handle` method asynchronously. It manages execution timing,
+        logging, and error handling, and returns any output produced by the command.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature identifier of the command to execute.
+        args : Optional[List[str]], default None
+            List of command-line arguments to pass to the command. If None, no arguments are provided.
+
+        Returns
+        -------
+        Optional[Any]
+            The output produced by the command's `handle` method if execution is successful.
+            Returns None if the command does not produce a result or if an error occurs.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the command with the specified signature is not found in the registry.
+        SystemExit
+            If argument parsing fails due to invalid arguments provided (raised by argparse).
+        Exception
+            Propagates any exception raised during command execution after logging and error output.
+
+        Notes
+        -----
+        - Logs execution start, completion, and errors with timestamps if enabled.
+        - Handles argument parsing and injects parsed arguments into the command instance.
+        - All exceptions are logged and displayed in the console.
+        """
+
+        # Retrieve the command from the registry by its signature
+        command: Command = self.__commands.get(signature)
+        if command is None:
+            raise CLIOrionisValueError(f"Command '{signature}' not found.")
+
+        # Start execution timer for performance measurement
+        self.__performance_counter.start()
+
+        # Log the command execution start with RUNNING state if timestamps are enabled
+        if command.timestamps:
             self.__executer.running(program=signature)
 
         try:
+            # Instantiate the command class using the application container
+            command_instance: IBaseCommand = self.__app.make(command.obj)
 
-            # Create an instance of the command class and execute it
-            command_instance: IBaseCommand = self.__app.make(command_class)
+            # Inject parsed arguments into the command instance
+            command_instance._args = self.__parseArgs(command, args)
 
-            # If arguments were parsed, set them on the command instance
-            if isinstance(parsed_args, argparse.Namespace):
-                command_instance._args = vars(parsed_args)
-            elif isinstance(parsed_args, dict):
-                command_instance._args = parsed_args
-            else:
-                command_instance._args = {}
+            # Execute the command's handle method asynchronously and capture its output
+            output = await self.__app.callAsync(command_instance, 'handle')
 
-            # Call the handle method of the command instance
-            output = self.__app.call(command_instance, 'handle')
-
-            # Log the command execution completion with DONE state
-            elapsed_time = round(time.perf_counter() - start_time, 2)
-            if timestamps:
+            # Calculate elapsed time and log completion with DONE state if command.timestamps are enabled
+            elapsed_time = round(self.__performance_counter.stop(), 2)
+            if command.timestamps:
                 self.__executer.done(program=signature, time=f"{elapsed_time}s")
 
-            # Log the command execution success
+            # Log successful execution in the logger service
             self.__logger.info(f"Command '{signature}' executed successfully in ({elapsed_time}) seconds.")
 
-            # If the command has a return value or output, return it
-            if output is not None:
-                return output
+            # Return the output produced by the command, if any
+            return output
 
         except Exception as e:
 
-            # Display the error message in the console
+            # Display the error message in the console (without timestamp)
             self.__console.error(f"An error occurred while executing command '{signature}': {e}", timestamp=False)
 
             # Log the error in the logger service
             self.__logger.error(f"Command '{signature}' execution failed: {e}")
 
-            # Log the command execution failure with ERROR state
-            elapsed_time = round(time.perf_counter() - start_time, 2)
-            if timestamps:
-                self.__executer.fail(program=signature, time=f"{elapsed_time}s")
+            # Calculate elapsed time and log failure with ERROR state if command.timestamps are enabled
+            elapsed_time = round(self.__performance_counter.stop(), 2)
+            if command.timestamps:
+                self.__executer.fail(program=signature, time=f"{elapsed_time}s")
+
+            # Propagate the exception after logging
+            raise

orionis-0.476.0/orionis/console/enums/command.py

@@ -0,0 +1,43 @@
+import argparse
+from dataclasses import dataclass
+from typing import Type, Optional
+from orionis.support.entities.base import BaseEntity
+
+@dataclass(kw_only=True)
+class Command(BaseEntity):
+    """
+    Represents a console command and its associated metadata.
+
+    Parameters
+    ----------
+    obj : Type
+        The type or class associated with the command.
+    timestamps : bool
+        Whether timestamps are enabled for this command.
+    signature : str
+        The signature string representing the command usage.
+    description : str
+        A brief description of what the command does.
+    args : Optional[argparse.ArgumentParser], optional
+        Optional argument parser for command-line arguments.
+
+    Returns
+    -------
+    Command
+        An instance of the Command class containing metadata and configuration for a console command.
+    """
+
+    # The type or class associated with the command
+    obj: Type
+
+    # Indicates if timestamps are enabled for this command
+    timestamps: bool
+
+    # The command usage signature
+    signature: str
+
+    # Description of the command's purpose
+    description: str
+
+    # Optional argument parser for command-line arguments
+    args: Optional[argparse.ArgumentParser] = None

orionis-0.476.0/orionis/console/enums/task.py

@@ -0,0 +1,42 @@
+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