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

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/console/args/parser.py

@@ -1,6 +1,40 @@
+import argparse
+
 class ArgumentPaser():
 
-    def __init__(self, args: dict):
-        self.__args = args
+    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.
 
-    def 
+        Returns
+        -------
+        Namespace
+            An object containing the parsed arguments as attributes.
+        """
+        return self.__parser.parse_args(args)

orionis/console/base/command.py

@@ -1,92 +1,147 @@
-from typing import Any, Dict
+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 console commands in Orionis.
+    Abstract base class for implementing console commands in the Orionis framework.
 
-    Inherits from Console and ProgressBar, allowing commands to:
-    - Display messages, errors, and formatted text in the console.
-    - Manage progress bars for long-running tasks.
-    - Access and manipulate parsed arguments from the command line.
+    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
     ----------
-    args : dict
-        Dictionary containing the parsed arguments for the command. Set via the setArgs method.
+    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()
-        Must be implemented by each subclass to define the main logic of the command.
-    argument(key)
-        Retrieves the value of a specific argument by key.
-    arguments()
-        Returns all parsed arguments as a dictionary.
+        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.
     """
 
-    args: Dict[str, Any] = {}
+    # 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):
         """
-        Main entry point for command execution.
+        Execute the main command logic.
 
-        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 and progress bar methods as needed.
+        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.
 
-        Example:
-            def handle(self):
-                self.write("Processing...")
-                value = self.argument("key")
-                # custom logic
+        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 in the base class. Subclasses must implement this method.
+            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):
+    def argument(self, key: str, default: Any = None) -> Any:
         """
-        Retrieves the value of a specific argument by its key.
+        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
-            Name of the argument to retrieve.
+            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 or None
-            Value associated with the key, or None if it does not exist or arguments are not set.
+        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 key is not a string or if arguments are not a dictionary.
-
-        Example:
-            value = self.argument("user")
+            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.
         """
-        if not isinstance(key, str):
-            raise ValueError("Argument key must be a string.")
-        if not isinstance(self.args, dict):
-            raise ValueError("Arguments must be a dictionary.")
-        return self.args.get(key)
 
-    def arguments(self) -> dict:
-        """
-        Returns all parsed arguments as a dictionary.
+        # 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.")
 
-        Returns
-        -------
-        dict
-            Dictionary containing all arguments received by the command. If no arguments, returns an empty dictionary.
+        # 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.")
 
-        Example:
-            args = self.arguments()
-        """
-        return dict(self.args) if isinstance(self.args, dict) else {}
+        # Safely retrieve the argument value with optional default fallback
+        return self._args.get(key, default)