Started refactoring docstrings to meet pydocstyle standards (#1428)

Author: tleonhardt

cmd2/__init__.py

@@ -1,4 +1,4 @@
-"""This simply imports certain things for backwards compatibility."""
+"""Import certain things for backwards compatibility."""
 
 import argparse
 import contextlib

cmd2/ansi.py

@@ -1,5 +1,6 @@
-"""Support for ANSI escape sequences which are used for things like applying style to text,
-setting the window title, and asynchronous alerts.
+"""Support for ANSI escape sequences.
+
+These are used for things like applying style to text, setting the window title, and asynchronous alerts.
 """
 
 import functools
@@ -92,6 +93,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.
+
     This is intended for single line strings. If text contains a newline, this
     function will return -1. For multiline strings, call widest_line() instead.
 
@@ -105,8 +107,10 @@ 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()
-    so it handles ANSI style sequences and has the same restrictions on non-printable characters.
+    """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
     :return: The width of the string when printed to the terminal if no errors occur.
@@ -186,14 +190,16 @@ 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
-        e.g. Fg.LIGHT_MAGENTA + "hello".
+        """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
-        e.g. "hello" + Fg.RESET.
+        """Support building an ANSI sequence string when self is the right operand.
+
+        e.g. "hello" + Fg.RESET
         """
         return str(other) + str(self)
 
@@ -262,7 +268,8 @@ 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}".
         """
@@ -271,6 +278,7 @@ def __str__(self) -> str:
 
 class Fg(FgColor, Enum):
     """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.
     """
@@ -295,7 +303,8 @@ 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}".
         """
@@ -304,6 +313,7 @@ def __str__(self) -> str:
 
 class Bg(BgColor, Enum):
     """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.
     """
@@ -328,7 +338,8 @@ 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}".
         """
@@ -337,6 +348,7 @@ def __str__(self) -> str:
 
 class EightBitFg(FgColor, Enum):
     """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.
     """
@@ -599,7 +611,8 @@ 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}".
         """
@@ -608,6 +621,7 @@ def __str__(self) -> str:
 
 class EightBitBg(BgColor, Enum):
     """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.
     """
@@ -870,7 +884,8 @@ 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}".
         """
@@ -879,6 +894,7 @@ def __str__(self) -> str:
 
 class RgbFg(FgColor):
     """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.
     """
 
@@ -896,7 +912,8 @@ 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}".
         """
@@ -905,6 +922,7 @@ def __str__(self) -> str:
 
 class RgbBg(BgColor):
     """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.
     """
 
@@ -922,7 +940,8 @@ 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}".
         """
@@ -942,6 +961,7 @@ def style(
     underline: Optional[bool] = None,
 ) -> str:
     """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.
 

cmd2/argparse_completer.py

@@ -1,4 +1,5 @@
-"""This module defines the ArgparseCompleter class which provides argparse-based tab completion to cmd2 apps.
+"""Module efines 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.
 """
 
@@ -70,13 +71,16 @@ def _build_hint(parser: argparse.ArgumentParser, arg_action: argparse.Action) ->
 
 
 def _single_prefix_char(token: str, parser: argparse.ArgumentParser) -> bool:
-    """Returns if a token is just a single flag prefix character."""
+    """Is a token just a single flag prefix character."""
     return len(token) == 1 and token[0] in parser.prefix_chars
 
 
 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,
-    then anything that looks like a flag can't be consumed as a value for it.
+    """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().
     """
     # Flags have to be at least characters
@@ -131,7 +135,8 @@ 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)}'
@@ -142,8 +147,10 @@ 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
-        be a hint about the argument being tab completed.
+        """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.
         """
@@ -241,8 +248,10 @@ 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
-            as complete or print an error if the group has already been completed
+            """Check if an argument belongs to a mutually exclusive group potenitally mark that group complete.
+
+            Either mark the 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.
             """
@@ -590,7 +599,8 @@ 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
@@ -615,7 +625,8 @@ 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.
         """
@@ -643,7 +654,8 @@ 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.
         """