From a9341e45b90ff1c09b5e04f7d0b258d331d7c477 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Tue, 13 May 2025 15:25:17 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`interac?=
 =?UTF-8?q?tive-mode`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @ArchooD2.

* https://github.com/ArchooD2/snaparg/pull/11#issuecomment-2876923122

The following files were modified:

* `snaparg/snaparg.py`
* `snaparg/snaparg_interactive.py`
---
 snaparg/snaparg.py             | 35 ++++++++++++++++++++++++++++++++++
 snaparg/snaparg_interactive.py |  4 ++--
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/snaparg/snaparg.py b/snaparg/snaparg.py
index 0534355..825da03 100644
--- a/snaparg/snaparg.py
+++ b/snaparg/snaparg.py
@@ -16,6 +16,11 @@
 
 class SnapArgumentParser(argparse.ArgumentParser):
     def __init__(self, *args, **kwargs):
+        """
+        Initializes the SnapArgumentParser with enhanced defaults.
+        
+        Sets a custom help formatter with increased help position width and, for Python 3.12+, enables exit on error by default.
+        """
         if sys.version_info > (3, 11):
             kwargs.setdefault("exit_on_error", True)
         kwargs.setdefault(
@@ -24,6 +29,11 @@ def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
     def add_argument(self, *args, **kwargs):
+        """
+        Adds a command-line argument, with enhanced support for enum types.
+        
+        If the argument type is an enum.Enum subclass, sets the metavar to display valid enum member names and ensures input values are parsed as enum members, raising an error for invalid values.
+        """
         arg_type = kwargs.get("type")
         if isinstance(arg_type, type) and issubclass(arg_type, enum.Enum):
             kwargs.setdefault("metavar", "[" + "|".join(e.name for e in arg_type) + "]")
@@ -41,10 +51,25 @@ def parse_enum(s):
         return super().add_argument(*args, **kwargs)
 
     def get_registered_actions(self):
+        """
+        Returns a list of argument actions that have associated option strings.
+        
+        Only actions representing options (i.e., those with flags like '--foo') are included.
+        """
         return [a for a in self._actions if a.option_strings]
 
 
     def _autofix_arguments(self, suggestions, raw_args):
+        """
+        Replaces mistyped arguments in the input list with their suggested corrections.
+        
+        Args:
+            suggestions: A list of (wrong, right) argument string pairs indicating corrections.
+            raw_args: The original list of command-line argument strings.
+        
+        Returns:
+            A new list of arguments with mistyped entries replaced by their suggested corrections.
+        """
         fixed_args = []
         for arg in raw_args:
             for wrong, right in suggestions:
@@ -56,6 +81,11 @@ def _autofix_arguments(self, suggestions, raw_args):
         return fixed_args
 
     def parse_args(self, args=None, namespace=None):
+        """
+        Parses command-line arguments and checks for missing required options.
+        
+        If any required option arguments are missing after parsing, raises an error listing them.
+        """
         parsed_args = super().parse_args(args, namespace)
         # Check for missing required arguments
         missing = []
@@ -69,6 +99,11 @@ def parse_args(self, args=None, namespace=None):
         return parsed_args
 
     def error(self, message):
+        """
+        Handles command-line parsing errors with enhanced, colorized messages and suggestions.
+        
+        If a required argument value is missing, displays the expected type and usage tips. For mistyped flags, suggests corrections or automatically fixes them if '--autofix' is present, then exits the program.
+        """
         valid_options = []
         for action in self.get_registered_actions():
             if action.option_strings:
diff --git a/snaparg/snaparg_interactive.py b/snaparg/snaparg_interactive.py
index 6a8191b..72a0610 100644
--- a/snaparg/snaparg_interactive.py
+++ b/snaparg/snaparg_interactive.py
@@ -3,9 +3,9 @@
 
 def interactive_parse(parser: SnapArgumentParser):
     """
-    Parses command-line arguments, interactively prompting for missing required arguments.
+    Parses command-line arguments, interactively prompting for any missing required values.
     
-    If required arguments are missing, prompts the user to enter values for them, validates the input, and then returns the fully parsed arguments.
+    If required arguments are missing from the command line, prompts the user to input them, validates and converts the input as needed, and returns the parsed arguments.
     """
     try:
         return parser.parse_args()