cmd2 2.5.11__py3-none-any.whl → 2.6.0__py3-none-any.whl

cmd2/__init__.py

@@ -1,26 +1,19 @@
-#
-# -*- coding: utf-8 -*-
-# flake8: noqa F401
-"""This simply imports certain things for backwards compatibility."""
-
-import sys
+"""Import certain things for backwards compatibility."""
 
+import argparse
+import contextlib
 import importlib.metadata as importlib_metadata
+import sys
 
-try:
+with contextlib.suppress(importlib_metadata.PackageNotFoundError):
     __version__ = importlib_metadata.version(__name__)
-except importlib_metadata.PackageNotFoundError:  # pragma: no cover
-    # package is not installed
-    pass
-
-from typing import List
 
 from .ansi import (
-    Cursor,
     Bg,
-    Fg,
+    Cursor,
     EightBitBg,
     EightBitFg,
+    Fg,
     RgbBg,
     RgbFg,
     TextStyle,
@@ -36,20 +29,18 @@ from .argparse_custom import (
 
 # Check if user has defined a module that sets a custom value for argparse_custom.DEFAULT_ARGUMENT_PARSER.
 # Do this before loading cmd2.Cmd class so its commands use the custom parser.
-import argparse
-
 cmd2_parser_module = getattr(argparse, 'cmd2_parser_module', None)
 if cmd2_parser_module is not None:
     import importlib
 
     importlib.import_module(cmd2_parser_module)
 
+from . import plugin
 from .argparse_completer import set_default_ap_completer_type
-
 from .cmd2 import Cmd
 from .command_definition import CommandSet, with_default_category
 from .constants import COMMAND_NAME, DEFAULT_SHORTCUTS
-from .decorators import with_argument_list, with_argparser, with_category, as_subcommand_to
+from .decorators import as_subcommand_to, with_argparser, with_argument_list, with_category
 from .exceptions import (
     Cmd2ArgparseError,
     CommandSetRegistrationError,
@@ -57,13 +48,11 @@ from .exceptions import (
     PassThroughException,
     SkipPostcommandHooks,
 )
-from . import plugin
 from .parsing import Statement
 from .py_bridge import CommandResult
-from .utils import categorize, CompletionMode, CustomCompletionSettings, Settable
-
+from .utils import CompletionMode, CustomCompletionSettings, Settable, categorize
 
-__all__: List[str] = [
+__all__: list[str] = [  # noqa: RUF022
     'COMMAND_NAME',
     'DEFAULT_SHORTCUTS',
     # ANSI Exports

cmd2/ansi.py

@@ -1,7 +1,6 @@
-# coding=utf-8
-"""
-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
@@ -12,7 +11,6 @@ from enum import (
 from typing import (
     IO,
     Any,
-    List,
     Optional,
     cast,
 )
@@ -31,18 +29,18 @@ BEL = '\a'
 
 
 class AllowStyle(Enum):
-    """Values for ``cmd2.ansi.allow_style``"""
+    """Values for ``cmd2.ansi.allow_style``."""
 
     ALWAYS = 'Always'  # Always output ANSI style sequences
     NEVER = 'Never'  # Remove ANSI style sequences from all output
     TERMINAL = 'Terminal'  # Remove ANSI style sequences if the output is not going to the terminal
 
     def __str__(self) -> str:
-        """Return value instead of enum name for printing in cmd2's set command"""
+        """Return value instead of enum name for printing in cmd2's set command."""
         return str(self.value)
 
     def __repr__(self) -> str:
-        """Return quoted value instead of enum description for printing in cmd2's set command"""
+        """Return quoted value instead of enum description for printing in cmd2's set command."""
         return repr(self.value)
 
 
@@ -85,8 +83,7 @@ RGB_BG_RE = re.compile(rf'{ESC}\[48;2(?:;(?:1?[0-9]?[0-9]?|2[0-4][0-9]|25[0-5]))
 
 
 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
@@ -95,8 +92,8 @@ 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.
 
@@ -110,9 +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.
@@ -130,8 +128,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
@@ -145,8 +142,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
@@ -155,8 +151,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:
@@ -173,8 +168,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:
@@ -193,69 +187,65 @@ def clear_line(clear_type: int = 2) -> str:
 # Base classes which are not intended to be used directly
 ####################################################################################
 class AnsiSequence:
-    """Base class to create ANSI sequence strings"""
+    """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)
 
 
 class FgColor(AnsiSequence):
-    """Base class for ANSI Sequences which set foreground text color"""
-
-    pass
+    """Base class for ANSI Sequences which set foreground text color."""
 
 
 class BgColor(AnsiSequence):
-    """Base class for ANSI Sequences which set background text color"""
-
-    pass
+    """Base class for ANSI Sequences which set background text color."""
 
 
 ####################################################################################
-# Implementations intended for direct use
+# Implementations intended for direct use (do NOT use outside of cmd2)
 ####################################################################################
 class Cursor:
-    """Create ANSI sequences to alter the cursor position"""
+    """Create ANSI sequences to alter the cursor position."""
 
     @staticmethod
-    def UP(count: int = 1) -> str:
-        """Move the cursor up a specified amount of lines (Defaults to 1)"""
+    def UP(count: int = 1) -> str:  # noqa: N802
+        """Move the cursor up a specified amount of lines (Defaults to 1)."""
         return f"{CSI}{count}A"
 
     @staticmethod
-    def DOWN(count: int = 1) -> str:
-        """Move the cursor down a specified amount of lines (Defaults to 1)"""
+    def DOWN(count: int = 1) -> str:  # noqa: N802
+        """Move the cursor down a specified amount of lines (Defaults to 1)."""
         return f"{CSI}{count}B"
 
     @staticmethod
-    def FORWARD(count: int = 1) -> str:
-        """Move the cursor forward a specified amount of lines (Defaults to 1)"""
+    def FORWARD(count: int = 1) -> str:  # noqa: N802
+        """Move the cursor forward a specified amount of lines (Defaults to 1)."""
         return f"{CSI}{count}C"
 
     @staticmethod
-    def BACK(count: int = 1) -> str:
-        """Move the cursor back a specified amount of lines (Defaults to 1)"""
+    def BACK(count: int = 1) -> str:  # noqa: N802
+        """Move the cursor back a specified amount of lines (Defaults to 1)."""
         return f"{CSI}{count}D"
 
     @staticmethod
-    def SET_POS(x: int, y: int) -> str:
-        """Set the cursor position to coordinates which are 1-based"""
+    def SET_POS(x: int, y: int) -> str:  # noqa: N802
+        """Set the cursor position to coordinates which are 1-based."""
         return f"{CSI}{y};{x}H"
 
 
 class TextStyle(AnsiSequence, Enum):
-    """Create text style ANSI sequences"""
+    """Create text style ANSI sequences."""
 
     # Resets all styles and colors of text
     RESET_ALL = 0
@@ -278,17 +268,17 @@ 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}"
+        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.
     """
@@ -313,17 +303,17 @@ 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}"
+        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.
     """
@@ -348,17 +338,17 @@ 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}"
+        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.
     """
@@ -621,17 +611,17 @@ 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}"
+        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.
     """
@@ -894,23 +884,22 @@ 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}"
+        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
@@ -923,23 +912,22 @@ class RgbFg(FgColor):
         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}"
+        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
@@ -952,10 +940,10 @@ class RgbBg(BgColor):
         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}"
+        e.g. my_str = f"{RgbBg(100, 255, 27)}hello{Bg.RESET}".
         """
         return self._sequence
 
@@ -972,8 +960,8 @@ 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.
 
@@ -992,11 +980,11 @@ def style(
     :raises TypeError: if bg isn't None or a subclass of BgColor
     :return: the stylized string
     """
-    # List of strings that add style
-    additions: List[AnsiSequence] = []
+    # list of strings that add style
+    additions: list[AnsiSequence] = []
 
-    # List of strings that remove style
-    removals: List[AnsiSequence] = []
+    # list of strings that remove style
+    removals: list[AnsiSequence] = []
 
     # Process the style settings
     if fg is not None:
@@ -1062,7 +1050,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 ['']