Apply automated docstring refactoring

Author: tleonhardt

cmd2/ansi.py

@@ -1,5 +1,4 @@
-"""
-Support for ANSI escape sequences which are used for things like applying style to text,
+"""Support for ANSI escape sequences which are used for things like applying style to text,
 setting the window title, and asynchronous alerts.
 """
 
@@ -83,8 +82,7 @@ def __repr__(self) -> str:
 
 
 def strip_style(text: str) -> str:
-    """
-    Strip ANSI style sequences from a string.
+    """Strip ANSI style sequences from a string.
 
     :param text: string which may contain ANSI style sequences
     :return: the same string with any ANSI style sequences removed
@@ -93,8 +91,7 @@ def strip_style(text: str) -> str:
 
 
 def style_aware_wcswidth(text: str) -> int:
-    """
-    Wrap wcswidth to make it compatible with strings that contain ANSI style sequences.
+    """Wrap wcswidth to make it compatible with strings that contain ANSI style sequences.
     This is intended for single line strings. If text contains a newline, this
     function will return -1. For multiline strings, call widest_line() instead.
 
@@ -108,8 +105,7 @@ def style_aware_wcswidth(text: str) -> int:
 
 
 def widest_line(text: str) -> int:
-    """
-    Return the width of the widest line in a multiline string. This wraps style_aware_wcswidth()
+    """Return the width of the widest line in a multiline string. This wraps style_aware_wcswidth()
     so it handles ANSI style sequences and has the same restrictions on non-printable characters.
 
     :param text: the string being measured
@@ -128,8 +124,7 @@ def widest_line(text: str) -> int:
 
 
 def style_aware_write(fileobj: IO[str], msg: str) -> None:
-    """
-    Write a string to a fileobject and strip its ANSI style sequences if required by allow_style setting
+    """Write a string to a fileobject and strip its ANSI style sequences if required by allow_style setting
 
     :param fileobj: the file object being written to
     :param msg: the string being written
@@ -143,8 +138,7 @@ def style_aware_write(fileobj: IO[str], msg: str) -> None:
 # Utility functions which create various ANSI sequences
 ####################################################################################
 def set_title(title: str) -> str:
-    """
-    Generate a string that, when printed, sets a terminal's window title.
+    """Generate a string that, when printed, sets a terminal's window title.
 
     :param title: new title for the window
     :return: the set title string
@@ -153,8 +147,7 @@ def set_title(title: str) -> str:
 
 
 def clear_screen(clear_type: int = 2) -> str:
-    """
-    Generate a string that, when printed, clears a terminal screen based on value of clear_type.
+    """Generate a string that, when printed, clears a terminal screen based on value of clear_type.
 
     :param clear_type: integer which specifies how to clear the screen (Defaults to 2)
                        Possible values:
@@ -171,8 +164,7 @@ def clear_screen(clear_type: int = 2) -> str:
 
 
 def clear_line(clear_type: int = 2) -> str:
-    """
-    Generate a string that, when printed, clears a line based on value of clear_type.
+    """Generate a string that, when printed, clears a line based on value of clear_type.
 
     :param clear_type: integer which specifies how to clear the line (Defaults to 2)
                        Possible values:
@@ -194,15 +186,13 @@ class AnsiSequence:
     """Base class to create ANSI sequence strings"""
 
     def __add__(self, other: Any) -> str:
-        """
-        Support building an ANSI sequence string when self is the left operand
+        """Support building an ANSI sequence string when self is the left operand
         e.g. Fg.LIGHT_MAGENTA + "hello"
         """
         return str(self) + str(other)
 
     def __radd__(self, other: Any) -> str:
-        """
-        Support building an ANSI sequence string when self is the right operand
+        """Support building an ANSI sequence string when self is the right operand
         e.g. "hello" + Fg.RESET
         """
         return str(other) + str(self)
@@ -272,17 +262,15 @@ class TextStyle(AnsiSequence, Enum):
     UNDERLINE_DISABLE = 24
 
     def __str__(self) -> str:
-        """
-        Return ANSI text style sequence instead of enum name
+        """Return ANSI text style sequence instead of enum name
         This is helpful when using a TextStyle in an f-string or format() call
         e.g. my_str = f"{TextStyle.UNDERLINE_ENABLE}hello{TextStyle.UNDERLINE_DISABLE}"
         """
         return f"{CSI}{self.value}m"
 
 
 class Fg(FgColor, Enum):
-    """
-    Create ANSI sequences for the 16 standard terminal foreground text colors.
+    """Create ANSI sequences for the 16 standard terminal foreground text colors.
     A terminal's color settings affect how these colors appear.
     To reset any foreground color, use Fg.RESET.
     """
@@ -307,17 +295,15 @@ class Fg(FgColor, Enum):
     RESET = 39
 
     def __str__(self) -> str:
-        """
-        Return ANSI color sequence instead of enum name
+        """Return ANSI color sequence instead of enum name
         This is helpful when using an Fg in an f-string or format() call
         e.g. my_str = f"{Fg.BLUE}hello{Fg.RESET}"
         """
         return f"{CSI}{self.value}m"
 
 
 class Bg(BgColor, Enum):
-    """
-    Create ANSI sequences for the 16 standard terminal background text colors.
+    """Create ANSI sequences for the 16 standard terminal background text colors.
     A terminal's color settings affect how these colors appear.
     To reset any background color, use Bg.RESET.
     """
@@ -342,17 +328,15 @@ class Bg(BgColor, Enum):
     RESET = 49
 
     def __str__(self) -> str:
-        """
-        Return ANSI color sequence instead of enum name
+        """Return ANSI color sequence instead of enum name
         This is helpful when using a Bg in an f-string or format() call
         e.g. my_str = f"{Bg.BLACK}hello{Bg.RESET}"
         """
         return f"{CSI}{self.value}m"
 
 
 class EightBitFg(FgColor, Enum):
-    """
-    Create ANSI sequences for 8-bit terminal foreground text colors. Most terminals support 8-bit/256-color mode.
+    """Create ANSI sequences for 8-bit terminal foreground text colors. Most terminals support 8-bit/256-color mode.
     The first 16 colors correspond to the 16 colors from Fg and behave the same way.
     To reset any foreground color, including 8-bit, use Fg.RESET.
     """
@@ -615,17 +599,15 @@ class EightBitFg(FgColor, Enum):
     GRAY_93 = 255
 
     def __str__(self) -> str:
-        """
-        Return ANSI color sequence instead of enum name
+        """Return ANSI color sequence instead of enum name
         This is helpful when using an EightBitFg in an f-string or format() call
         e.g. my_str = f"{EightBitFg.SLATE_BLUE_1}hello{Fg.RESET}"
         """
         return f"{CSI}38;5;{self.value}m"
 
 
 class EightBitBg(BgColor, Enum):
-    """
-    Create ANSI sequences for 8-bit terminal background text colors. Most terminals support 8-bit/256-color mode.
+    """Create ANSI sequences for 8-bit terminal background text colors. Most terminals support 8-bit/256-color mode.
     The first 16 colors correspond to the 16 colors from Bg and behave the same way.
     To reset any background color, including 8-bit, use Bg.RESET.
     """
@@ -888,23 +870,20 @@ class EightBitBg(BgColor, Enum):
     GRAY_93 = 255
 
     def __str__(self) -> str:
-        """
-        Return ANSI color sequence instead of enum name
+        """Return ANSI color sequence instead of enum name
         This is helpful when using an EightBitBg in an f-string or format() call
         e.g. my_str = f"{EightBitBg.KHAKI_3}hello{Bg.RESET}"
         """
         return f"{CSI}48;5;{self.value}m"
 
 
 class RgbFg(FgColor):
-    """
-    Create ANSI sequences for 24-bit (RGB) terminal foreground text colors. The terminal must support 24-bit/true-color mode.
+    """Create ANSI sequences for 24-bit (RGB) terminal foreground text colors. The terminal must support 24-bit/true-color.
     To reset any foreground color, including 24-bit, use Fg.RESET.
     """
 
     def __init__(self, r: int, g: int, b: int) -> None:
-        """
-        RgbFg initializer
+        """RgbFg initializer
 
         :param r: integer from 0-255 for the red component of the color
         :param g: integer from 0-255 for the green component of the color
@@ -917,23 +896,20 @@ def __init__(self, r: int, g: int, b: int) -> None:
         self._sequence = f"{CSI}38;2;{r};{g};{b}m"
 
     def __str__(self) -> str:
-        """
-        Return ANSI color sequence instead of enum name
+        """Return ANSI color sequence instead of enum name
         This is helpful when using an RgbFg in an f-string or format() call
         e.g. my_str = f"{RgbFg(0, 55, 100)}hello{Fg.RESET}"
         """
         return self._sequence
 
 
 class RgbBg(BgColor):
-    """
-    Create ANSI sequences for 24-bit (RGB) terminal background text colors. The terminal must support 24-bit/true-color mode.
+    """Create ANSI sequences for 24-bit (RGB) terminal background text colors. The terminal must support 24-bit/true-color.
     To reset any background color, including 24-bit, use Bg.RESET.
     """
 
     def __init__(self, r: int, g: int, b: int) -> None:
-        """
-        RgbBg initializer
+        """RgbBg initializer
 
         :param r: integer from 0-255 for the red component of the color
         :param g: integer from 0-255 for the green component of the color
@@ -946,8 +922,7 @@ def __init__(self, r: int, g: int, b: int) -> None:
         self._sequence = f"{CSI}48;2;{r};{g};{b}m"
 
     def __str__(self) -> str:
-        """
-        Return ANSI color sequence instead of enum name
+        """Return ANSI color sequence instead of enum name
         This is helpful when using an RgbBg in an f-string or format() call
         e.g. my_str = f"{RgbBg(100, 255, 27)}hello{Bg.RESET}"
         """
@@ -966,8 +941,7 @@ def style(
     strikethrough: Optional[bool] = None,
     underline: Optional[bool] = None,
 ) -> str:
-    """
-    Apply ANSI colors and/or styles to a string and return it.
+    """Apply ANSI colors and/or styles to a string and return it.
     The styling is self contained which means that at the end of the string reset code(s) are issued
     to undo whatever styling was done at the beginning.
 
@@ -1056,7 +1030,6 @@ def async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_off
     :param alert_msg: the message to display to the user
     :return: the correct string so that the alert message appears to the user to be printed above the current line.
     """
-
     # Split the prompt lines since it can contain newline characters.
     prompt_lines = prompt.splitlines() or ['']
 

cmd2/argparse_completer.py

@@ -1,5 +1,4 @@
-"""
-This module defines the ArgparseCompleter class which provides argparse-based tab completion to cmd2 apps.
+"""This module defines the ArgparseCompleter class which provides argparse-based tab completion to cmd2 apps.
 See the header of argparse_custom.py for instructions on how to use these features.
 """
 
@@ -76,8 +75,7 @@ def _single_prefix_char(token: str, parser: argparse.ArgumentParser) -> bool:
 
 
 def _looks_like_flag(token: str, parser: argparse.ArgumentParser) -> bool:
-    """
-    Determine if a token looks like a flag. Unless an argument has nargs set to argparse.REMAINDER,
+    """Determine if a token looks like a flag. Unless an argument has nargs set to argparse.REMAINDER,
     then anything that looks like a flag can't be consumed as a value for it.
     Based on argparse._parse_optional().
     """
@@ -138,8 +136,7 @@ def __init__(self, arg_action: argparse.Action) -> None:
 
 class _UnfinishedFlagError(CompletionError):
     def __init__(self, flag_arg_state: _ArgumentState) -> None:
-        """
-        CompletionError which occurs when the user has not finished the current flag
+        """CompletionError which occurs when the user has not finished the current flag
         :param flag_arg_state: information about the unfinished flag action
         """
         arg = f'{argparse._get_action_name(flag_arg_state.action)}'
@@ -150,8 +147,7 @@ def __init__(self, flag_arg_state: _ArgumentState) -> None:
 
 class _NoResultsError(CompletionError):
     def __init__(self, parser: argparse.ArgumentParser, arg_action: argparse.Action) -> None:
-        """
-        CompletionError which occurs when there are no results. If hinting is allowed, then its message will
+        """CompletionError which occurs when there are no results. If hinting is allowed, then its message will
         be a hint about the argument being tab completed.
         :param parser: ArgumentParser instance which owns the action being tab completed
         :param arg_action: action being tab completed
@@ -166,8 +162,7 @@ class ArgparseCompleter:
     def __init__(
         self, parser: argparse.ArgumentParser, cmd2_app: 'Cmd', *, parent_tokens: Optional[dict[str, list[str]]] = None
     ) -> None:
-        """
-        Create an ArgparseCompleter
+        """Create an ArgparseCompleter
 
         :param parser: ArgumentParser instance
         :param cmd2_app: reference to the Cmd2 application that owns this ArgparseCompleter
@@ -207,8 +202,7 @@ def __init__(
     def complete(
         self, text: str, line: str, begidx: int, endidx: int, tokens: list[str], *, cmd_set: Optional[CommandSet] = None
     ) -> list[str]:
-        """
-        Complete text using argparse metadata
+        """Complete text using argparse metadata
 
         :param text: the string prefix we are attempting to match (all matches must begin with it)
         :param line: the current input line with leading whitespace removed
@@ -252,8 +246,7 @@ def consume_argument(arg_state: _ArgumentState) -> None:
             consumed_arg_values[arg_state.action.dest].append(token)
 
         def update_mutex_groups(arg_action: argparse.Action) -> None:
-            """
-            Check if an argument belongs to a mutually exclusive group and either mark that group
+            """Check if an argument belongs to a mutually exclusive group and either mark that group
             as complete or print an error if the group has already been completed
             :param arg_action: the action of the argument
             :raises CompletionError: if the group is already completed
@@ -501,7 +494,6 @@ def update_mutex_groups(arg_action: argparse.Action) -> None:
 
     def _complete_flags(self, text: str, line: str, begidx: int, endidx: int, matched_flags: list[str]) -> list[str]:
         """Tab completion routine for a parsers unused flags"""
-
         # Build a list of flags that can be tab completed
         match_against = []
 
@@ -535,7 +527,6 @@ def _complete_flags(self, text: str, line: str, begidx: int, endidx: int, matche
 
     def _format_completions(self, arg_state: _ArgumentState, completions: Union[list[str], list[CompletionItem]]) -> list[str]:
         """Format CompletionItems into hint table"""
-
         # Nothing to do if we don't have at least 2 completions which are all CompletionItems
         if len(completions) < 2 or not all(isinstance(c, CompletionItem) for c in completions):
             return cast(list[str], completions)
@@ -611,8 +602,7 @@ def _format_completions(self, arg_state: _ArgumentState, completions: Union[list
         return cast(list[str], completions)
 
     def complete_subcommand_help(self, text: str, line: str, begidx: int, endidx: int, tokens: list[str]) -> list[str]:
-        """
-        Supports cmd2's help command in the completion of subcommand names
+        """Supports cmd2's help command in the completion of subcommand names
         :param text: the string prefix we are attempting to match (all matches must begin with it)
         :param line: the current input line with leading whitespace removed
         :param begidx: the beginning index of the prefix text
@@ -638,8 +628,7 @@ def complete_subcommand_help(self, text: str, line: str, begidx: int, endidx: in
         return []
 
     def format_help(self, tokens: list[str]) -> str:
-        """
-        Supports cmd2's help command in the retrieval of help text
+        """Supports cmd2's help command in the retrieval of help text
         :param tokens: arguments passed to help command
         :return: help text of the command being queried
         """
@@ -668,8 +657,7 @@ def _complete_arg(
         *,
         cmd_set: Optional[CommandSet] = None,
     ) -> list[str]:
-        """
-        Tab completion routine for an argparse argument
+        """Tab completion routine for an argparse argument
         :return: list of completions
         :raises CompletionError: if the completer or choices function this calls raises one
         """
@@ -767,8 +755,7 @@ def _complete_arg(
 
 
 def set_default_ap_completer_type(completer_type: type[ArgparseCompleter]) -> None:
-    """
-    Set the default ArgparseCompleter class for a cmd2 app.
+    """Set the default ArgparseCompleter class for a cmd2 app.
 
     :param completer_type: Type that is a subclass of ArgparseCompleter.
     """