orionis 0.1.0__py3-none-any.whl

orionis/luminate/contracts/console/command_interface.py

@@ -0,0 +1,36 @@
+from typing import Any
+from abc import ABC, abstractmethod
+
+class ICommand(ABC):
+    """
+    Interface for managing and executing registered commands.
+
+    This interface ensures that any class implementing it will provide a method
+    for executing commands from a cache by their signature.
+    """
+
+    @abstractmethod
+    def call(signature: str, vars: dict[str, Any] = {}, *args: Any, **kwargs: Any) -> Any:
+        """
+        Calls a registered command from the CacheCommands singleton.
+
+        This method retrieves the command class associated with the given
+        signature, instantiates it, and executes the `handle` method of
+        the command instance.
+
+        Parameters
+        ----------
+        signature : str
+            The unique identifier (signature) of the command to be executed.
+        **kwargs : dict
+            Additional keyword arguments to be passed to the command instance
+            when it is created.
+
+        Raises
+        ------
+        KeyError
+            If no command with the given signature is found in the cache.
+        RuntimeError
+            If an error occurs while executing the command.
+        """
+        pass

orionis/luminate/contracts/console/console_interface.py

@@ -0,0 +1,305 @@
+from abc import ABC, abstractmethod
+
+class IConsole(ABC):
+    """
+    Interface for console utility operations, ensuring consistent method definitions.
+
+    Provides methods to print success, info, warning, and error messages with
+    optional timestamps, as well as general text formatting methods.
+    """
+
+    # ---- SUCCESS ----
+    @abstractmethod
+    def success(message: str = '', timestamp: bool = True):
+        """
+        Prints a success message with a green background.
+
+        Parameters
+        ----------
+        message : str, optional
+            The success message to print (default is '').
+        timestamp : bool, optional
+            Whether to include a timestamp (default is True).
+        """
+        pass
+
+    @abstractmethod
+    def textSuccess(message: str = ''):
+        """Prints a success message in green."""
+        pass
+
+    @abstractmethod
+    def textSuccessBold(message: str = ''):
+        """Prints a bold success message in green."""
+        pass
+
+    # ---- INFO ----
+    @abstractmethod
+    def info(message: str = '', timestamp: bool = True):
+        """Prints an informational message with a blue background."""
+        pass
+
+    @abstractmethod
+    def textInfo(message: str = ''):
+        """Prints an informational message in blue."""
+        pass
+
+    @abstractmethod
+    def textInfoBold(message: str = ''):
+        """Prints a bold informational message in blue."""
+        pass
+
+    # ---- WARNING ----
+    @abstractmethod
+    def warning(message: str = '', timestamp: bool = True):
+        """Prints a warning message with a yellow background."""
+        pass
+
+    @abstractmethod
+    def textWarning(message: str = ''):
+        """Prints a warning message in yellow."""
+        pass
+
+    @abstractmethod
+    def textWarningBold(message: str = ''):
+        """Prints a bold warning message in yellow."""
+        pass
+
+    # ---- FAIL ----
+    @abstractmethod
+    def fail(message: str = '', timestamp: bool = True):
+        """Prints an fail message with a red background."""
+        pass
+
+    # ---- ERROR ----
+    @abstractmethod
+    def error(message: str = '', timestamp: bool = True):
+        """Prints an error message with a red background."""
+        pass
+
+    @abstractmethod
+    def textError(message: str = ''):
+        """Prints an error message in red."""
+        pass
+
+    @abstractmethod
+    def textErrorBold(message: str = ''):
+        """Prints a bold error message in red."""
+        pass
+
+    # ---- MUTED ----
+    @abstractmethod
+    def textMuted(message: str = ''):
+        """Prints a muted (gray) message."""
+        pass
+
+    @abstractmethod
+    def textMutedBold(message: str = ''):
+        """Prints a bold muted (gray) message."""
+        pass
+
+    # ---- UNDERLINE ----
+    @abstractmethod
+    def textUnderline(message: str = ''):
+        """
+        Prints an underlined message.
+
+        Parameters
+        ----------
+        message : str, optional
+            The message to print (default is '').
+        """
+        pass
+
+    # ---- CLEAR CONSOLE ----
+    @abstractmethod
+    def clear():
+        """Clears the console screen."""
+        pass
+
+    @abstractmethod
+    def clearLine():
+        """Clears the current console line."""
+        pass
+
+    # ---- EMPTY LINE CONSOLE ----
+    @abstractmethod
+    def line(message: str = ''):
+        """Prints a line of text."""
+        pass
+
+    @abstractmethod
+    def newLine(count: int = 1):
+        """
+        Prints multiple new lines.
+
+        Parameters
+        ----------
+        count : int, optional
+            The number of new lines to print (default is 1).
+
+        Raises
+        ------
+        ValueError
+            If count is less than or equal to 0.
+        """
+        pass
+
+    # ---- WRITE CONSOLE ----
+    @abstractmethod
+    def write(message: str = ''):
+        """
+        Prints a message without moving to the next line.
+
+        Parameters
+        ----------
+        message : str, optional
+            The message to print (default is '').
+        """
+        pass
+
+    @abstractmethod
+    def writeLine(message: str = ''):
+        """
+        Prints a message and moves to the next line.
+
+        Parameters
+        ----------
+        message : str, optional
+            The message to print (default is '').
+        """
+        pass
+
+    @abstractmethod
+    def ask(question: str) -> str:
+        """
+        Prompts the user for input with a message and returns the user's response.
+
+        Parameters
+        ----------
+        question : str
+            The question to ask the user.
+
+        Returns
+        -------
+        str
+            The user's input, as a string.
+        """
+        pass
+
+    @abstractmethod
+    def confirm(question: str, default: bool = False) -> bool:
+        """
+        Asks a confirmation question and returns True or False based on the user's response.
+
+        Parameters
+        ----------
+        question : str
+            The confirmation question to ask.
+        default : bool, optional
+            The default response if the user presses Enter without typing a response.
+            Default is False, which corresponds to a 'No' response.
+
+        Returns
+        -------
+        bool
+            The user's response, which will be True if 'Y' is entered,
+            or False if 'N' is entered or the default is used.
+        """
+        pass
+
+    @abstractmethod
+    def secret(question: str) -> str:
+        """
+        Prompts the user for hidden input, typically used for password input.
+
+        Parameters
+        ----------
+        question : str
+            The prompt to ask the user.
+
+        Returns
+        -------
+        str
+            The user's hidden input, returned as a string.
+        """
+        pass
+
+    @abstractmethod
+    def table(headers: list, rows: list):
+        """
+        Prints a table in the console with the given headers and rows.
+
+        Parameters
+        ----------
+        headers : list of str
+            The column headers for the table.
+        rows : list of list of str
+            The rows of the table, where each row is a list of strings representing the columns.
+
+        Notes
+        -----
+        The method calculates the maximum width of each column and formats the output accordingly. 
+        It prints a header row followed by a separator and the data rows.
+        """
+        pass
+
+    @abstractmethod
+    def anticipate(question: str, options: list, default=None):
+        """
+        Provides autocomplete suggestions based on user input.
+
+        Parameters
+        ----------
+        question : str
+            The prompt for the user.
+        options : list of str
+            The list of possible options for autocomplete.
+        default : str, optional
+            The default value if no matching option is found. Defaults to None.
+
+        Returns
+        -------
+        str
+            The chosen option or the default value.
+
+        Notes
+        -----
+        This method allows the user to input a string, and then attempts to provide
+        an autocomplete suggestion by matching the beginning of the input with the
+        available options. If no match is found, the method returns the default value
+        or the user input if no default is provided.
+        """
+        pass
+
+    @abstractmethod
+    def choice(question: str, choices: list, default_index: int = 0) -> str:
+        """
+        Allows the user to select an option from a list.
+
+        Parameters
+        ----------
+        question : str
+            The prompt for the user.
+        choices : list of str
+            The list of available choices.
+        default_index : int, optional
+            The index of the default choice (zero-based). Defaults to 0.
+
+        Returns
+        -------
+        str
+            The selected choice.
+
+        Raises
+        ------
+        ValueError
+            If `default_index` is out of the range of choices.
+
+        Notes
+        -----
+        The user is presented with a numbered list of choices and prompted to select
+        one by entering the corresponding number. If an invalid input is provided,
+        the user will be repeatedly prompted until a valid choice is made.
+        """
+        pass

orionis/luminate/contracts/console/executor_interface.py

@@ -0,0 +1,51 @@
+from abc import ABC, abstractmethod
+
+class IExecutor(ABC):
+    """
+    Interface for execution state logging.
+
+    This interface defines methods for logging different execution states:
+    "RUNNING", "DONE", and "FAIL".
+    """
+
+    @abstractmethod
+    def running(program: str, time: str = ''):
+        """
+        Logs the execution of a program in a "RUNNING" state.
+
+        Parameters
+        ----------
+        program : str
+            The name of the program being executed.
+        time : str, optional
+            The time duration of execution, default is an empty string.
+        """
+        pass
+
+    @abstractmethod
+    def done(program: str, time: str = ''):
+        """
+        Logs the execution of a program in a "DONE" state.
+
+        Parameters
+        ----------
+        program : str
+            The name of the program being executed.
+        time : str, optional
+            The time duration of execution, default is an empty string.
+        """
+        pass
+
+    @abstractmethod
+    def fail(program: str, time: str = ''):
+        """
+        Logs the execution of a program in a "FAIL" state.
+
+        Parameters
+        ----------
+        program : str
+            The name of the program being executed.
+        time : str, optional
+            The time duration of execution, default is an empty string.
+        """
+        pass

orionis/luminate/contracts/console/kernel_interface.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+from typing import Any, Tuple
+
+class ICLIKernel(ABC):
+    """
+    Interface for CLIKernel, defining the required method for handling CLI command execution.
+
+    This interface ensures that any implementing class can process CLI arguments
+    and delegate execution accordingly.
+
+    Methods
+    -------
+    handle(*args: tuple[Any, ...]) -> Any
+        Processes CLI arguments and delegates execution to the appropriate command runner.
+    """
+
+    @abstractmethod
+    def handle(self, *args: Tuple[Any, ...]) -> Any:
+        """
+        Handles CLI command execution by forwarding arguments to a command runner.
+
+        Parameters
+        ----------
+        *args : tuple[Any, ...]
+            A tuple containing CLI arguments passed from the command line.
+
+        Returns
+        -------
+        Any
+            The result of the executed command.
+        """
+        pass

orionis/luminate/contracts/console/management_interface.py

@@ -0,0 +1,63 @@
+from abc import ABC, abstractmethod
+
+class IManagement(ABC):
+    """
+    Interface defining the contract for the Management class.
+
+    This interface ensures that any implementing class provides methods for
+    displaying the framework version, upgrading the framework, creating a new
+    application, and displaying additional information.
+    """
+
+    @abstractmethod
+    def displayVersion(self) -> str:
+        """
+        Display the current version of the framework.
+
+        Returns
+        -------
+        str
+            The ASCII representation of the framework version.
+        """
+        pass
+
+    @abstractmethod
+    def executeUpgrade(self) -> None:
+        """
+        Execute the framework upgrade process to the latest version.
+
+        Raises
+        ------
+        Exception
+            If an error occurs during the upgrade process.
+        """
+        pass
+
+    @abstractmethod
+    def createNewApp(self, name_app: str) -> None:
+        """
+        Create a new application with the given name.
+
+        Parameters
+        ----------
+        name_app : str
+            The name of the new application.
+
+        Raises
+        ------
+        Exception
+            If an error occurs during the application setup.
+        """
+        pass
+
+    @abstractmethod
+    def displayInfo(self) -> None:
+        """
+        Display additional information about the framework.
+
+        Raises
+        ------
+        Exception
+            If an error occurs while displaying information.
+        """
+        pass

orionis/luminate/contracts/console/parser_interface.py

@@ -0,0 +1,76 @@
+from abc import ABC, abstractmethod
+from typing import List, Tuple, Dict, Any
+import argparse
+
+
+class IParser(ABC):
+    """
+    Interface for a command-line argument parser.
+
+    Defines the necessary methods for a command-line parser, ensuring
+    consistency across implementations.
+    """
+
+    @abstractmethod
+    def __init__(self, vars: Dict[str, Any], args: Tuple[Any, ...], kwargs: Dict[str, Any]):
+        """
+        Initializes the parser.
+
+        Parameters
+        ----------
+        vars : dict
+            A dictionary containing additional variables.
+        args : tuple
+            A tuple containing command-line arguments.
+        kwargs : dict
+            A dictionary containing keyword arguments.
+        """
+        pass
+
+    @abstractmethod
+    def setArguments(self, arguments: List[Tuple[str, Dict[str, Any]]]) -> None:
+        """
+        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.
+        """
+        pass
+
+    @abstractmethod
+    def recognize(self) -> None:
+        """
+        Processes and formats command-line arguments before parsing.
+
+        Raises
+        ------
+        ValueError
+            If an argument does not follow the correct format.
+        """
+        pass
+
+    @abstractmethod
+    def get(self) -> argparse.Namespace:
+        """
+        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.
+        """
+        pass

orionis/luminate/contracts/console/progress_bar_interface.py

@@ -0,0 +1,66 @@
+from abc import ABC, abstractmethod
+
+class IProgressBar(ABC):
+    """
+    Interface for a progress bar.
+
+    This interface defines the structure for a progress bar, enforcing
+    the implementation of methods to initialize, update, and complete
+    the progress tracking.
+
+    Methods
+    -------
+    start()
+        Initializes the progress bar and sets it to the starting state.
+    advance(increment)
+        Advances the progress bar by a specific increment.
+    finish()
+        Completes the progress bar and ensures the final state is displayed.
+    """
+
+    @abstractmethod
+    def start(self):
+        """
+        Initializes the progress bar.
+
+        This method should be implemented to set the progress bar
+        to its initial state and display the starting progress.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented in a subclass.
+        """
+        pass
+
+    @abstractmethod
+    def advance(self, increment: int):
+        """
+        Advances the progress bar by a given increment.
+
+        Parameters
+        ----------
+        increment : int
+            The amount by which the progress should be increased.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented in a subclass.
+        """
+        pass
+
+    @abstractmethod
+    def finish(self):
+        """
+        Completes the progress bar.
+
+        This method should be implemented to ensure the progress bar
+        reaches its final state and is properly displayed.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented in a subclass.
+        """
+        pass

orionis/luminate/contracts/console/register_interface.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+
+class IRegister(ABC):
+    """
+    Interface for a command register.
+    """
+
+    @abstractmethod
+    def command(self, command_class):
+        """
+        Registers a command class after validating its structure.
+
+        Parameters
+        ----------
+        command_class : type
+            The command class to register.
+
+        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'.
+        """
+        pass