cmd2 2.6.2__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

cmd2/string_utils.py

@@ -0,0 +1,166 @@
+"""Provides string utility functions.
+
+This module offers a collection of string utility functions built on the Rich library.
+These utilities are designed to correctly handle strings with ANSI style sequences and
+full-width characters (like those used in CJK languages).
+"""
+
+from rich.align import AlignMethod
+from rich.style import StyleType
+from rich.text import Text
+
+from . import rich_utils as ru
+
+
+def align(
+    val: str,
+    align: AlignMethod,
+    width: int | None = None,
+    character: str = " ",
+) -> str:
+    """Align string to a given width.
+
+    There are convenience wrappers around this function: align_left(), align_center(), and align_right()
+
+    :param val: string to align
+    :param align: one of "left", "center", or "right".
+    :param width: Desired width. Defaults to width of the terminal.
+    :param character: Character to pad with. Defaults to " ".
+
+    """
+    if width is None:
+        width = ru.console_width()
+
+    text = Text.from_ansi(val)
+    text.align(align, width=width, character=character)
+    return ru.rich_text_to_string(text)
+
+
+def align_left(
+    val: str,
+    width: int | None = None,
+    character: str = " ",
+) -> str:
+    """Left-align string to a given width.
+
+    :param val: string to align
+    :param width: Desired width. Defaults to width of the terminal.
+    :param character: Character to pad with. Defaults to " ".
+
+    """
+    return align(val, "left", width=width, character=character)
+
+
+def align_center(
+    val: str,
+    width: int | None = None,
+    character: str = " ",
+) -> str:
+    """Center-align string to a given width.
+
+    :param val: string to align
+    :param width: Desired width. Defaults to width of the terminal.
+    :param character: Character to pad with. Defaults to " ".
+
+    """
+    return align(val, "center", width=width, character=character)
+
+
+def align_right(
+    val: str,
+    width: int | None = None,
+    character: str = " ",
+) -> str:
+    """Right-align string to a given width.
+
+    :param val: string to align
+    :param width: Desired width. Defaults to width of the terminal.
+    :param character: Character to pad with. Defaults to " ".
+
+    """
+    return align(val, "right", width=width, character=character)
+
+
+def stylize(val: str, style: StyleType) -> str:
+    """Apply an ANSI style to a string, preserving any existing styles.
+
+    :param val: string to be styled
+    :param style: style instance or style definition to apply.
+    :return: the stylized string
+    """
+    # Convert to a Rich Text object to parse and preserve existing ANSI styles.
+    text = Text.from_ansi(val)
+    text.stylize(style)
+    return ru.rich_text_to_string(text)
+
+
+def strip_style(val: str) -> str:
+    """Strip all ANSI style sequences from a string.
+
+    :param val: string to be stripped
+    :return: the stripped string
+    """
+    return ru.ANSI_STYLE_SEQUENCE_RE.sub("", val)
+
+
+def str_width(val: str) -> int:
+    """Return the display width of a string.
+
+    This is intended for single-line strings.
+    Replace tabs with spaces before calling this.
+
+    :param val: the string being measured
+    :return: width of the string when printed to the terminal
+    """
+    text = Text.from_ansi(val)
+    return text.cell_len
+
+
+def is_quoted(val: str) -> bool:
+    """Check if a string is quoted.
+
+    :param val: the string being checked for quotes
+    :return: True if a string is quoted
+    """
+    from . import constants
+
+    return len(val) > 1 and val[0] == val[-1] and val[0] in constants.QUOTES
+
+
+def quote(val: str) -> str:
+    """Quote a string."""
+    quote = "'" if '"' in val else '"'
+
+    return quote + val + quote
+
+
+def quote_if_needed(val: str) -> str:
+    """Quote a string if it contains spaces and isn't already quoted."""
+    if is_quoted(val) or ' ' not in val:
+        return val
+
+    return quote(val)
+
+
+def strip_quotes(val: str) -> str:
+    """Strip outer quotes from a string.
+
+     Applies to both single and double quotes.
+
+    :param val:  string to strip outer quotes from
+    :return: same string with potentially outer quotes stripped
+    """
+    if is_quoted(val):
+        val = val[1:-1]
+    return val
+
+
+def norm_fold(val: str) -> str:
+    """Normalize and casefold Unicode strings for saner comparisons.
+
+    :param val: input unicode string
+    :return: a normalized and case-folded version of the input string
+    """
+    import unicodedata
+
+    return unicodedata.normalize("NFC", val).casefold()

cmd2/styles.py

@@ -0,0 +1,72 @@
+"""Defines custom Rich styles and their corresponding names for cmd2.
+
+This module provides a centralized and discoverable way to manage Rich styles
+used within the cmd2 framework. It defines a StrEnum for style names and a
+dictionary that maps these names to their default style objects.
+
+**Notes**
+
+Cmd2 uses Rich for its terminal output, and while this module defines a set of
+cmd2-specific styles, it's important to understand that these aren't the only
+styles that can appear. Components like Rich tracebacks and the rich-argparse
+library, which cmd2 uses for its help output, also apply their own built-in
+styles. Additionally, app developers may use other Rich objects that have
+their own default styles.
+
+For a complete theming experience, you can create a custom theme that includes
+styles from Rich and rich-argparse. The `cmd2.rich_utils.set_theme()` function
+automatically updates rich-argparse's styles with any custom styles provided in
+your theme dictionary, so you don't have to modify them directly.
+
+You can find Rich's default styles in the `rich.default_styles` module.
+For rich-argparse, the style names are defined in the
+`rich_argparse.RichHelpFormatter.styles` dictionary.
+
+"""
+
+import sys
+
+from rich.style import (
+    Style,
+    StyleType,
+)
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    from backports.strenum import StrEnum
+
+from .colors import Color
+
+
+class Cmd2Style(StrEnum):
+    """An enumeration of the names of custom Rich styles used in cmd2.
+
+    Using this enum allows for autocompletion and prevents typos when
+    referencing cmd2-specific styles.
+
+    This StrEnum is tightly coupled with `DEFAULT_CMD2_STYLES`. Any name
+    added here must have a corresponding style definition there.
+    """
+
+    COMMAND_LINE = "cmd2.example"  # Command line examples in help text
+    ERROR = "cmd2.error"  # Error text (used by perror())
+    EXCEPTION_TYPE = "cmd2.exception.type"  # Used by pexcept to mark an exception type
+    HELP_HEADER = "cmd2.help.header"  # Help table header text
+    HELP_LEADER = "cmd2.help.leader"  # Text right before the help tables are listed
+    SUCCESS = "cmd2.success"  # Success text (used by psuccess())
+    TABLE_BORDER = "cmd2.table_border"  # Applied to cmd2's table borders
+    WARNING = "cmd2.warning"  # Warning text (used by pwarning())
+
+
+# Default styles used by cmd2. Tightly coupled with the Cmd2Style enum.
+DEFAULT_CMD2_STYLES: dict[str, StyleType] = {
+    Cmd2Style.COMMAND_LINE: Style(color=Color.CYAN, bold=True),
+    Cmd2Style.ERROR: Style(color=Color.BRIGHT_RED),
+    Cmd2Style.EXCEPTION_TYPE: Style(color=Color.DARK_ORANGE, bold=True),
+    Cmd2Style.HELP_HEADER: Style(color=Color.BRIGHT_GREEN, bold=True),
+    Cmd2Style.HELP_LEADER: Style(color=Color.CYAN, bold=True),
+    Cmd2Style.SUCCESS: Style(color=Color.GREEN),
+    Cmd2Style.TABLE_BORDER: Style(color=Color.BRIGHT_GREEN),
+    Cmd2Style.WARNING: Style(color=Color.BRIGHT_YELLOW),
+}

cmd2/terminal_utils.py

@@ -0,0 +1,144 @@
+r"""Support for terminal control escape sequences.
+
+These are used for things like setting the window title and asynchronous alerts.
+"""
+
+from . import string_utils as su
+
+#######################################################
+# Common ANSI escape sequence constants
+#######################################################
+ESC = '\x1b'
+CSI = f'{ESC}['
+OSC = f'{ESC}]'
+BEL = '\a'
+
+
+####################################################################################
+# Utility functions which create various ANSI sequences
+####################################################################################
+def set_title_str(title: str) -> str:
+    """Generate a string that, when printed, sets a terminal's window title.
+
+    :param title: new title for the window
+    :return: the set title string
+    """
+    return f"{OSC}2;{title}{BEL}"
+
+
+def clear_screen_str(clear_type: int = 2) -> str:
+    """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:
+                       0 - clear from cursor to end of screen
+                       1 - clear from cursor to beginning of the screen
+                       2 - clear entire screen
+                       3 - clear entire screen and delete all lines saved in the scrollback buffer
+    :return: the clear screen string
+    :raises ValueError: if clear_type is not a valid value
+    """
+    if 0 <= clear_type <= 3:
+        return f"{CSI}{clear_type}J"
+    raise ValueError("clear_type must in an integer from 0 to 3")
+
+
+def clear_line_str(clear_type: int = 2) -> str:
+    """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:
+                       0 - clear from cursor to the end of the line
+                       1 - clear from cursor to beginning of the line
+                       2 - clear entire line
+    :return: the clear line string
+    :raises ValueError: if clear_type is not a valid value
+    """
+    if 0 <= clear_type <= 2:
+        return f"{CSI}{clear_type}K"
+    raise ValueError("clear_type must in an integer from 0 to 2")
+
+
+####################################################################################
+# Implementations intended for direct use (do NOT use outside of cmd2)
+####################################################################################
+class Cursor:
+    """Create ANSI sequences to alter the cursor position."""
+
+    @staticmethod
+    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:  # 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:  # 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:  # 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:  # noqa: N802
+        """Set the cursor position to coordinates which are 1-based."""
+        return f"{CSI}{y};{x}H"
+
+
+def async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_offset: int, alert_msg: str) -> str:
+    """Calculate the desired string, including ANSI escape codes, for displaying an asynchronous alert message.
+
+    :param terminal_columns: terminal width (number of columns)
+    :param prompt: current onscreen prompt
+    :param line: current contents of the Readline line buffer
+    :param cursor_offset: the offset of the current cursor position within line
+    :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 ['']
+
+    # Calculate how many terminal lines are taken up by all prompt lines except for the last one.
+    # That will be included in the input lines calculations since that is where the cursor is.
+    num_prompt_terminal_lines = 0
+    for prompt_line in prompt_lines[:-1]:
+        prompt_line_width = su.str_width(prompt_line)
+        num_prompt_terminal_lines += int(prompt_line_width / terminal_columns) + 1
+
+    # Now calculate how many terminal lines are take up by the input
+    last_prompt_line = prompt_lines[-1]
+    last_prompt_line_width = su.str_width(last_prompt_line)
+
+    input_width = last_prompt_line_width + su.str_width(line)
+
+    num_input_terminal_lines = int(input_width / terminal_columns) + 1
+
+    # Get the cursor's offset from the beginning of the first input line
+    cursor_input_offset = last_prompt_line_width + cursor_offset
+
+    # Calculate what input line the cursor is on
+    cursor_input_line = int(cursor_input_offset / terminal_columns) + 1
+
+    # Create a string that when printed will clear all input lines and display the alert
+    terminal_str = ''
+
+    # Move the cursor down to the last input line
+    if cursor_input_line != num_input_terminal_lines:
+        terminal_str += Cursor.DOWN(num_input_terminal_lines - cursor_input_line)
+
+    # Clear each line from the bottom up so that the cursor ends up on the first prompt line
+    total_lines = num_prompt_terminal_lines + num_input_terminal_lines
+    terminal_str += (clear_line_str() + Cursor.UP(1)) * (total_lines - 1)
+
+    # Clear the first prompt line
+    terminal_str += clear_line_str()
+
+    # Move the cursor to the beginning of the first prompt line and print the alert
+    terminal_str += '\r' + alert_msg
+    return terminal_str

cmd2/transcript.py

@@ -18,10 +18,8 @@ from typing import (
     cast,
 )
 
-from . import (
-    ansi,
-    utils,
-)
+from . import string_utils as su
+from . import utils
 
 if TYPE_CHECKING:  # pragma: no cover
     from cmd2 import (
@@ -36,7 +34,7 @@ class Cmd2TestCase(unittest.TestCase):
     that will execute the commands in a transcript file and expect the
     results shown.
 
-    See example.py
+    See transcript_example.py
     """
 
     cmdapp: Optional['Cmd'] = None
@@ -76,13 +74,13 @@ class Cmd2TestCase(unittest.TestCase):
 
         line_num = 0
         finished = False
-        line = ansi.strip_style(next(transcript))
+        line = su.strip_style(next(transcript))
         line_num += 1
         while not finished:
             # Scroll forward to where actual commands begin
             while not line.startswith(self.cmdapp.visible_prompt):
                 try:
-                    line = ansi.strip_style(next(transcript))
+                    line = su.strip_style(next(transcript))
                 except StopIteration:
                     finished = True
                     break
@@ -108,14 +106,14 @@ class Cmd2TestCase(unittest.TestCase):
             result = self.cmdapp.stdout.read()
             stop_msg = 'Command indicated application should quit, but more commands in transcript'
             # Read the expected result from transcript
-            if ansi.strip_style(line).startswith(self.cmdapp.visible_prompt):
+            if su.strip_style(line).startswith(self.cmdapp.visible_prompt):
                 message = f'\nFile {fname}, line {line_num}\nCommand was:\n{command}\nExpected: (nothing)\nGot:\n{result}\n'
                 assert not result.strip(), message  # noqa: S101
                 # If the command signaled the application to quit there should be no more commands
                 assert not stop, stop_msg  # noqa: S101
                 continue
             expected_parts = []
-            while not ansi.strip_style(line).startswith(self.cmdapp.visible_prompt):
+            while not su.strip_style(line).startswith(self.cmdapp.visible_prompt):
                 expected_parts.append(line)
                 try:
                     line = next(transcript)