orionis 0.448.0__tar.gz → 0.450.0__tar.gz

{orionis-0.448.0/orionis.egg-info → orionis-0.450.0}/PKG-INFO

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

{orionis-0.448.0 → orionis-0.450.0}/orionis/console/args/argument.py

@@ -45,69 +45,69 @@ class CLIArgument:
     """
 
     # Required fields
-    flags: List[str] = None
-    type: Type = None
-    help: str = None
+    flags: List[str]
+    type: Type
+    help: Optional[str] = None
 
     default: Any = field(
-        default_factory = None,
-        metadata = {
+        default=None,
+        metadata={
             "description": "Default value for the argument.",
             "default": None
         }
     )
 
     choices: Optional[List[Any]] = field(
-        default_factory = None,
-        metadata = {
+        default=None,
+        metadata={
             "description": "List of valid choices for the argument.",
             "default": None
         }
     )
 
     required: bool = field(
-        default_factory = False,
-        metadata = {
+        default=False,
+        metadata={
             "description": "Indicates if the argument is required.",
             "default": False
         }
     )
 
     metavar: Optional[str] = field(
-        default_factory = None,
-        metadata = {
+        default=None,
+        metadata={
             "description": "Metavar for displaying in help messages.",
             "default": None
         }
     )
 
     dest: Optional[str] = field(
-        default_factory = None,
-        metadata = {
+        default=None,
+        metadata={
             "description": "Destination name for the argument in the namespace.",
             "default": None
         }
     )
 
     action: Union[str, ArgumentAction] = field(
-        default_factory = ArgumentAction.STORE,
-        metadata = {
+        default=ArgumentAction.STORE,
+        metadata={
             "description": "Action to perform with the argument.",
             "default": ArgumentAction.STORE.value
         }
     )
 
     nargs: Optional[Union[int, str]] = field(
-        default_factory = None,
-        metadata = {
+        default=None,
+        metadata={
             "description": "Number of arguments expected (e.g., 1, 2, '+', '*').",
             "default": None
         }
     )
 
     const: Any = field(
-        default_factory = None,
-        metadata = {
+        default=None,
+        metadata={
             "description": "Constant value for store_const or append_const actions.",
             "default": None
         }
@@ -159,7 +159,8 @@ class CLIArgument:
 
         # Auto-generate help if not provided
         if self.help is None:
-            object.__setattr__(self, 'help', f"Argument for {primary_flag}")
+            clean_flag = primary_flag.lstrip('-').replace('-', ' ').title()
+            object.__setattr__(self, 'help', f"{clean_flag} argument")
 
         # Ensure help is a string
         if not isinstance(self.help, str):
@@ -204,9 +205,7 @@ class CLIArgument:
             raise CLIOrionisValueError(f"Destination '{self.dest}' is not a valid Python identifier")
 
         # Normalize action value
-        if self.action is None:
-            object.__setattr__(self, 'action', ArgumentAction.STORE.value)
-        elif isinstance(self.action, str):
+        if isinstance(self.action, str):
             try:
                 action_enum = ArgumentAction(self.action)
                 object.__setattr__(self, 'action', action_enum.value)
@@ -217,22 +216,74 @@ class CLIArgument:
         else:
             raise CLIOrionisValueError("Action must be a string or an ArgumentAction enum value")
 
+        # Determine if this is an optional argument (starts with dash)
+        is_optional = any(flag.startswith('-') for flag in self.flags)
+
         # Special handling for boolean types
         if self.type is bool:
+            # Auto-configure action based on default value and whether it's optional
+            if is_optional:
+                action = ArgumentAction.STORE_FALSE.value if self.default else ArgumentAction.STORE_TRUE.value
+                object.__setattr__(self, 'action', action)
+                # argparse ignores type with store_true/false actions
+                object.__setattr__(self, 'type', None)
+            else:
+                # For positional boolean arguments, keep type as bool
+                pass
 
-            # Auto-configure action based on default value
-            action = ArgumentAction.STORE_TRUE.value if not self.default else ArgumentAction.STORE_FALSE.value
-            object.__setattr__(self, 'action', action)
-
-            # argparse ignores type with store_true/false actions
+        # Special handling for list types
+        elif self.type is list:
+            if self.nargs is None:
+                # Auto-configure for accepting multiple values
+                object.__setattr__(self, 'nargs', '+' if is_optional else '*')
+            # Keep type as list for proper conversion
+            object.__setattr__(self, 'type', str)  # argparse expects element type, not list
+
+        # Handle count action - typically used for verbosity flags
+        elif self.action == ArgumentAction.COUNT.value:
+            object.__setattr__(self, 'type', None)  # count action doesn't use type
+            if self.default is None:
+                object.__setattr__(self, 'default', 0)
+
+        # Handle const actions
+        if self.action in (ArgumentAction.STORE_CONST.value, ArgumentAction.APPEND_CONST.value):
+            if self.const is None:
+                # Auto-set const based on type or use True as default
+                if self.type is bool:
+                    object.__setattr__(self, 'const', True)
+                elif self.type is int:
+                    object.__setattr__(self, 'const', 1)
+                elif self.type is str:
+                    object.__setattr__(self, 'const', self.dest)
+                else:
+                    object.__setattr__(self, 'const', True)
+            object.__setattr__(self, 'type', None)  # const actions don't use type
+
+        # Handle nargs '?' - optional single argument
+        elif self.nargs == '?':
+            if self.const is None and is_optional:
+                # For optional arguments with nargs='?', set a reasonable const
+                object.__setattr__(self, 'const', True if self.type is bool else self.dest)
+
+        # Validate nargs compatibility
+        if self.nargs is not None:
+            valid_nargs = ['?', '*', '+'] + [str(i) for i in range(0, 10)]
+            if isinstance(self.nargs, int):
+                if self.nargs < 0:
+                    raise CLIOrionisValueError("nargs cannot be negative")
+            elif self.nargs not in valid_nargs:
+                raise CLIOrionisValueError(f"Invalid nargs value: {self.nargs}")
+
+        # Handle version action
+        if self.action == ArgumentAction.VERSION.value:
             object.__setattr__(self, 'type', None)
+            if 'version' not in self.dest:
+                object.__setattr__(self, 'dest', 'version')
 
-        # Special handling for list types
-        if self.type is list and self.nargs is None:
+        # Handle help action
+        if self.action == ArgumentAction.HELP.value:
+            object.__setattr__(self, 'type', None)
 
-            # Auto-configure for accepting multiple values
-            object.__setattr__(self, 'nargs', '+')
-            object.__setattr__(self, 'type', str)
 
     def addToParser(self, parser: argparse.ArgumentParser) -> None:
         """
@@ -327,17 +378,97 @@ class CLIArgument:
             "action": self.action,                      # Action to take when argument is encountered
             "nargs": self.nargs,                        # Number of command-line arguments expected
             "type": self.type,                          # Type to convert the argument to
-            "const": self.const                         # Constant value for certain actions
         }
 
-        # Filter out None values to prevent passing invalid parameters to argparse
-        # argparse will raise errors if None values are explicitly passed for certain parameters
-        kwargs = {k: v for k, v in kwargs.items() if v is not None}
-
-        # Remove 'required' parameter for positional arguments since it's not supported
-        # Positional arguments are inherently required by argparse's design
-        if is_positional and 'required' in kwargs:
-            del kwargs['required']
+        # Handle const parameter for specific actions
+        const_actions = [
+            ArgumentAction.STORE_CONST.value,
+            ArgumentAction.APPEND_CONST.value
+        ]
+
+        # Add const parameter when it's needed
+        if self.action in const_actions or (self.nargs == '?' and self.const is not None):
+            kwargs["const"] = self.const
+
+        # Special handling for version action
+        if self.action == ArgumentAction.VERSION.value and hasattr(self, 'version'):
+            kwargs["version"] = getattr(self, 'version', None)
+
+        # Define actions that don't accept certain parameters
+        type_ignored_actions = [
+            ArgumentAction.STORE_TRUE.value,
+            ArgumentAction.STORE_FALSE.value,
+            ArgumentAction.STORE_CONST.value,
+            ArgumentAction.APPEND_CONST.value,
+            ArgumentAction.COUNT.value,
+            ArgumentAction.HELP.value,
+            ArgumentAction.VERSION.value
+        ]
+
+        # Define actions that don't accept metavar or default parameters
+        metavar_ignored_actions = [
+            ArgumentAction.STORE_TRUE.value,
+            ArgumentAction.STORE_FALSE.value,
+            ArgumentAction.COUNT.value,
+            ArgumentAction.HELP.value,
+            ArgumentAction.VERSION.value
+        ]
+
+        # Define actions that don't accept default parameters
+        default_ignored_actions = [
+            ArgumentAction.STORE_TRUE.value,
+            ArgumentAction.STORE_FALSE.value,
+            ArgumentAction.STORE_CONST.value,
+            ArgumentAction.APPEND_CONST.value,
+            ArgumentAction.HELP.value,
+            ArgumentAction.VERSION.value
+        ]
+
+        # Filter out None values and incompatible parameters
+        filtered_kwargs = {}
+        for k, v in kwargs.items():
+            if v is not None:
+
+                # Skip parameters that are not compatible with certain actions
+                if k == "type" and self.action in type_ignored_actions:
+                    continue
+
+                # Skip metavar for actions that don't accept it
+                if k == "metavar" and self.action in metavar_ignored_actions:
+                    continue
+
+                # Skip default for actions that don't accept it
+                if k == "default" and self.action in default_ignored_actions:
+                    continue
+
+                # Special case: don't include empty strings for metavar in positional args
+                if k == "metavar" and is_positional and v == "":
+                    continue
+
+                # Add the parameter to the filtered kwargs
+                filtered_kwargs[k] = v
+
+        # Remove parameters that are not compatible with positional arguments
+        if is_positional:
+
+            # Remove 'required' parameter for positional arguments since it's not supported
+            if 'required' in filtered_kwargs:
+                del filtered_kwargs['required']
+
+            # Remove 'dest' parameter for positional arguments as argparse calculates it automatically
+            if 'dest' in filtered_kwargs:
+                del filtered_kwargs['dest']
+
+            # Remove 'metavar' if it's the same as the flag name (redundant)
+            if 'metavar' in filtered_kwargs and len(self.flags) == 1:
+                flag_upper = self.flags[0].upper()
+                if filtered_kwargs['metavar'] == flag_upper:
+                    del filtered_kwargs['metavar']
+
+        # For count action, ensure default is an integer
+        if self.action == ArgumentAction.COUNT.value and 'default' in filtered_kwargs:
+            if not isinstance(filtered_kwargs['default'], int):
+                filtered_kwargs['default'] = 0
 
         # Return the cleaned and validated kwargs dictionary
-        return kwargs
+        return filtered_kwargs

orionis-0.450.0/orionis/console/args/parser.py

@@ -0,0 +1,40 @@
+import argparse
+
+class ArgumentPaser():
+
+    def __init__(self):
+        self.__parser = argparse.ArgumentParser()
+
+    def addArgument(self, name: str, **kwargs):
+        """
+        Add an argument to the parser.
+
+        Parameters
+        ----------
+        name : str
+            The name of the argument to add.
+        kwargs : dict
+            Additional keyword arguments for the argument configuration.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+        self.__parser.add_argument(name, **kwargs)
+
+    def parse(self, args=None):
+        """
+        Parse the command-line arguments.
+
+        Parameters
+        ----------
+        args : list, optional
+            A list of arguments to parse. If None, uses sys.argv by default.
+
+        Returns
+        -------
+        Namespace
+            An object containing the parsed arguments as attributes.
+        """
+        return self.__parser.parse_args(args)

orionis-0.450.0/orionis/console/base/command.py

@@ -0,0 +1,147 @@
+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.base.contracts.command import IBaseCommand
+
+class BaseCommand(Console, ProgressBar, IBaseCommand):
+    """
+    Abstract base class for implementing console commands in the Orionis framework.
+
+    This class provides a foundation for creating command-line interface commands with
+    built-in console output capabilities, progress bar functionality, and argument handling.
+    It inherits from Console and ProgressBar to provide rich terminal interaction features
+    while implementing the IBaseCommand interface contract.
+
+    The BaseCommand class serves as a template that enforces a consistent structure for
+    all command implementations in the framework, requiring subclasses to implement the
+    core command logic while providing common utilities for argument access and console
+    operations.
+
+    This is an abstract base class and should not be instantiated directly.
+    All concrete command implementations must inherit from this class and
+    provide their own handle() method implementation.
+
+    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
+    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] = []
+
+    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.
+        """
+
+        # Raise an error to enforce implementation in subclasses
+        raise NotImplementedError("The 'handle' method must be implemented in the subclass.")
+
+    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.
+        """
+
+        # Validate that the key parameter is a string type
+        if not isinstance(key, str):
+            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.")
+
+        # Safely retrieve the argument value with optional default fallback
+        return self._args.get(key, default)

orionis-0.450.0/orionis/console/base/contracts/command.py

@@ -0,0 +1,125 @@
+
+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