orionis 0.448.0__py3-none-any.whl → 0.450.0__py3-none-any.whl

orionis/console/base/contracts/command.py

@@ -1,68 +1,125 @@
 
 from abc import ABC, abstractmethod
-from typing import Any, Dict
+from typing import Any, Dict, List
+
+from orionis.console.args.argument import CLIArgument
 
 class IBaseCommand(ABC):
     """
-    Abstract base contract for console commands in Orionis.
+    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.
 
-    Inherits from ABC and defines the required interface for all console commands:
-    - Stores parsed command-line arguments.
-    - Requires implementation of main execution logic and argument accessors.
+    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.
 
     Attributes
     ----------
-    args : Dict[str, Any]
-        Dictionary containing the parsed arguments for the command. Should be set by the command parser.
+    timestamps : bool, default=True
+        Controls whether timestamps are displayed in console output. When enabled,
+        all console messages will include timestamp prefixes for better debugging
+        and logging capabilities.
+    signature : str
+        The command signature string that defines the command name and expected
+        arguments format. Used for command registration in the console system
+        and automatic help text generation. Must follow the framework's signature
+        format conventions.
+    description : str
+        Human-readable description explaining the command's purpose and functionality.
+        This text is displayed in help documentation, command listings, and usage
+        instructions to assist users in understanding the command's capabilities.
+    _args : Dict[str, Any]
+        Dictionary containing parsed command-line arguments and options passed to
+        the command during execution. Populated automatically by the command parser
+        before the handle() method is called, providing structured access to all
+        user-provided input parameters.
+    arguments : List[CLIArgument]
+        List of CLIArgument instances defining the command's accepted arguments
+        and options. Used for argument parsing, validation, and help text generation.
+
+    Methods
+    -------
+    handle() -> None
+        Abstract method that must be implemented by all concrete command subclasses.
+        Contains the main execution logic specific to each command type and handles
+        argument processing, business logic execution, and output generation.
+
+    Notes
+    -----
+    - All concrete implementations must override the handle() method
+    - Command signatures should follow framework naming conventions
+    - Use self._args dictionary to access parsed command-line arguments
+    - Implement proper error handling and validation within command logic
+    - Follow single responsibility principle for maintainable command structure
+    - Utilize framework's console output methods for consistent user experience
+
+    See Also
+    --------
+    abc.ABC : Abstract base class functionality
+    typing.Dict : Type hints for argument dictionary structure
     """
 
-    args: Dict[str, Any] = {}
+    # Enable timestamps in console output by default
+    timestamps: bool = True
 
-    @abstractmethod
-    def handle(self):
-        """
-        Main entry point for command execution.
+    # Command signature string for registration and help text generation
+    signature: str
 
-        This method must be overridden in each subclass to define the specific logic of the command.
-        Access parsed arguments via self.args and use console/output methods as needed.
+    # Human-readable description for documentation and help display
+    description: str
 
-        Raises
-        ------
-        NotImplementedError
-            Always raised in the base class. Subclasses must implement this method.
-        """
-        pass
+    # Dictionary to store parsed command-line arguments and options
+    _args: Dict[str, Any] = {}
+
+    # List of CLIArgument instances defining command arguments
+    arguments: List[CLIArgument] = []
 
     @abstractmethod
-    def argument(self, key: str) -> Any:
+    def handle(self) -> None:
         """
-        Retrieves the value of a specific argument by its key.
+        Execute the main logic of the console command.
+
+        This abstract method serves as the primary entry point for command execution
+        and must be implemented by all concrete command subclasses. The method contains
+        the core business logic specific to each command type and is responsible for
+        processing the parsed arguments stored in self.args and producing the desired
+        output or side effects.
 
-        Parameters
-        ----------
-        key : str
-            Name of the argument to retrieve.
+        The implementation should access parsed command-line arguments through the
+        self.args dictionary and utilize appropriate console output methods for
+        user feedback and result presentation. Error handling and resource cleanup
+        should also be managed within this method to ensure robust command execution.
 
         Returns
         -------
-        Any or None
-            Value associated with the key, or None if it does not exist or arguments are not set.
+        None
+            This method does not return any value. All command output, results,
+            error messages, and user feedback should be handled through console
+            output methods, file operations, database transactions, or other
+            side effects rather than return values.
 
         Raises
         ------
-        ValueError
-            If the key is not a string or if arguments are not a dictionary.
-        """
-        pass
+        NotImplementedError
+            Automatically raised when this method is called on the abstract base
+            class without a concrete implementation. All subclasses must override
+            this method with their specific command logic to avoid this exception.
 
-    @abstractmethod
-    def arguments(self) -> Dict[str, Any]:
+        Notes
+        -----
+        - Access command arguments and options via the self.args dictionary
+        - Use framework's console output methods for consistent user interaction
+        - Implement comprehensive error handling and input validation
+        - Ensure proper cleanup of resources (files, connections, etc.) if needed
+        - Follow the single responsibility principle for maintainable command logic
+        - Handle both success and failure scenarios appropriately
         """
-        Returns all parsed arguments as a dictionary.
 
-        Returns
-        -------
-        dict
-            Dictionary containing all arguments received by the command. If no arguments, returns an empty dictionary.
-        """
+        # Abstract method placeholder - concrete implementations must override this method
+        # Each subclass should replace this pass statement with specific command logic
         pass

orionis/console/core/reactor.py

@@ -1,28 +1,422 @@
+import argparse
 import os
 from pathlib import Path
+import time
+from typing import 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.output.contracts.executor import IExecutor
+from orionis.console.output.executor import Executor
+from orionis.foundation.contracts.application import IApplication
 from orionis.services.introspection.modules.reflection import ReflectionModule
-
+import re
 
 class Reactor:
 
     def __init__(
-        self
+        self,
+        app: Optional[IApplication] = None
     ):
-        self.__reactors = {}
-        self.__command_path = str((Path.cwd() / 'app' / 'console' / 'commands').resolve())
-        self.__loadCommands()
+        """
+        Initializes a new Reactor instance for command discovery and management.
+
+        The Reactor constructor sets up the command processing environment by establishing
+        the application context, determining the project root directory, and automatically
+        discovering and loading command classes from the console commands directory.
+        It maintains an internal registry of discovered commands for efficient lookup
+        and execution.
+
+        Parameters
+        ----------
+        app : Optional[IApplication], default None
+            The application instance to use for command processing. If None is provided,
+            a new Orionis application instance will be created automatically. The
+            application instance provides access to configuration, paths, and other
+            framework services required for command execution.
+
+        Returns
+        -------
+        None
+            This is a constructor method and does not return any value. The instance
+            is configured with the provided or default application and populated with
+            discovered commands.
+
+        Notes
+        -----
+        - Command discovery is performed automatically during initialization
+        - The current working directory is used as the project root for module resolution
+        - Commands are loaded from the path specified by app.path('console_commands')
+        - The internal command registry is initialized as an empty dictionary before loading
+        """
+
+        # Initialize the application instance, using provided app or creating new Orionis instance
+        self.__app = app or Orionis()
+
+        # Set the project root directory to current working directory for module path resolution
+        self.__root: str = str(Path.cwd())
+
+        # Initialize the internal command registry as an empty dictionary
+        self.__commands: dict = {}
+
+        # Automatically discover and load command classes from the console commands directory
+        self.__loadCommands(str(self.__app.path('console_commands')), self.__root)
+
+        # Initialize the executor for command output management
+        self.__executer: IExecutor = self.__app.make('x-orionis.console.output.executor')
+
+    def __loadCommands(self, commands_path: str, root_path: str) -> None:
+        """
+        Loads command classes from Python files in the specified commands directory.
 
-    def __loadCommands(self):
+        This method recursively walks through the commands directory, imports Python modules,
+        and registers command classes that inherit from BaseCommand. It performs module path
+        sanitization to handle virtual environment paths and validates command structure
+        before registration.
 
-        # Base path of the project
-        root_path = str(Path.cwd())
+        Parameters
+        ----------
+        commands_path : str
+            The absolute path to the directory containing command modules to load.
+        root_path : str
+            The root path of the project, used for module path normalization.
+
+        Returns
+        -------
+        None
+            This method does not return any value. Command classes are registered
+            internally in the reactor's command registry.
+
+        Notes
+        -----
+        - Only Python files (.py extension) are processed
+        - Virtual environment paths are automatically filtered out during module resolution
+        - Command classes must inherit from BaseCommand to be registered
+        - Each discovered command class undergoes structure validation via __ensureStructure
+        """
 
         # Iterate through the command path and load command modules
-        for current_directory, _, files in os.walk(self.__command_path):
+        for current_directory, _, files in os.walk(commands_path):
             for file in files:
+
+                # Only process Python files
                 if file.endswith('.py'):
-                    pre_module = current_directory.replace(root_path, '').replace(os.sep, '.').lstrip('.')
-                    file_name = file[:-3]
-                    print(f"{pre_module}.{file_name}")
-                    rf_module = ReflectionModule(f"{pre_module}.{file_name}")
-                    print(rf_module.getClasses())
+
+                    # Sanitize the module path by converting filesystem path to Python module notation
+                    pre_module = current_directory.replace(root_path, '')\
+                                                  .replace(os.sep, '.')\
+                                                  .lstrip('.')
+
+                    # Remove virtual environment paths using regex (Windows, Linux, macOS)
+                    # Windows: venv\Lib\site-packages or venv\lib\site-packages
+                    # Linux/macOS: venv/lib/python*/site-packages
+                    pre_module = re.sub(r'[^.]*\.(?:Lib|lib)\.(?:python[^.]*\.)?site-packages\.?', '', pre_module)
+
+                    # Remove any remaining .venv or venv patterns from the module path
+                    pre_module = re.sub(r'\.?v?env\.?', '', pre_module)
+
+                    # Clean up any double dots or leading/trailing dots that may have been created
+                    pre_module = re.sub(r'\.+', '.', pre_module).strip('.')
+
+                    # Skip if module name is empty after cleaning (invalid module path)
+                    if not pre_module:
+                        continue
+
+                    # Create the reflection module path by combining sanitized path with filename
+                    rf_module = ReflectionModule(f"{pre_module}.{file[:-3]}")
+
+                    # Iterate through all classes found in the current module
+                    for name, obj in rf_module.getClasses().items():
+
+                        # Check if the class is a valid command class (inherits from BaseCommand but is not BaseCommand itself)
+                        if issubclass(obj, BaseCommand) and obj is not BaseCommand and obj is not IBaseCommand:
+
+                            # Validate the command class structure and register it
+                            timestamp = self.__ensureTimestamps(obj)
+                            signature = self.__ensureSignature(obj)
+                            description = self.__ensureDescription(obj)
+                            args = self.__ensureArguments(obj)
+
+                            # Add the command to the internal registry
+                            self.__commands[signature] = {
+                                "class": obj,
+                                "timestamps": timestamp,
+                                "signature": signature,
+                                "description": description,
+                                "args": args
+                            }
+
+    def __ensureTimestamps(self, obj: IBaseCommand) -> bool:
+        """
+        Validates that a command class has a properly formatted timestamps attribute.
+
+        This method ensures that the command class contains a 'timestamps' attribute
+        that is a boolean value, indicating whether timestamps should be included in
+        console output messages.
+
+        Parameters
+        ----------
+        obj : IBaseCommand
+            The command class instance to validate.
+
+        Returns
+        -------
+        Reactor
+            Returns self to enable method chaining for additional validation calls.
+
+        Raises
+        ------
+        ValueError
+            If the command class lacks a 'timestamps' attribute or if the attribute is not a boolean.
+        """
+
+        # Check if the command class has a timestamps attribute
+        if not hasattr(obj, 'timestamps'):
+            return False
+
+        # Ensure the timestamps attribute is a boolean type
+        if not isinstance(obj.timestamps, bool):
+            raise TypeError(f"Command class {obj.__name__} 'timestamps' must be a boolean.")
+
+        # Return timestamps value
+        return obj.timestamps
+
+    def __ensureSignature(self, obj: IBaseCommand) -> str:
+        """
+        Validates that a command class has a properly formatted signature attribute.
+
+        This method ensures that the command class contains a 'signature' attribute
+        that follows the required naming conventions for command identification.
+        The signature must be a non-empty string containing only alphanumeric
+        characters, underscores, and colons, with specific placement rules.
+
+        Parameters
+        ----------
+        obj : IBaseCommand
+            The command class instance to validate.
+
+        Returns
+        -------
+        Reactor
+            Returns self to enable method chaining.
+
+        Raises
+        ------
+        ValueError
+            If the command class lacks a 'signature' attribute, if the signature
+            is an empty string, or if the signature doesn't match the required pattern.
+        TypeError
+            If the 'signature' attribute is not a string.
+        """
+
+        # Check if the command class has a signature attribute
+        if not hasattr(obj, 'signature'):
+            raise ValueError(f"Command class {obj.__name__} must have a 'signature' attribute.")
+
+        # Ensure the signature attribute is a string type
+        if not isinstance(obj.signature, str):
+            raise TypeError(f"Command class {obj.__name__} 'signature' must be a string.")
+
+        # Validate that the signature is not empty after stripping whitespace
+        if obj.signature.strip() == '':
+            raise ValueError(f"Command class {obj.__name__} 'signature' cannot be an empty string.")
+
+        # Define the regex pattern for valid signature format
+        # Pattern allows: alphanumeric chars, underscores, colons
+        # Cannot start/end with underscore or colon, cannot start with number
+        pattern = r'^[a-zA-Z][a-zA-Z0-9_:]*[a-zA-Z0-9]$|^[a-zA-Z]$'
+
+        # Validate the signature against the required pattern
+        if not re.match(pattern, obj.signature):
+            raise ValueError(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()
+
+    def __ensureDescription(self, obj: IBaseCommand) -> str:
+        """
+        Validates that a command class has a properly formatted description attribute.
+
+        This method ensures that the command class contains a 'description' attribute
+        that provides meaningful documentation for the command. The description must
+        be a non-empty string that can be used for help documentation and command
+        listing purposes.
+
+        Parameters
+        ----------
+        obj : IBaseCommand
+            The command class instance to validate.
+
+        Returns
+        -------
+        Reactor
+            Returns self to enable method chaining for additional validation calls.
+
+        Raises
+        ------
+        ValueError
+            If the command class lacks a 'description' attribute or if the description
+            is an empty string after stripping whitespace.
+        TypeError
+            If the 'description' attribute is not a string type.
+        """
+
+        # Check if the command class has a description attribute
+        if not hasattr(obj, 'description'):
+            raise ValueError(f"Command class {obj.__name__} must have a 'description' attribute.")
+
+        # Ensure the description attribute is a string type
+        if not isinstance(obj.description, str):
+            raise TypeError(f"Command class {obj.__name__} 'description' must be a string.")
+
+        # Validate that the description is not empty after stripping whitespace
+        if obj.description.strip() == '':
+            raise ValueError(f"Command class {obj.__name__} 'description' cannot be an empty string.")
+
+        # Return description
+        return obj.description.strip()
+
+    def __ensureArguments(self, obj: IBaseCommand) -> Optional[argparse.ArgumentParser]:
+        """
+        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.
+
+        Parameters
+        ----------
+        obj : IBaseCommand
+            The command class instance to validate.
+
+        Returns
+        -------
+        Optional[argparse.ArgumentParser]
+            An ArgumentParser instance configured with the command's arguments,
+            or None if the command has no arguments.
+
+        Raises
+        ------
+        TypeError
+            If the 'arguments' attribute is not a list or contains non-CLIArgument instances.
+        """
+
+        # Check if the command class has an arguments attribute
+        if not hasattr(obj, 'arguments'):
+            return None
+
+        # Ensure the arguments attribute is a list type
+        if not isinstance(obj.arguments, list):
+            raise TypeError(f"Command class {obj.__name__} 'arguments' must be a list.")
+
+        # If arguments is empty, return None
+        if len(obj.arguments) == 0:
+            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 TypeError(f"Command class {obj.__name__} 'arguments' must contain only CLIArgument instances, found '{type(value).__name__}' at index {index}.")
+
+        # Build the arguments dictionary from the CLIArgument instances
+        required_args: List[CLIArgument] = obj.arguments
+
+        # Create an ArgumentParser instance to handle the command arguments
+        arg_parser = argparse.ArgumentParser(
+            description=f"{obj.signature} - {obj.description}",
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+            add_help=True,
+            allow_abbrev=False
+        )
+        for arg in required_args:
+            arg.addToParser(arg_parser)
+
+        # Return the configured ArgumentParser
+        return arg_parser
+
+    def call(
+        self,
+        signature: str,
+        args: Optional[List[str]] = None
+    ):
+        """
+        Executes a command by its signature with optional 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.
+
+        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.
+
+        Returns
+        -------
+        None
+            This method does not return any value. The command's handle method is called
+            directly for execution.
+
+        Raises
+        ------
+        ValueError
+            If the command with the specified signature is not found in the registry.
+        SystemExit
+            If argument parsing fails due to invalid arguments provided.
+        """
+
+        # Retrieve the command from the registry
+        command: dict = self.__commands.get(signature)
+        if command is None:
+            raise ValueError(f"Command '{signature}' not found.")
+
+        # Start execution timer
+        start_time = time.perf_counter()
+
+        # Get command details
+        command_class = command.get("class")
+        arg_parser: Optional[argparse.ArgumentParser] = command.get("args")
+        timestamps: bool = command.get("timestamps")
+
+        # Initialize parsed arguments
+        parsed_args = None
+
+        # 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
+
+        # Log the command execution start with RUNNING state
+        if timestamps:
+            self.__executer.running(program=signature)
+
+        try:
+
+            # Create an instance of the command class and execute it
+            command_instance: IBaseCommand = command_class()
+            command_instance._args = vars(parsed_args) if parsed_args else {}
+            output =  command_instance.handle(self.__app.make('x-orionis.services.inspirational.inspire'))
+
+            # Log the command execution completion with DONE state
+            if timestamps:
+                elapsed_time = round(time.perf_counter() - start_time, 2)
+                self.__executer.done(program=signature, time=f"{elapsed_time}s")
+
+            # If the command has a return value or output, return it
+            if output is not None:
+                return output
+
+        except Exception as e:
+
+            # Log the command execution failure with ERROR state
+            if timestamps:
+                elapsed_time = round(time.perf_counter() - start_time, 2)
+                self.__executer.fail(program=signature, time=f"{elapsed_time}s")