orionis 0.538.0__py3-none-any.whl → 0.540.0__py3-none-any.whl

orionis/console/base/command.py

@@ -2,7 +2,7 @@ from typing import Any, Dict, List
 from orionis.console.args.argument import CLIArgument
 from orionis.console.dynamic.progress_bar import ProgressBar
 from orionis.console.output.console import Console
-from orionis.console.contracts.command import IBaseCommand
+from orionis.console.contracts.base_command import IBaseCommand
 
 class BaseCommand(Console, ProgressBar, IBaseCommand):
     """

orionis/console/base/scheduler.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from orionis.console.contracts.scheduler import IBaseScheduler
+from orionis.console.contracts.base_scheduler import IBaseScheduler
 from orionis.console.contracts.schedule import ISchedule
 from orionis.console.entities.job_error import JobError
 from orionis.console.entities.scheduler_paused import SchedulerPaused

orionis/console/contracts/base_command.py

@@ -0,0 +1,123 @@
+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.
+
+    Attributes
+    ----------
+    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
+    """
+
+    # 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] = {}
+
+    # List of CLIArgument instances defining command arguments
+    arguments: List[CLIArgument] = []
+
+    @abstractmethod
+    def handle(self) -> None:
+        """
+        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.
+
+        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
+        -------
+        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
+        ------
+        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.
+
+        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
+        """
+
+        # Abstract method placeholder - concrete implementations must override this method
+        # Each subclass should replace this pass statement with specific command logic
+        pass

orionis/console/contracts/cli_request.py

@@ -0,0 +1,85 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+class ICLIRequest(ABC):
+
+    @abstractmethod
+    def command(self) -> str:
+        """
+        Retrieve the command name associated with this CLI request.
+
+        This method provides access to the command string that was specified during
+        the initialization of the CLIRequest object. The command represents the
+        primary action or operation that should be executed based on the CLI input.
+
+        Returns
+        -------
+        str
+            The command name stored as a string. This is the exact command value
+            that was passed to the constructor during object initialization.
+
+        Notes
+        -----
+        The returned command string is immutable and represents the core action
+        identifier for this CLI request. This value is essential for determining
+        which operation should be performed by the CLI handler.
+        """
+        pass
+
+    @abstractmethod
+    def all(self) -> dict:
+        """
+        Retrieve all command line arguments as a complete dictionary.
+
+        This method provides access to the entire collection of command line arguments
+        that were passed during the initialization of the CLIRequest object. It returns
+        a reference to the internal arguments dictionary, allowing for comprehensive
+        access to all parsed CLI parameters.
+
+        Returns
+        -------
+        dict
+            A dictionary containing all the parsed command line arguments as key-value
+            pairs, where keys are argument names (str) and values are the corresponding
+            argument values of any type. If no arguments were provided during
+            initialization, returns an empty dictionary.
+
+        Notes
+        -----
+        This method returns a reference to the internal arguments dictionary rather
+        than a copy. Modifications to the returned dictionary will affect the
+        internal state of the CLIRequest object.
+        """
+        pass
+
+    @abstractmethod
+    def argument(self, name: str, default: Any = None):
+        """
+        Retrieve the value of a specific command line argument by its name.
+
+        This method provides access to individual command line arguments that were
+        passed during initialization. It safely retrieves argument values without
+        raising exceptions if the argument doesn't exist.
+
+        Parameters
+        ----------
+        name : str
+            The name of the command line argument to retrieve. This should match
+            the key used when the argument was originally parsed and stored.
+        default : Any, optional
+            The default value to return if the specified argument name does not
+            exist in the arguments dictionary. Defaults to None.
+
+        Returns
+        -------
+        Any or None
+            The value associated with the specified argument name if it exists
+            in the arguments dictionary. Returns None if the argument name is
+            not found or was not provided during CLI execution.
+
+        Notes
+        -----
+        This method uses the dictionary's get() method to safely access values,
+        ensuring that missing arguments return None rather than raising a KeyError.
+        """
+        pass

orionis/console/contracts/command.py

@@ -1,123 +1,105 @@
 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.
-
-    Attributes
-    ----------
-    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
-    """
-
-    # 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] = {}
-
-    # List of CLIArgument instances defining command arguments
-    arguments: List[CLIArgument] = []
+from orionis.console.entities.command import Command as CommandEntity
+
+class ICommand(ABC):
+
+    @abstractmethod
+    def timestamp(self, enabled: bool = True) -> 'ICommand':
+        """
+        Configure whether timestamps should be included in command output.
+
+        This method allows enabling or disabling timestamp display for the command.
+        When enabled, timestamps will be shown alongside command execution results.
+
+        Parameters
+        ----------
+        enabled : bool, default=True
+            Flag to enable or disable timestamp display. True enables timestamps,
+            False disables them.
+
+        Returns
+        -------
+        Command
+            Returns the current Command instance to allow method chaining.
+
+        Raises
+        ------
+        TypeError
+            If the enabled parameter is not a boolean value.
+        """
+        pass
+
+    @abstractmethod
+    def description(self, desc: str) -> 'ICommand':
+        """
+        Set the description for the command.
+
+        This method allows setting a descriptive text that explains what the command
+        does. The description is used for help text and documentation purposes when
+        displaying command information to users.
+
+        Parameters
+        ----------
+        desc : str
+            The description text for the command. Must be a non-empty string that
+            describes the command's purpose and functionality.
+
+        Returns
+        -------
+        Command
+            Returns the current Command instance to allow method chaining.
+
+        Raises
+        ------
+        TypeError
+            If the desc parameter is not a string value.
+        """
+        pass
 
     @abstractmethod
-    def handle(self) -> None:
+    def arguments(self, args: list) -> 'ICommand':
         """
-        Execute the main logic of the console command.
+        Set the list of CLI arguments for the 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.
+        This method configures the command-line arguments that the command will accept.
+        Each argument must be a properly configured CLIArgument instance that defines
+        the argument's name, type, validation rules, and other properties. The arguments
+        are used during command parsing to validate and process user input.
 
-        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.
+        Parameters
+        ----------
+        args : list
+            A list of CLIArgument instances that define the command's accepted arguments.
+            Each element in the list must be a valid CLIArgument object with proper
+            configuration for argument parsing and validation.
 
         Returns
         -------
-        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.
+        Command
+            Returns the current Command instance to allow method chaining and enable
+            fluent interface pattern for command configuration.
 
         Raises
         ------
-        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.
-
-        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
+        TypeError
+            If the args parameter is not a list, or if any element in the list
+            is not an instance of CLIArgument.
+        """
+        pass
+
+    @abstractmethod
+    def get(self) -> tuple[str, CommandEntity]:
         """
+        Retrieve the configured Command entity.
 
-        # Abstract method placeholder - concrete implementations must override this method
-        # Each subclass should replace this pass statement with specific command logic
+        This method constructs and returns a Command entity object that encapsulates
+        all the configuration details of the command, including its signature, concrete
+        class, method, description, arguments, and timestamp setting. The returned
+        Command entity can be used for command execution and management.
+
+        Returns
+        -------
+        CommandEntity
+            A Command entity object containing all the command's configuration details.
+        """
         pass

orionis/console/contracts/event.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 from datetime import datetime
 from orionis.console.contracts.schedule_event_listener import IScheduleEventListener
-from orionis.console.enums.event import Event as EventEntity
+from orionis.console.entities.event import Event as EventEntity
 
 class IEvent(ABC):
 

orionis/console/contracts/reactor.py

@@ -1,8 +1,48 @@
 from abc import ABC, abstractmethod
 from typing import Any, List, Optional
+from orionis.console.contracts.command import ICommand
 
 class IReactor(ABC):
 
+    @abstractmethod
+    def command(
+        self,
+        signature: str,
+        handler: Any
+    ) -> ICommand:
+        """
+        Define a new command using a fluent interface.
+
+        This method allows defining a new command with a specified signature and handler
+        function using a fluent interface pattern. The command can be further configured
+        by chaining additional method calls to set properties such as timestamps,
+        description, and arguments.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature identifier for the command. Must follow naming conventions
+            (alphanumeric characters, underscores, colons, cannot start/end with underscore
+            or colon, cannot start with a number).
+        handler : Any
+            The function or callable that will be executed when the command is invoked.
+            This should be a valid function that accepts parameters matching the command's
+            defined arguments.
+
+        Returns
+        -------
+        ICommand
+            Returns an instance of ICommand that allows further configuration of the command
+            through method chaining.
+
+        Raises
+        ------
+        TypeError
+            If the signature is not a string or if the handler is not callable.
+        ValueError
+            If the signature does not meet the required naming conventions.
+        """
+
     @abstractmethod
     def info(self) -> List[dict]:
         """