orionis 0.1.0__py3-none-any.whl

orionis/luminate/console/output/styles.py

@@ -0,0 +1,95 @@
+from enum import Enum
+
+class ANSIColors(Enum):
+    """
+    ANSI escape codes for text and background styling in the terminal.
+
+    This Enum provides color codes for text styling in console applications,
+    including foreground (TEXT), background (BG), bold (TEXT_BOLD), and
+    additional text styles like underlining.
+
+    Attributes
+    ----------
+    DEFAULT : str
+        Resets all colors and styles to default terminal settings.
+
+    Background Colors
+    -----------------
+    BG_INFO : str
+        Blue background, typically used for informational messages.
+    BG_ERROR : str
+        Red background, typically used for error messages.
+    BG_WARNING : str
+        Yellow background, typically used for warnings.
+    BG_SUCCESS : str
+        Green background, typically used for success messages.
+
+    Foreground Colors
+    -----------------
+    TEXT_INFO : str
+        Blue text, typically used for informational messages.
+    TEXT_ERROR : str
+        Bright red text, typically used for errors.
+    TEXT_WARNING : str
+        Yellow text, typically used for warnings.
+    TEXT_SUCCESS : str
+        Green text, typically used for success messages.
+    TEXT_WHITE : str
+        White text, useful for contrast.
+    TEXT_MUTED : str
+        Gray text, typically used for secondary/muted information.
+
+    Bold Foreground Colors
+    ----------------------
+    TEXT_BOLD_INFO : str
+        Bold blue text for informational emphasis.
+    TEXT_BOLD_ERROR : str
+        Bold red text for error emphasis.
+    TEXT_BOLD_WARNING : str
+        Bold yellow text for warning emphasis.
+    TEXT_BOLD_SUCCESS : str
+        Bold green text for success emphasis.
+    TEXT_BOLD_WHITE : str
+        Bold white text for strong contrast.
+    TEXT_BOLD_MUTED : str
+        Bold gray text for muted yet emphasized information.
+
+    Additional Text Styles
+    ----------------------
+    TEXT_BOLD : str
+        Bold text style.
+    TEXT_STYLE_UNDERLINE : str
+        Underlined text for emphasis.
+    TEXT_RESET : str
+        Resets text styles to default settings.
+    """
+
+    DEFAULT = '\033[0m'                 # Reset all colors and styles
+
+    # Background Colors
+    BG_INFO = '\033[44m'                # Blue background for INFO
+    BG_ERROR = '\033[41m'               # Red background for ERROR
+    BG_FAIL = '\033[48;5;166m'          # Red background for FAIL
+    BG_WARNING = '\033[43m'             # Yellow background for WARNING
+    BG_SUCCESS = '\033[42m'             # Green background for SUCCESS
+
+    # Foreground Text Colors
+    TEXT_INFO = '\033[34m'              # Blue for informational messages
+    TEXT_ERROR = '\033[91m'             # Bright red for errors
+    TEXT_WARNING = '\033[33m'           # Yellow for warnings
+    TEXT_SUCCESS = '\033[32m'           # Green for success
+    TEXT_WHITE = '\033[97m'             # White text
+    TEXT_MUTED = '\033[90m'             # Gray (muted) text
+
+    # Bold Foreground Text Colors
+    TEXT_BOLD_INFO = '\033[1;34m'       # Bold blue for INFO
+    TEXT_BOLD_ERROR = '\033[1;91m'      # Bold red for ERROR
+    TEXT_BOLD_WARNING = '\033[1;33m'    # Bold yellow for WARNING
+    TEXT_BOLD_SUCCESS = '\033[1;32m'    # Bold green for SUCCESS
+    TEXT_BOLD_WHITE = '\033[1;97m'      # Bold white text
+    TEXT_BOLD_MUTED = '\033[1;90m'      # Bold gray (muted) text
+
+    # Additional Text Styles
+    TEXT_BOLD = "\033[1m"               # Bold text
+    TEXT_STYLE_UNDERLINE = '\033[4m'    # Underline text
+    TEXT_RESET = "\033[0m"              # Reset styles

orionis/luminate/console/parser.py

@@ -0,0 +1,159 @@
+import shlex
+import types
+import argparse
+from io import StringIO
+from contextlib import redirect_stderr
+from orionis.luminate.contracts.console.parser_interface import IParser
+
+class Parser(IParser):
+    """
+    A command-line argument parser using argparse.
+
+    This class provides methods for dynamically registering arguments,
+    parsing positional and keyword arguments, and handling errors gracefully.
+
+    Attributes
+    ----------
+    argparse : argparse.ArgumentParser
+        The argument parser instance used for defining and parsing arguments.
+    args : list
+        A list storing the command-line arguments to be parsed.
+    kwargs : dict
+        A dictionary containing keyword arguments.
+    registered_arguments : set
+        A set tracking registered argument names to prevent duplicates.
+    """
+
+    def __init__(self, vars: dict, args: tuple, kwargs: dict):
+        """
+        Initializes the Parser class.
+
+        Parameters
+        ----------
+        vars : dict
+            A dictionary containing additional variables.
+        args : tuple
+            A tuple containing command-line arguments.
+        kwargs : dict
+            A dictionary containing keyword arguments.
+        """
+        self.argparse = argparse.ArgumentParser(description='Orionis Commands Argument Parser')
+        self.vars = vars or {}
+        self.args = list(args)
+        self.kwargs = kwargs or {}
+        self.registered_arguments = set()
+        self.parsed_arguments = []
+
+    def setArguments(self, arguments: list):
+        """
+        Registers command-line arguments dynamically.
+
+        Parameters
+        ----------
+        arguments : list of tuple
+            A list of tuples where each tuple contains:
+            - str: The argument name (e.g., '--value')
+            - dict: A dictionary of options (e.g., {'type': int, 'required': True})
+
+        Raises
+        ------
+        ValueError
+            If an argument is already registered.
+        """
+        for arg, options in arguments:
+            if arg in self.registered_arguments:
+                raise ValueError(f"Duplicate argument detected: {arg}")
+            self.argparse.add_argument(arg, **options)
+            self.registered_arguments.add(arg)
+
+    def _validateType(self, value):
+        """
+        Validates that a value is not an instance of a class, function, or lambda.
+
+        Parameters
+        ----------
+        value : any
+            The value to be validated.
+
+        Raises
+        ------
+        ValueError
+            If the value is a class instance, function, or lambda.
+        """
+        if isinstance(value, (types.FunctionType, types.LambdaType, type)):
+            raise ValueError("Command arguments cannot be functions, lambdas, or class instances.")
+
+    def recognize(self):
+        """
+        Processes and formats command-line arguments before parsing.
+
+        Raises
+        ------
+        ValueError
+            If an argument does not follow the correct format.
+        """
+
+        # If `args` is a single list inside a list, extract it
+        if isinstance(self.args, list) and len(self.args) == 1 and isinstance(self.args[0], list):
+            all_args:list = self.args[0]
+            first_arg:str = all_args[0]
+
+            if first_arg.endswith('.py') or first_arg in ['orionis']:
+                self.args = all_args[1:]
+            else:
+                self.args = all_args
+
+        # Merge `kwargs` with `vars`
+        if isinstance(self.vars, dict):
+            self.kwargs = {**self.vars, **self.kwargs}
+        else:
+            self.args = [self.vars, *self.args]
+
+        # Process each argument in `args`
+        formatted_args = []
+        for arg in self.args:
+            self._validateType(arg)
+
+            arg = str(arg).strip()
+            if arg.startswith('--') and '=' in arg[2:]:
+                formatted_args.append(arg)
+            else:
+                raise ValueError(f'Unrecognized argument: "{arg}". Expected format: --key="value"')
+
+        # Convert `kwargs` to `--key=value` format
+        for key, value in self.kwargs.items():
+            self._validateType(value)
+            formatted_args.append(f'--{key}={shlex.quote(str(value))}')
+
+        # Replace args with processed version
+        self.parsed_arguments = formatted_args
+
+    def get(self):
+        """
+        Parses the collected command-line arguments.
+
+        Returns
+        -------
+        argparse.Namespace
+            The parsed arguments as an object where each argument is an attribute.
+
+        Raises
+        ------
+        ValueError
+            If required arguments are missing or an error occurs during parsing,
+            it raises a customized error message including the original argparse error.
+        """
+        stderr_capture = StringIO()
+
+        try:
+            with redirect_stderr(stderr_capture):
+                return self.argparse.parse_args(self.parsed_arguments)
+
+        except SystemExit:
+            error_message = stderr_capture.getvalue().strip()
+            array_message = error_message.split('error: ')
+            final_message = str(array_message[1]).replace('unrecognized', 'Unrecognized')
+            raise ValueError(f"Argument parsing failed | {final_message} | Required arguments: {', '.join(self.registered_arguments)}")
+
+        except Exception as e:
+            raise ValueError(f"An unexpected error occurred while parsing arguments: {str(e)}")

orionis/luminate/console/register.py

@@ -0,0 +1,98 @@
+from orionis.luminate.console.base.command import BaseCommand
+from orionis.luminate.cache.console.commands import CacheCommands
+from orionis.luminate.contracts.console.register_interface import IRegister
+
+class Register(IRegister):
+    """
+    A class to register and manage command classes.
+
+    Attributes
+    ----------
+    commands : dict
+        A dictionary storing registered command classes.
+    """
+
+    def __init__(self, cache : CacheCommands = None):
+        """
+        Initializes the Register instance and prepares the cache commands system.
+        """
+        self.cache_commands = cache or CacheCommands()
+
+    def command(self, command_class):
+        """
+        Registers a command class after validating its structure.
+
+        Parameters
+        ----------
+        command_class : type
+            The command class to register. It must:
+            - Have a 'signature' attribute (str, containing only letters, numbers, and ':', with no spaces).
+            - Have a 'description' attribute (str).
+            - Implement a 'handle' method.
+            - Inherit from 'BaseCommand'.
+
+        Returns
+        -------
+        type
+            The registered command class.
+
+        Raises
+        ------
+        ValueError
+            If 'signature' is missing, invalid, contains spaces, or is not a string.
+            If 'description' is missing or not a string.
+            If 'handle' method is missing.
+        TypeError
+            If the class does not inherit from 'BaseCommand'.
+        """
+
+        # Ensure 'command_class' is actually a class
+        if not isinstance(command_class, type):
+            raise TypeError(f"Expected a class, but got {type(command_class).__name__}.")
+
+        # Validate 'signature' attribute
+        if not hasattr(command_class, 'signature') or not isinstance(command_class.signature, str):
+            raise ValueError(f"Class {command_class.__name__} must have a 'signature' attribute as a string.")
+
+        # Sanitaze signature
+        signature = command_class.signature.strip()
+
+        # Ensure signature contains only letters, numbers, and ':', with no spaces
+        if not signature or ' ' in signature or not all(c.isalnum() or c == ":" for c in signature):
+            raise ValueError(f"Invalid signature format: '{signature}'. Only letters, numbers, and ':' are allowed, with no spaces.")
+
+        # Validate 'description' attribute
+        if not hasattr(command_class, 'description') or not isinstance(command_class.description, str):
+            raise ValueError(f"Class {command_class.__name__} must have a 'description' attribute as a string.")
+
+        # Sanitaze signature
+        description = command_class.description.strip()
+
+        # Validate 'handle' method
+        if not hasattr(command_class, 'handle') or not callable(getattr(command_class, 'handle')):
+            raise ValueError(f"Class {command_class.__name__} must implement a 'handle' method.")
+
+        # Validate 'arguments' method
+        if hasattr(command_class, 'arguments') and callable(getattr(command_class, 'arguments')):
+            arguments = command_class().arguments()
+        else:
+            arguments = []
+
+        # Validate inheritance from 'BaseCommand'
+        if not issubclass(command_class, BaseCommand):
+            raise TypeError(f"Class {command_class.__name__} must inherit from 'BaseCommand'.")
+
+        # Register the command
+        self.cache_commands.register(
+            instance=command_class,
+            arguments=arguments,
+            description=description,
+            signature=signature
+        )
+
+        # Return Class
+        return command_class
+
+
+# Return Decorator.
+register = Register()

orionis/luminate/console/runner.py

@@ -0,0 +1,126 @@
+import time
+from orionis.luminate.facades.log import Log
+from orionis.luminate.console.output.console import Console
+from orionis.luminate.console.output.executor import Executor
+from orionis.luminate.pipelines.cli_pipeline import CLIPipeline
+from orionis.luminate.console.command_filter import CommandFilter
+from orionis.luminate.contracts.console.runner_interface import ICLIRunner
+
+class CLIRunner(ICLIRunner):
+    """
+    CLIRunner manages the execution of CLI commands in Orionis.
+
+    This class:
+    - Parses command-line arguments or function parameters.
+    - Executes commands through the `CLIPipeline`.
+    - Logs execution status and errors.
+
+    Methods
+    -------
+    handle(signature: str = None, vars: dict = {}, *args, **kwargs)
+        Processes and executes a CLI command based on provided arguments.
+    """
+
+    @staticmethod
+    def handle(signature: str = None, vars: dict = {}, *args, **kwargs):
+        """
+        Processes and executes a CLI command.
+
+        This method:
+        - Determines whether the command is invoked from `sys.argv` or as a function.
+        - Extracts the command signature and arguments.
+        - Executes the command pipeline.
+        - Logs execution status and handles errors.
+
+        Parameters
+        ----------
+        signature : str, optional
+            The command signature (default is None, meaning it is extracted from `sys.argv`).
+        vars : dict, optional
+            Named arguments for the command (default is an empty dictionary).
+        *args
+            Additional arguments for the command.
+        **kwargs
+            Additional keyword arguments for the command.
+
+        Returns
+        -------
+        Any
+            The output of the executed command.
+
+        Raises
+        ------
+        ValueError
+            If no command signature is provided.
+        Exception
+            If an unexpected error occurs during execution.
+        """
+
+        try:
+
+            # Exclude commands from Printing
+            exclude_running = CommandFilter.isExcluded(signature)
+
+            # Determine if command is being executed from sys.argv
+            sys_argv = signature is None
+
+            # Start execution timer
+            start_time = time.perf_counter()
+
+            # Handle command signature extraction from sys.argv
+            if sys_argv:
+
+                # Extract command signature and arguments from sys.argv
+                if not args or len(args[0]) <= 1:
+                    raise ValueError("No command signature specified.")
+
+                # Extract command signature and arguments
+                args_list = args[0]
+                signature, *args = args_list[1:]
+
+            # Log command execution start
+            Log.info(f"Running command: {signature}")
+
+            if not exclude_running:
+                Executor.running(program=signature)
+
+            # Initialize command pipeline
+            pipeline = CLIPipeline().getCommand(signature)
+
+            # Parse arguments based on invocation type
+            if sys_argv:
+                pipeline.parseArguments(*args)
+            else:
+                pipeline.parseArguments(vars, *args, **kwargs)
+
+            # Execute the command
+            output = pipeline.execute()
+
+            # Log successful execution
+            Log.success(f"Command executed successfully: {signature}")
+
+            # Calculate execution time
+            if not exclude_running:
+                elapsed_time = round(time.perf_counter() - start_time, 2)
+                Executor.done(program=signature, time=f"{elapsed_time}s")
+
+            # Return command output
+            return output
+
+        except ValueError as e:
+
+            # Handle missing or invalid command signature
+            Log.error(f"Command failed: {signature or 'Unknown'}, Value Error: {e}")
+            if not exclude_running:
+                Console.error(message=f"Value Error: {e}")
+                elapsed_time = round(time.perf_counter() - start_time, 2)
+                Executor.fail(program=signature or "Unknown", time=f"{elapsed_time}s")
+
+        except Exception as e:
+
+            # Handle unexpected errors
+            Log.error(f"Command failed: {signature or 'Unknown'}, Execution Error: {e}")
+            if not exclude_running:
+                Console.error(message=f"Execution Error: {e}")
+                elapsed_time = round(time.perf_counter() - start_time, 2)
+                Executor.fail(program=signature or "Unknown", time=f"{elapsed_time}s")

orionis/luminate/console/scripts/management.py

@@ -0,0 +1,94 @@
+from orionis.luminate.installer.setup import Setup
+from orionis.luminate.installer.output import Output
+from orionis.luminate.installer.upgrade import Upgrade
+from orionis.luminate.contracts.console.management_interface import IManagement
+
+class Management(IManagement):
+    """
+    Management class responsible for handling framework-related operations.
+
+    This class provides methods to display the framework version, execute upgrades,
+    create new applications, and display additional information.
+
+    Attributes
+    ----------
+    output : Output
+        Instance of Output to manage command-line display messages.
+    """
+
+    def __init__(self, output = Output):
+        """
+        Initialize the Management class with an output handler.
+
+        Parameters
+        ----------
+        output : Output
+            An instance of Output to handle command-line messages.
+        """
+        self.output = output
+
+    def displayVersion(self) -> str:
+        """
+        Display the current version of the framework in ASCII format.
+
+        Returns
+        -------
+        str
+            The ASCII representation of the framework version.
+
+        Raises
+        ------
+        Exception
+            If an error occurs while generating the ASCII version output.
+        """
+        try:
+            return self.output.asciiIco()
+        except Exception as e:
+            raise RuntimeError(f"Failed to display version: {e}")
+
+    def executeUpgrade(self) -> None:
+        """
+        Execute the framework upgrade process to the latest version.
+
+        Raises
+        ------
+        Exception
+            If an error occurs during the upgrade process.
+        """
+        try:
+            Upgrade.execute()
+        except Exception as e:
+            raise RuntimeError(f"Upgrade process failed: {e}")
+
+    def createNewApp(self, name_app: str = "example-app") -> None:
+        """
+        Create a new application with the specified name.
+
+        Parameters
+        ----------
+        name_app : str, optional
+            The name of the new application (default is "example-app").
+
+        Raises
+        ------
+        Exception
+            If an error occurs during the application setup.
+        """
+        try:
+            Setup(name_app).handle()
+        except Exception as e:
+            raise RuntimeError(f"Failed to create application '{name_app}': {e}")
+
+    def displayInfo(self) -> None:
+        """
+        Display additional framework information in ASCII format.
+
+        Raises
+        ------
+        Exception
+            If an error occurs while displaying information.
+        """
+        try:
+            self.output.asciiInfo()
+        except Exception as e:
+            raise RuntimeError(f"Failed to display information: {e}")