cmd2 2.4.2__py3-none-any.whl → 2.5.9__py3-none-any.whl

cmd2/rl_utils.py

@@ -2,6 +2,7 @@
 """
 Imports the proper Readline for the platform and provides utility functions for it
 """
+
 import sys
 from enum import (
     Enum,
@@ -28,19 +29,17 @@ from typing import (
 
 # Prefer statically linked gnureadline if installed due to compatibility issues with libedit
 try:
-    # noinspection PyPackageRequirements
     import gnureadline as readline  # type: ignore[import]
 except ImportError:
     # Note: If this actually fails, you should install gnureadline on Linux/Mac or pyreadline3 on Windows.
     try:
-        # noinspection PyUnresolvedReferences
         import readline  # type: ignore[no-redef]
     except ImportError:  # pragma: no cover
         pass
 
 
 class RlType(Enum):
-    """Readline library types we recognize"""
+    """Readline library types we support"""
 
     GNU = 1
     PYREADLINE = 2
@@ -70,8 +69,8 @@ if 'pyreadline3' in sys.modules:
     )
 
     # Check if we are running in a terminal
-    if sys.stdout.isatty():  # pragma: no cover
-        # noinspection PyPep8Naming,PyUnresolvedReferences
+    if sys.stdout is not None and sys.stdout.isatty():  # pragma: no cover
+
         def enable_win_vt100(handle: HANDLE) -> bool:
             """
             Enables VT100 character sequences in a Windows console
@@ -101,27 +100,18 @@ if 'pyreadline3' in sys.modules:
         # Enable VT100 sequences for stdout and stderr
         STD_OUT_HANDLE = -11
         STD_ERROR_HANDLE = -12
-        # noinspection PyUnresolvedReferences
         vt100_stdout_support = enable_win_vt100(readline.rl.console.GetStdHandle(STD_OUT_HANDLE))
-        # noinspection PyUnresolvedReferences
         vt100_stderr_support = enable_win_vt100(readline.rl.console.GetStdHandle(STD_ERROR_HANDLE))
         vt100_support = vt100_stdout_support and vt100_stderr_support
 
     ############################################################################################################
     # pyreadline3 is incomplete in terms of the Python readline API. Add the missing functions we need.
     ############################################################################################################
-    # readline.redisplay()
-    try:
-        getattr(readline, 'redisplay')
-    except AttributeError:
-        # noinspection PyProtectedMember,PyUnresolvedReferences
-        readline.redisplay = readline.rl.mode._update_line
-
     # readline.remove_history_item()
     try:
         getattr(readline, 'remove_history_item')
     except AttributeError:
-        # noinspection PyProtectedMember,PyUnresolvedReferences
+
         def pyreadline_remove_history_item(pos: int) -> None:
             """
             An implementation of remove_history_item() for pyreadline3
@@ -141,7 +131,7 @@ if 'pyreadline3' in sys.modules:
 
 elif 'gnureadline' in sys.modules or 'readline' in sys.modules:
     # We don't support libedit. See top of this file for why.
-    if 'libedit' not in readline.__doc__:
+    if readline.__doc__ is not None and 'libedit' not in readline.__doc__:
         try:
             # Load the readline lib so we can access members of it
             import ctypes
@@ -156,7 +146,7 @@ elif 'gnureadline' in sys.modules or 'readline' in sys.modules:
             rl_type = RlType.GNU
             vt100_support = sys.stdout.isatty()
 
-# Check if readline was loaded
+# Check if we loaded a supported version of readline
 if rl_type == RlType.NONE:  # pragma: no cover
     if not _rl_warn_reason:
         _rl_warn_reason = (
@@ -168,7 +158,6 @@ else:
     rl_warning = ''
 
 
-# noinspection PyProtectedMember,PyUnresolvedReferences
 def rl_force_redisplay() -> None:  # pragma: no cover
     """
     Causes readline to display the prompt and input text wherever the cursor is and start
@@ -191,7 +180,6 @@ def rl_force_redisplay() -> None:  # pragma: no cover
         readline.rl.mode._update_line()
 
 
-# noinspection PyProtectedMember, PyUnresolvedReferences
 def rl_get_point() -> int:  # pragma: no cover
     """
     Returns the offset of the current cursor position in rl_line_buffer
@@ -206,9 +194,8 @@ def rl_get_point() -> int:  # pragma: no cover
         return 0
 
 
-# noinspection PyUnresolvedReferences
 def rl_get_prompt() -> str:  # pragma: no cover
-    """Gets Readline's current prompt"""
+    """Get Readline's prompt"""
     if rl_type == RlType.GNU:
         encoded_prompt = ctypes.c_char_p.in_dll(readline_lib, "rl_prompt").value
         if encoded_prompt is None:
@@ -229,7 +216,24 @@ def rl_get_prompt() -> str:  # pragma: no cover
     return rl_unescape_prompt(prompt)
 
 
-# noinspection PyUnresolvedReferences
+def rl_get_display_prompt() -> str:  # pragma: no cover
+    """
+    Get Readline's currently displayed prompt.
+
+    In GNU Readline, the displayed prompt sometimes differs from the prompt.
+    This occurs in functions that use the prompt string as a message area, such as incremental search.
+    """
+    if rl_type == RlType.GNU:
+        encoded_prompt = ctypes.c_char_p.in_dll(readline_lib, "rl_display_prompt").value
+        if encoded_prompt is None:
+            prompt = ''
+        else:
+            prompt = encoded_prompt.decode(encoding='utf-8')
+        return rl_unescape_prompt(prompt)
+    else:
+        return rl_get_prompt()
+
+
 def rl_set_prompt(prompt: str) -> None:  # pragma: no cover
     """
     Sets Readline's prompt
@@ -246,7 +250,8 @@ def rl_set_prompt(prompt: str) -> None:  # pragma: no cover
 
 
 def rl_escape_prompt(prompt: str) -> str:
-    """Overcome bug in GNU Readline in relation to calculation of prompt length in presence of ANSI escape codes
+    """
+    Overcome bug in GNU Readline in relation to calculation of prompt length in presence of ANSI escape codes
 
     :param prompt: original prompt
     :return: prompt safe to pass to GNU Readline
@@ -285,3 +290,32 @@ def rl_unescape_prompt(prompt: str) -> str:
         prompt = prompt.replace(escape_start, "").replace(escape_end, "")
 
     return prompt
+
+
+def rl_in_search_mode() -> bool:  # pragma: no cover
+    """Check if readline is doing either an incremental (e.g. Ctrl-r) or non-incremental (e.g. Esc-p) search"""
+    if rl_type == RlType.GNU:
+        # GNU Readline defines constants that we can use to determine if in search mode.
+        #     RL_STATE_ISEARCH    0x0000080
+        #     RL_STATE_NSEARCH    0x0000100
+        IN_SEARCH_MODE = 0x0000180
+
+        readline_state = ctypes.c_int.in_dll(readline_lib, "rl_readline_state").value
+        return bool(IN_SEARCH_MODE & readline_state)
+    elif rl_type == RlType.PYREADLINE:
+        from pyreadline3.modes.emacs import (  # type: ignore[import]
+            EmacsMode,
+        )
+
+        # These search modes only apply to Emacs mode, which is the default.
+        if not isinstance(readline.rl.mode, EmacsMode):
+            return False
+
+        # While in search mode, the current keyevent function is set one of the following.
+        search_funcs = (
+            readline.rl.mode._process_incremental_search_keyevent,
+            readline.rl.mode._process_non_incremental_search_keyevent,
+        )
+        return readline.rl.mode.process_keyevent_queue[-1] in search_funcs
+    else:
+        return False

cmd2/table_creator.py

@@ -5,6 +5,7 @@ This API is built upon two core classes: Column and TableCreator
 The general use case is to inherit from TableCreator to create a table class with custom formatting options.
 There are already implemented and ready-to-use examples of this below TableCreator's code.
 """
+
 import copy
 import io
 from collections import (

cmd2/transcript.py

@@ -9,6 +9,7 @@ a unit test, comparing the expected output to the actual output.
 This file contains the class necessary to make that work. This
 class is used in cmd2.py::run_transcript_tests()
 """
+
 import re
 import unittest
 from typing import (
@@ -60,7 +61,7 @@ class Cmd2TestCase(unittest.TestCase):
     def runTest(self) -> None:  # was testall
         if self.cmdapp:
             its = sorted(self.transcripts.items())
-            for (fname, transcript) in its:
+            for fname, transcript in its:
                 self._test_transcript(fname, transcript)
 
     def _fetchTranscripts(self) -> None:
@@ -204,7 +205,7 @@ class Cmd2TestCase(unittest.TestCase):
                 # escaped. We found it.
                 break
             else:
-                # check if the slash is preceeded by a backslash
+                # check if the slash is preceded by a backslash
                 if s[pos - 1 : pos] == '\\':
                     # it is.
                     if in_regex:

cmd2/utils.py

@@ -1,5 +1,6 @@
 # coding=utf-8
 """Shared utility functions"""
+
 import argparse
 import collections
 import functools
@@ -12,6 +13,9 @@ import subprocess
 import sys
 import threading
 import unicodedata
+from difflib import (
+    SequenceMatcher,
+)
 from enum import (
     Enum,
 )
@@ -41,12 +45,10 @@ from .argparse_custom import (
 if TYPE_CHECKING:  # pragma: no cover
     import cmd2  # noqa: F401
 
-    PopenTextIO = subprocess.Popen[bytes]
-
+    PopenTextIO = subprocess.Popen[str]
 else:
     PopenTextIO = subprocess.Popen
 
-
 _T = TypeVar('_T')
 
 
@@ -91,11 +93,14 @@ def strip_quotes(arg: str) -> str:
     return arg
 
 
-def str_to_bool(val: str) -> bool:
-    """Converts a string to a boolean based on its value.
+def to_bool(val: Any) -> bool:
+    """Converts anything to a boolean based on its value.
+
+    Strings like "True", "true", "False", and "false" return True, True, False, and False
+    respectively. All other values are converted using bool()
 
-    :param val: string being converted
-    :return: boolean value expressed in the string
+    :param val: value being converted
+    :return: boolean value expressed in the passed in value
     :raises: ValueError if the string does not contain a value corresponding to a boolean value
     """
     if isinstance(val, str):
@@ -103,7 +108,11 @@ def str_to_bool(val: str) -> bool:
             return True
         elif val.capitalize() == str(False):
             return False
-    raise ValueError("must be True or False (case-insensitive)")
+        raise ValueError("must be True or False (case-insensitive)")
+    elif isinstance(val, bool):
+        return val
+    else:
+        return bool(val)
 
 
 class Settable:
@@ -128,7 +137,7 @@ class Settable:
         :param name: name of the instance attribute being made settable
         :param val_type: callable used to cast the string value from the command line into its proper type and
                          even validate its value. Setting this to bool provides tab completion for true/false and
-                         validation using str_to_bool(). The val_type function should raise an exception if it fails.
+                         validation using to_bool(). The val_type function should raise an exception if it fails.
                          This exception will be caught and printed by Cmd.do_set().
         :param description: string describing this setting
         :param settable_object: object to which the instance attribute belongs (e.g. self)
@@ -149,13 +158,13 @@ class Settable:
         :param choices_provider: function that provides choices for this argument
         :param completer: tab completion function that provides choices for this argument
         """
-        if val_type == bool:
+        if val_type is bool:
 
             def get_bool_choices(_) -> List[str]:  # type: ignore[no-untyped-def]
                 """Used to tab complete lowercase boolean values"""
                 return ['true', 'false']
 
-            val_type = str_to_bool
+            val_type = to_bool
             choices_provider = cast(ChoicesProviderFunc, get_bool_choices)
 
         self.name = name
@@ -169,17 +178,14 @@ class Settable:
         self.completer = completer
 
     def get_value(self) -> Any:
-        """
-        Get the value of the settable attribute
-        :return:
-        """
+        """Get the value of the settable attribute."""
         return getattr(self.settable_obj, self.settable_attrib_name)
 
-    def set_value(self, value: Any) -> Any:
+    def set_value(self, value: Any) -> None:
         """
-        Set the settable attribute on the specified destination object
-        :param value: New value to set
-        :return: New value that the attribute was set to
+        Set the settable attribute on the specified destination object.
+
+        :param value: new value to set
         """
         # Run the value through its type function to handle any conversion or validation
         new_value = self.val_type(value)
@@ -196,7 +202,6 @@ class Settable:
         # Check if we need to call an onchange callback
         if orig_value != new_value and self.onchange_cb:
             self.onchange_cb(self.name, orig_value, new_value)
-        return new_value
 
 
 def is_text_file(file_path: str) -> bool:
@@ -663,19 +668,21 @@ class ProcReader:
 
         # Run until process completes
         while self._proc.poll() is None:
-            # noinspection PyUnresolvedReferences
             available = read_stream.peek()  # type: ignore[attr-defined]
             if available:
                 read_stream.read(len(available))
                 self._write_bytes(write_stream, available)
 
     @staticmethod
-    def _write_bytes(stream: Union[StdSim, TextIO], to_write: bytes) -> None:
+    def _write_bytes(stream: Union[StdSim, TextIO], to_write: Union[bytes, str]) -> None:
         """
         Write bytes to a stream
         :param stream: the stream being written to
         :param to_write: the bytes being written
         """
+        if isinstance(to_write, str):
+            to_write = to_write.encode()
+
         try:
             stream.buffer.write(to_write)
         except BrokenPipeError:
@@ -863,7 +870,8 @@ def align_text(
     )
 
     if width is None:
-        width = shutil.get_terminal_size().columns
+        # Prior to Python 3.11 this can return 0, so use a fallback if needed.
+        width = shutil.get_terminal_size().columns or constants.DEFAULT_TERMINAL_WIDTH
 
     if width < 1:
         raise ValueError("width must be at least 1")
@@ -1144,17 +1152,18 @@ def categorize(func: Union[Callable[..., Any], Iterable[Callable[..., Any]]], ca
     :param func: function or list of functions to categorize
     :param category: category to put it in
 
-    :Example:
+    Example:
+
+    ```py
+    import cmd2
+    class MyApp(cmd2.Cmd):
+      def do_echo(self, arglist):
+        self.poutput(' '.join(arglist)
 
-    >>> import cmd2
-    >>> class MyApp(cmd2.Cmd):
-    >>>   def do_echo(self, arglist):
-    >>>     self.poutput(' '.join(arglist)
-    >>>
-    >>>   cmd2.utils.categorize(do_echo, "Text Processing")
+      cmd2.utils.categorize(do_echo, "Text Processing")
+    ```
 
-    For an alternative approach to categorizing commands using a decorator, see
-    :func:`~cmd2.decorators.with_category`
+    For an alternative approach to categorizing commands using a decorator, see [cmd2.decorators.with_category][]
     """
     if isinstance(func, Iterable):
         for item in func:
@@ -1179,9 +1188,7 @@ def get_defining_class(meth: Callable[..., Any]) -> Optional[Type[Any]]:
     if isinstance(meth, functools.partial):
         return get_defining_class(meth.func)
     if inspect.ismethod(meth) or (
-        inspect.isbuiltin(meth)
-        and getattr(meth, '__self__') is not None
-        and getattr(meth.__self__, '__class__')  # type: ignore[attr-defined]
+        inspect.isbuiltin(meth) and getattr(meth, '__self__') is not None and getattr(meth.__self__, '__class__')
     ):
         for cls in inspect.getmro(meth.__self__.__class__):  # type: ignore[attr-defined]
             if meth.__name__ in cls.__dict__:
@@ -1254,3 +1261,36 @@ def strip_doc_annotations(doc: str) -> str:
         elif found_first:
             break
     return cmd_desc
+
+
+def similarity_function(s1: str, s2: str) -> float:
+    # The ratio from s1,s2 may be different to s2,s1. We keep the max.
+    # See https://docs.python.org/3/library/difflib.html#difflib.SequenceMatcher.ratio
+    return max(SequenceMatcher(None, s1, s2).ratio(), SequenceMatcher(None, s2, s1).ratio())
+
+
+MIN_SIMIL_TO_CONSIDER = 0.7
+
+
+def suggest_similar(
+    requested_command: str, options: Iterable[str], similarity_function_to_use: Optional[Callable[[str, str], float]] = None
+) -> Optional[str]:
+    """
+    Given a requested command and an iterable of possible options returns the most similar (if any is similar)
+
+    :param requested_command: The command entered by the user
+    :param options: The list of available commands to search for the most similar
+    :param similarity_function_to_use: An optional callable to use to compare commands
+    :return: The most similar command or None if no one is similar
+    """
+
+    proposed_command = None
+    best_simil = MIN_SIMIL_TO_CONSIDER
+    requested_command_to_compare = requested_command.lower()
+    similarity_function_to_use = similarity_function_to_use or similarity_function
+    for each in options:
+        simil = similarity_function_to_use(each.lower(), requested_command_to_compare)
+        if best_simil < simil:
+            best_simil = simil
+            proposed_command = each
+    return proposed_command

{cmd2-2.4.2.dist-info → cmd2-2.5.9.dist-info}/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2008-2022 Catherine Devlin and others
+Copyright (c) 2008-2024 Catherine Devlin and others
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal