orionis 0.617.0__tar.gz → 0.619.0__tar.gz

{orionis-0.617.0/orionis.egg-info → orionis-0.619.0}/PKG-INFO

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

{orionis-0.617.0 → orionis-0.619.0}/orionis/console/base/command.py

@@ -24,34 +24,6 @@ class BaseCommand(Console, ProgressBar, IBaseCommand):
 
     The class integrates with the framework's console and progress bar systems,
     allowing commands to provide rich user feedback during execution.
-
-    Attributes
-    ----------
-    timestamps : bool, default True
-        Controls whether timestamps are included in console output messages.
-        When True, all console output will be prefixed with timestamp information.
-    signature : str
-        Defines the command signature string used for command registration and
-        automatic help text generation. This should follow the framework's
-        signature format conventions.
-    description : str
-        Human-readable description of the command's purpose and functionality.
-        Used in help documentation and command listing interfaces.
-    _args : Dict[str, Any], default {}
-        Dictionary containing parsed command-line arguments and options.
-        Populated automatically by the command parser before handle() execution.
-    arguments : List[CLIArgument], default []
-        List of CLIArgument instances defining the command's accepted arguments
-        and options. Used for argument parsing and validation.
-
-    Methods
-    -------
-    handle()
-        Abstract method that must be implemented by subclasses to define the
-        main command execution logic.
-    argument(key: str)
-        Safely retrieves argument values from the parsed arguments dictionary
-        with type validation and error handling.
     """
 
     # Enable timestamps in console output by default
@@ -64,12 +36,43 @@ class BaseCommand(Console, ProgressBar, IBaseCommand):
     description: str
 
     # Dictionary to store parsed command-line arguments and options
-    _args: Dict[str, Any] = {}
+    __args: Dict[str, Any] = {}
+
+    async def options(self) -> List[CLIArgument]:
+        """
+        Defines the command-line arguments and options accepted by the command.
+
+        This asynchronous method should be overridden by subclasses to specify the list of
+        command-line arguments and options that the command supports. Each argument or option
+        should be represented as a CLIArgument object, which encapsulates details such as the
+        argument's name, type, default value, and help description.
+
+        This method enables the framework to automatically parse, validate, and document
+        the available arguments for each command, ensuring consistent user experience
+        across all commands.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        List
+            A list of CLIArgument objects, where each object describes a single
+            command-line argument or option accepted by the command. If the command
+            does not accept any arguments or options, an empty list is returned.
 
-    # List of CLIArgument instances defining command arguments
-    arguments: List[CLIArgument] = []
+        Notes
+        -----
+        Subclasses should override this method to declare their specific arguments.
+        The returned list is used by the framework for argument parsing and help
+        text generation.
+        """
 
-    def handle(self):
+        # Return an empty list by default; subclasses should override to provide arguments
+        return []
+
+    async def handle(self):
         """
         Execute the main command logic.
 
@@ -99,6 +102,70 @@ class BaseCommand(Console, ProgressBar, IBaseCommand):
         # Raise an error to enforce implementation in subclasses
         raise NotImplementedError("The 'handle' method must be implemented in the subclass.")
 
+    def setArguments(self, args: Dict[str, Any]) -> None:
+        """
+        Populate the internal arguments dictionary with parsed command-line arguments and options.
+
+        This method is intended for internal use by the command parsing mechanism to initialize
+        the internal arguments state before command execution. It assigns the provided dictionary
+        of arguments and options to the internal storage, making them accessible via the
+        `argument()` and `arguments()` methods.
+
+        Parameters
+        ----------
+        args : Dict[str, Any]
+            Dictionary containing parsed command-line arguments and options, where each key
+            represents an argument name and each value is the corresponding argument value.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It updates the internal state of the command
+            instance to reflect the provided arguments.
+
+        Raises
+        ------
+        ValueError
+            If the provided `args` parameter is not a dictionary.
+
+        Notes
+        -----
+        This method is automatically invoked by the command framework prior to the execution
+        of the `handle()` method. It should not be called directly by command implementations.
+        """
+
+        # Ensure the provided arguments are in dictionary form
+        if not isinstance(args, dict):
+            raise ValueError(f"Arguments must be a dictionary, got '{type(args).__name__}' instead.")
+
+        # Store the parsed arguments internally for later retrieval
+        self.__args = args
+
+    def arguments(self) -> Dict[str, Any]:
+        """
+        Retrieve the entire dictionary of parsed command-line arguments and options.
+
+        This method provides access to all arguments and options that have been parsed
+        and stored internally for the current command execution. It is useful for
+        scenarios where bulk access to all argument values is required, such as
+        dynamic processing or debugging.
+
+        Returns
+        -------
+        Dict[str, Any]
+            A dictionary containing all parsed command-line arguments and options,
+            where each key is the argument name and each value is the corresponding
+            argument value.
+
+        Notes
+        -----
+        The returned dictionary reflects the current state of the command's arguments.
+        Modifying the returned dictionary will affect the internal state of the command.
+        """
+
+        # Return the internal dictionary containing all parsed arguments and options
+        return self.__args
+
     def argument(self, key: str, default: Any = None) -> Any:
         """
         Retrieve the value of a specific command-line argument by key with optional default fallback.
@@ -131,7 +198,7 @@ class BaseCommand(Console, ProgressBar, IBaseCommand):
         ValueError
             If the provided key parameter is not of string type.
         ValueError
-            If the internal _args attribute is not of dictionary type, indicating
+            If the internal __args attribute is not of dictionary type, indicating
             a corrupted or improperly initialized command state.
         """
 
@@ -140,8 +207,8 @@ class BaseCommand(Console, ProgressBar, IBaseCommand):
             raise ValueError(f"Argument key must be a string, got '{type(key).__name__}' instead.")
 
         # Ensure the internal args attribute is a valid dictionary
-        if not isinstance(self._args, dict):
-            raise ValueError(f"Arguments must be a dictionary, got '{type(self._args).__name__}' instead.")
+        if not isinstance(self.__args, dict):
+            raise ValueError(f"Arguments must be a dictionary, got '{type(self.__args).__name__}' instead.")
 
         # Safely retrieve the argument value with optional default fallback
-        return self._args.get(key, default)
+        return self.__args.get(key, default)

orionis-0.619.0/orionis/console/contracts/base_command.py

@@ -0,0 +1,188 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+from orionis.console.args.argument import CLIArgument
+
+class IBaseCommand(ABC):
+    """
+    Abstract base contract for console commands in Orionis framework.
+
+    This abstract base class defines the standardized interface that all console
+    commands must implement within the Orionis framework. It provides a consistent
+    contract for command execution, argument handling, metadata storage, and console
+    output management.
+
+    The class establishes the foundation for command-line interface functionality,
+    ensuring all commands follow a uniform pattern for registration, execution,
+    and user interaction while maintaining flexibility for specific command logic
+    implementation.
+    """
+
+    # Enable timestamps in console output by default
+    timestamps: bool = True
+
+    # Command signature string for registration and help text generation
+    signature: str
+
+    # Human-readable description for documentation and help display
+    description: str
+
+    # Dictionary to store parsed command-line arguments and options
+    __args: Dict[str, Any] = {}
+
+    @abstractmethod
+    async def options(self) -> List[CLIArgument]:
+        """
+        Defines the command-line arguments and options accepted by the command.
+
+        This asynchronous method should be overridden by subclasses to specify the list of
+        command-line arguments and options that the command supports. Each argument or option
+        should be represented as a CLIArgument object, which encapsulates details such as the
+        argument's name, type, default value, and help description.
+
+        This method enables the framework to automatically parse, validate, and document
+        the available arguments for each command, ensuring consistent user experience
+        across all commands.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        List
+            A list of CLIArgument objects, where each object describes a single
+            command-line argument or option accepted by the command. If the command
+            does not accept any arguments or options, an empty list is returned.
+
+        Notes
+        -----
+        Subclasses should override this method to declare their specific arguments.
+        The returned list is used by the framework for argument parsing and help
+        text generation.
+        """
+        pass
+
+    @abstractmethod
+    async def handle(self):
+        """
+        Execute the main command logic.
+
+        This abstract method defines the entry point for command execution and must be
+        implemented by all concrete command subclasses. It serves as the primary interface
+        for running the command's core functionality after argument parsing and validation.
+
+        Returns
+        -------
+        None
+            This method does not return any value. All command output should be handled
+            through the inherited console methods or other side effects.
+
+        Raises
+        ------
+        NotImplementedError
+            Always raised when called on the base class, indicating that subclasses
+            must provide their own implementation of this method.
+
+        Notes
+        -----
+        Subclasses should override this method to implement their specific command
+        behavior. The method will be called after all command-line arguments have
+        been parsed and stored in the _args dictionary.
+        """
+        pass
+
+    @abstractmethod
+    def setArguments(self, args: Dict[str, Any]) -> None:
+        """
+        Populate the internal arguments dictionary with parsed command-line arguments and options.
+
+        This method is intended for internal use by the command parsing mechanism to initialize
+        the internal arguments state before command execution. It assigns the provided dictionary
+        of arguments and options to the internal storage, making them accessible via the
+        `argument()` and `arguments()` methods.
+
+        Parameters
+        ----------
+        args : Dict[str, Any]
+            Dictionary containing parsed command-line arguments and options, where each key
+            represents an argument name and each value is the corresponding argument value.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It updates the internal state of the command
+            instance to reflect the provided arguments.
+
+        Raises
+        ------
+        ValueError
+            If the provided `args` parameter is not a dictionary.
+
+        Notes
+        -----
+        This method is automatically invoked by the command framework prior to the execution
+        of the `handle()` method. It should not be called directly by command implementations.
+        """
+        pass
+
+    @abstractmethod
+    def arguments(self) -> Dict[str, Any]:
+        """
+        Retrieve the entire dictionary of parsed command-line arguments and options.
+
+        This method provides access to all arguments and options that have been parsed
+        and stored internally for the current command execution. It is useful for
+        scenarios where bulk access to all argument values is required, such as
+        dynamic processing or debugging.
+
+        Returns
+        -------
+        Dict[str, Any]
+            A dictionary containing all parsed command-line arguments and options,
+            where each key is the argument name and each value is the corresponding
+            argument value.
+
+        Notes
+        -----
+        The returned dictionary reflects the current state of the command's arguments.
+        Modifying the returned dictionary will affect the internal state of the command.
+        """
+        pass
+
+    @abstractmethod
+    def argument(self, key: str, default: Any = None) -> Any:
+        """
+        Retrieve the value of a specific command-line argument by key with optional default fallback.
+
+        This method provides safe and validated access to command-line arguments stored in the
+        internal arguments dictionary. It performs type checking on both the key parameter and
+        the internal _args attribute to ensure data integrity before attempting retrieval.
+
+        The method follows a fail-safe approach by returning a default value when the requested
+        argument key is not found, preventing KeyError exceptions during command execution.
+
+        Parameters
+        ----------
+        key : str
+            The string identifier used to locate the desired argument in the arguments
+            dictionary. Must be a non-empty string that corresponds to a valid argument name.
+        default : Any, optional
+            The fallback value to return if the specified key is not found in the arguments
+            dictionary. Defaults to None if not provided.
+
+        Returns
+        -------
+        Any
+            The value associated with the specified key if it exists in the arguments
+            dictionary. If the key is not found, returns the provided default value
+            or None if no default was specified.
+
+        Raises
+        ------
+        ValueError
+            If the provided key parameter is not of string type.
+        ValueError
+            If the internal __args attribute is not of dictionary type, indicating
+            a corrupted or improperly initialized command state.
+        """
+        pass

{orionis-0.617.0 → orionis-0.619.0}/orionis/console/core/reactor.py

@@ -15,6 +15,8 @@ from orionis.console.contracts.executor import IExecutor
 from orionis.console.exceptions import CLIOrionisTypeError
 from orionis.console.request.cli_request import CLIRequest
 from orionis.foundation.contracts.application import IApplication
+from orionis.services.introspection.concretes.reflection import ReflectionConcrete
+from orionis.services.introspection.instances.reflection import ReflectionInstance
 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
@@ -75,18 +77,6 @@ class Reactor(IReactor):
         # List to hold fluent command definitions
         self.__fluent_commands: List[ICommand] = []
 
-        # Load core commands immediately upon initialization
-        self.__loadCoreCommands()
-        self.__load__core_commands: bool = True
-
-        # Load custom user-defined commands from the project's commands directory
-        self.__loadCustomCommands()
-        self.__load__custom_commands: bool = True
-
-        # Flag to track if fluent commands have been loaded
-        self.__loadFluentCommands()
-        self.__load_fluent_commands: bool = True
-
     def __loadCommands(self) -> None:
         """
         Loads all available commands into the reactor's internal registry.
@@ -123,17 +113,17 @@ class Reactor(IReactor):
         """
 
         # Load core commands if they have not been loaded yet
-        if not self.__load__core_commands:
+        if not hasattr(self, '_Reactor__load__core_commands') or not self.__load__core_commands:
             self.__loadCoreCommands()
             self.__load__core_commands = True
 
         # Load custom user-defined commands if they have not been loaded yet
-        if not self.__load__custom_commands:
+        if not hasattr(self, '_Reactor__load__custom_commands') or not self.__load__custom_commands:
             self.__loadCustomCommands()
             self.__load__custom_commands = True
 
         # Load fluent interface commands if they have not been loaded yet
-        if not self.__load_fluent_commands:
+        if not hasattr(self, '_Reactor__load_fluent_commands') or not self.__load_fluent_commands:
             self.__loadFluentCommands()
             self.__load_fluent_commands = True
 
@@ -317,7 +307,7 @@ class Reactor(IReactor):
         for obj in core_commands:
 
             # Get the signature attribute from the command class
-            signature = getattr(obj, 'signature', None)
+            signature = ReflectionConcrete(obj).getAttribute('signature')
 
             # Skip if signature is not defined
             if signature is None:
@@ -501,7 +491,9 @@ class Reactor(IReactor):
 
         # Validate the signature against the required pattern
         if not re.match(pattern, obj.signature):
-            raise CLIOrionisValueError(f"Command class {obj.__name__} 'signature' must contain only alphanumeric characters, underscores (_) and colons (:), cannot start or end with underscore or colon, and cannot start with a number.")
+            raise CLIOrionisValueError(
+                f"Command class {obj.__name__} 'signature' must contain only alphanumeric characters, underscores (_) and colons (:), cannot start or end with underscore or colon, and cannot start with a number."
+            )
 
         # Return signature
         return obj.signature.strip()
@@ -553,8 +545,8 @@ class Reactor(IReactor):
         """
         Validates and processes command arguments for a command class.
 
-        This method ensures that the command class has properly formatted arguments
-        and creates an ArgumentParser instance configured with those arguments.
+        Ensures the command class provides a valid list of CLIArgument instances via its 'options' method,
+        and constructs an ArgumentParser accordingly.
 
         Parameters
         ----------
@@ -570,43 +562,53 @@ class Reactor(IReactor):
         Raises
         ------
         CLIOrionisTypeError
-            If the 'arguments' attribute is not a list or contains non-CLIArgument instances.
+            If the 'options' method does not return a list or contains non-CLIArgument instances.
         """
 
-        # Check if the command class has an arguments attribute
-        if not hasattr(obj, 'arguments'):
-            return None
+        # Instantiate the command and retrieve its options
+        instance = self.__app.make(obj)
+        options: List[CLIArgument]  = self.__app.call(instance, 'options')
 
-        # Ensure the arguments attribute is a list type
-        if not isinstance(obj.arguments, list):
-            raise CLIOrionisTypeError(f"Command class {obj.__name__} 'arguments' must be a list.")
+        # Validate that options is a list
+        if not isinstance(options, list):
+            raise CLIOrionisTypeError(
+                f"Command class {obj.__name__} 'options' must return a list."
+            )
 
-        # If arguments is empty, return None
-        if len(obj.arguments) == 0:
+        # Return None if there are no arguments
+        if not options:
             return None
 
-        # Validate that all items in the arguments list are CLIArgument instances
-        for index, value in enumerate(obj.arguments):
-            if not isinstance(value, CLIArgument):
-                raise CLIOrionisTypeError(f"Command class {obj.__name__} 'arguments' must contain only CLIArgument instances, found '{type(value).__name__}' at index {index}.")
+        # Validate all items are CLIArgument instances
+        for idx, arg in enumerate(options):
+            if not isinstance(arg, CLIArgument):
+                raise CLIOrionisTypeError(
+                    f"Command class {obj.__name__} 'options' must contain only CLIArgument instances, "
+                    f"found '{type(arg).__name__}' at index {idx}."
+                )
+
 
-        # Build the arguments dictionary from the CLIArgument instances
-        required_args: List[CLIArgument] = obj.arguments
+        # Get the Signature attribute from the command class
+        rf_concrete = ReflectionConcrete(obj)
+        signature = rf_concrete.getAttribute('signature', '<unknown>')
+        description = rf_concrete.getAttribute('description', '')
 
-        # Create an ArgumentParser instance to handle the command arguments
+        # Build the ArgumentParser
         arg_parser = argparse.ArgumentParser(
-            usage=f"python -B reactor {obj.signature} [options]",
-            description=f"Command [{obj.signature}] : {obj.description}",
+            usage=f"python -B reactor {signature} [options]",
+            description=f"Command [{signature}] : {description}",
             formatter_class=argparse.RawTextHelpFormatter,
             add_help=True,
             allow_abbrev=False,
             exit_on_error=True,
-            prog=obj.signature
+            prog=signature
         )
-        for arg in required_args:
+
+        # Add each CLIArgument to the ArgumentParser
+        for arg in options:
             arg.addToParser(arg_parser)
 
-        # Return the configured ArgumentParser
+        # Return the constructed ArgumentParser
         return arg_parser
 
     def __parseArgs(
@@ -646,13 +648,17 @@ class Reactor(IReactor):
 
         # If the command expects arguments, parse them using its ArgumentParser
         if command.args is not None and isinstance(command.args, argparse.ArgumentParser):
+
+            # If no args provided, use an empty list
             if args is None:
                 args = []
+
+            # Parse the provided arguments using the command's ArgumentParser
             try:
-                # Parse the provided arguments using the command's ArgumentParser
                 parsed_args = command.args.parse_args(args)
+
+            # Raise a CLIOrionisRuntimeError with the help message included in the exception
             except SystemExit:
-                # Raise a CLIOrionisRuntimeError with the help message included in the exception
                 raise CLIOrionisRuntimeError(
                     f"Failed to parse arguments for command '{command.signature}'.\n"
                     f"{command.args.format_help()}\n"
@@ -662,10 +668,13 @@ class Reactor(IReactor):
         # Convert the parsed arguments to a dictionary and return
         if isinstance(parsed_args, argparse.Namespace):
             return vars(parsed_args)
+
+        # If parsed_args is already a dictionary, return it directly
         elif isinstance(parsed_args, dict):
             return parsed_args
+
+        # Return an empty dictionary if no arguments were parsed
         else:
-            # Return an empty dictionary if no arguments were parsed
             return {}
 
     def command(
@@ -837,13 +846,16 @@ class Reactor(IReactor):
                 command_instance: IBaseCommand = self.__app.make(command.obj)
 
                 # Inject parsed arguments into the command instance
-                _args = self.__parseArgs(command, args)
-                command_instance._args = _args.copy()
+                dict_args = self.__parseArgs(command, args)
+
+                # Only set arguments if the command instance has a setArguments method
+                if ReflectionInstance(command_instance).hasMethod('setArguments'):
+                    command_instance.setArguments(dict_args.copy())
 
                 # Inject a scoped CLIRequest instance into the application container for the command's context
                 self.__app.scopedInstance(ICLIRequest, CLIRequest(
                     command=signature,
-                    args=_args.copy()
+                    args=dict_args.copy()
                 ))
 
                 # Execute the command's handle method and capture its output
@@ -940,13 +952,16 @@ class Reactor(IReactor):
                 command_instance: IBaseCommand = self.__app.make(command.obj)
 
                 # Inject parsed arguments into the command instance
-                _args = self.__parseArgs(command, args)
-                command_instance._args = _args.copy()
+                dict_args = self.__parseArgs(command, args)
+
+                # Only set arguments if the command instance has a setArguments method
+                if ReflectionInstance(command_instance).hasMethod('setArguments'):
+                    command_instance.setArguments(dict_args.copy())
 
                 # Inject a scoped CLIRequest instance into the application container for the command's context
                 self.__app.scopedInstance(ICLIRequest, CLIRequest(
                     command=signature,
-                    args=_args.copy()
+                    args=dict_args.copy()
                 ))
 
                 # Execute the command's handle method asynchronously and capture its output

{orionis-0.617.0 → orionis-0.619.0}/orionis/foundation/application.py

@@ -2118,6 +2118,7 @@ class Application(Container, IApplication):
         duplicate initialization. The startup time is calculated and logged
         for performance monitoring purposes.
         """
+
         # Check if already booted
         if not self.__booted:
 
@@ -2125,7 +2126,7 @@ class Application(Container, IApplication):
             self.instance(
                 IApplication,
                 self,
-                alias=f"x-{IApplication.__module__}.{IApplication.__name__}",
+                alias=f"x-orionis.foundation.contracts.application.IApplication",
                 enforce_decoupling=None
             )
 
@@ -2149,11 +2150,8 @@ class Application(Container, IApplication):
             # Calculate elapsed time in milliseconds since application start
             elapsed_ms = (time.time_ns() - self.startAt) // 1_000_000
 
-            # Compose the boot message
-            boot_message = f"Orionis Framework has been successfully booted. Startup time: {elapsed_ms} ms. Started at: {self.startAt} ns"
-
             # Log message to the logger
-            logger.info(boot_message)
+            logger.info(f"Orionis Framework has been successfully booted. Startup time: {elapsed_ms} ms. Started at: {self.startAt} ns")
 
         # Return the application instance for method chaining
         return self

{orionis-0.617.0 → orionis-0.619.0}/orionis/metadata/framework.py

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

{orionis-0.617.0 → orionis-0.619.0}/orionis/test/core/unit_test.py

@@ -1,4 +1,3 @@
-import inspect
 import io
 import json
 import logging
@@ -118,18 +117,6 @@ class UnitTest(IUnitTest):
         # Use live console output during test execution
         self.__live_console: bool = True
 
-        # Load and set internal paths for test discovery and result storage
-        self.__loadPaths()
-
-        # Load and validate the testing configuration from the application
-        self.__loadConfig()
-
-        # Discover and import test modules based on the configuration
-        self.__loadModules()
-
-        # Discover and load all test cases from the imported modules into the suite
-        self.__loadTests()
-
     def __loadPaths(
         self
     ) -> None:
@@ -737,6 +724,18 @@ class UnitTest(IUnitTest):
         # Record the start time in seconds
         performance_counter.start()
 
+        # Load and set internal paths for test discovery and result storage
+        self.__loadPaths()
+
+        # Load and validate the testing configuration from the application
+        self.__loadConfig()
+
+        # Discover and import test modules based on the configuration
+        self.__loadModules()
+
+        # Discover and load all test cases from the imported modules into the suite
+        self.__loadTests()
+
         # Length of all tests in the suite
         total_tests = self.getTestCount()