cmd2.utils

cmd2.utils

Shared utility functions.

PopenTextIO module-attribute

PopenTextIO = Popen[str]

MIN_SIMIL_TO_CONSIDER module-attribute

MIN_SIMIL_TO_CONSIDER = 0.7

Settable

Settable(name, val_type, description, settable_object, *, settable_attrib_name=None, onchange_cb=None, choices=None, choices_provider=None, completer=None)

Used to configure an attribute to be settable via the set command in the CLI.

Settable Initializer.

PARAMETER	DESCRIPTION
name	The user-facing name for this setting in the CLI. TYPE: str
val_type	A callable used to cast the string value from the CLI into its proper type and validate it. This function should raise an exception (like ValueError or TypeError) if the conversion or validation fails, which will be caught and displayed to the user by the set command. For example, setting this to int ensures the input is a valid integer. Specifying bool automatically provides tab completion for 'true' and 'false' and uses a built-in function for conversion and validation. TYPE: type[Any] | Callable[[Any], Any]
description	A concise string that describes the purpose of this setting. TYPE: str
settable_object	The object that owns the attribute being made settable (e.g. self). TYPE: object
settable_attrib_name	The name of the attribute on the settable_object that will be modified. This defaults to the value of the name parameter if not specified. TYPE: str | None DEFAULT: None
onchange_cb	An optional function or method to call when the value of this setting is altered by the set command. The callback is invoked only if the new value is different from the old one. It receives three arguments: param_name: str - name of the parameter old_value: Any - the parameter's old value new_value: Any - the parameter's new value The following optional settings provide tab completion for a parameter's values. They correspond to the same settings in argparse-based tab completion. A maximum of one of these should be provided. TYPE: Callable[[str, Any, Any], Any] | None DEFAULT: None
choices	iterable of accepted values TYPE: Iterable[Any] | None DEFAULT: None
choices_provider	function that provides choices for this argument TYPE: ChoicesProviderFunc | None DEFAULT: None
completer	tab completion function that provides choices for this argument TYPE: CompleterFunc | None DEFAULT: None

Source code in cmd2/utils.py

def __init__(
    self,
    name: str,
    val_type: type[Any] | Callable[[Any], Any],
    description: str,
    settable_object: object,
    *,
    settable_attrib_name: str | None = None,
    onchange_cb: Callable[[str, Any, Any], Any] | None = None,
    choices: Iterable[Any] | None = None,
    choices_provider: ChoicesProviderFunc | None = None,
    completer: CompleterFunc | None = None,
) -> None:
    """Settable Initializer.

    :param name: The user-facing name for this setting in the CLI.
    :param val_type: A callable used to cast the string value from the CLI into its
                     proper type and validate it. This function should raise an
                     exception (like ValueError or TypeError) if the conversion or
                     validation fails, which will be caught and displayed to the user
                     by the set command. For example, setting this to int ensures the
                     input is a valid integer. Specifying bool automatically provides
                     tab completion for 'true' and 'false' and uses a built-in function
                     for conversion and validation.
    :param description: A concise string that describes the purpose of this setting.
    :param settable_object: The object that owns the attribute being made settable (e.g. self).
    :param settable_attrib_name: The name of the attribute on the settable_object that
                                 will be modified. This defaults to the value of the name
                                 parameter if not specified.
    :param onchange_cb: An optional function or method to call when the value of this
                        setting is altered by the set command. The callback is invoked
                        only if the new value is different from the old one.

                        It receives three arguments:
                            param_name: str - name of the parameter
                            old_value: Any - the parameter's old value
                            new_value: Any - the parameter's new value

    The following optional settings provide tab completion for a parameter's values.
    They correspond to the same settings in argparse-based tab completion. A maximum
    of one of these should be provided.

    :param choices: iterable of accepted values
    :param choices_provider: function that provides choices for this argument
    :param completer: tab completion function that provides choices for this argument
    """
    if val_type is bool:

        def get_bool_choices(_: str) -> list[str]:
            """Tab complete lowercase boolean values."""
            return ['true', 'false']

        val_type = to_bool
        choices_provider = cast(ChoicesProviderFunc, get_bool_choices)

    self.name = name
    self.val_type = val_type
    self.description = description
    self.settable_obj = settable_object
    self.settable_attrib_name = settable_attrib_name if settable_attrib_name is not None else name
    self.onchange_cb = onchange_cb
    self.choices = choices
    self.choices_provider = choices_provider
    self.completer = completer

name instance-attribute

name = name

val_type instance-attribute

val_type = val_type

description instance-attribute

description = description

settable_obj instance-attribute

settable_obj = settable_object

settable_attrib_name instance-attribute

settable_attrib_name = settable_attrib_name if settable_attrib_name is not None else name

onchange_cb instance-attribute

onchange_cb = onchange_cb

choices instance-attribute

choices = choices

choices_provider instance-attribute

choices_provider = choices_provider

completer instance-attribute

completer = completer

value property writable

value

Get the value of the settable attribute.

StdSim

StdSim(inner_stream, *, echo=False, encoding='utf-8', errors='replace')

Class to simulate behavior of sys.stdout or sys.stderr.

Stores contents in internal buffer and optionally echos to the inner stream it is simulating.

StdSim Initializer.

PARAMETER	DESCRIPTION
inner_stream	the wrapped stream. Should be a TextIO or StdSim instance. TYPE: Union[TextIO, StdSim]
echo	if True, then all input will be echoed to inner_stream TYPE: bool DEFAULT: False
encoding	codec for encoding/decoding strings (defaults to utf-8) TYPE: str DEFAULT: 'utf-8'
errors	how to handle encoding/decoding errors (defaults to replace) TYPE: str DEFAULT: 'replace'

Source code in cmd2/utils.py

def __init__(
    self,
    inner_stream: Union[TextIO, 'StdSim'],
    *,
    echo: bool = False,
    encoding: str = 'utf-8',
    errors: str = 'replace',
) -> None:
    """StdSim Initializer.

    :param inner_stream: the wrapped stream. Should be a TextIO or StdSim instance.
    :param echo: if True, then all input will be echoed to inner_stream
    :param encoding: codec for encoding/decoding strings (defaults to utf-8)
    :param errors: how to handle encoding/decoding errors (defaults to replace)
    """
    self.inner_stream = inner_stream
    self.echo = echo
    self.encoding = encoding
    self.errors = errors
    self.pause_storage = False
    self.buffer = ByteBuf(self)

inner_stream instance-attribute

inner_stream = inner_stream

echo instance-attribute

echo = echo

encoding instance-attribute

encoding = encoding

errors instance-attribute

errors = errors

pause_storage instance-attribute

pause_storage = False

buffer instance-attribute

buffer = ByteBuf(self)

line_buffering property

line_buffering

Handle when the inner stream doesn't have a line_buffering attribute.

Which is the case when running unit tests because pytest sets stdout to a pytest EncodedFile object.

write

write(s)

Add str to internal bytes buffer and if echo is True, echo contents to inner stream.

PARAMETER	DESCRIPTION
s	String to write to the stream TYPE: str

Source code in cmd2/utils.py

def write(self, s: str) -> None:
    """Add str to internal bytes buffer and if echo is True, echo contents to inner stream.

    :param s: String to write to the stream
    """
    if not isinstance(s, str):
        raise TypeError(f'write() argument must be str, not {type(s)}')

    if not self.pause_storage:
        self.buffer.byte_buf += s.encode(encoding=self.encoding, errors=self.errors)
    if self.echo:
        self.inner_stream.write(s)

getvalue

getvalue()

Get the internal contents as a str.

Source code in cmd2/utils.py

def getvalue(self) -> str:
    """Get the internal contents as a str."""
    return self.buffer.byte_buf.decode(encoding=self.encoding, errors=self.errors)

getbytes

getbytes()

Get the internal contents as bytes.

Source code in cmd2/utils.py

def getbytes(self) -> bytes:
    """Get the internal contents as bytes."""
    return bytes(self.buffer.byte_buf)

read

read(size=-1)

Read from the internal contents as a str and then clear them out.

PARAMETER	DESCRIPTION
size	Number of bytes to read from the stream TYPE: int | None DEFAULT: -1

Source code in cmd2/utils.py

def read(self, size: int | None = -1) -> str:
    """Read from the internal contents as a str and then clear them out.

    :param size: Number of bytes to read from the stream
    """
    if size is None or size == -1:
        result = self.getvalue()
        self.clear()
    else:
        result = self.buffer.byte_buf[:size].decode(encoding=self.encoding, errors=self.errors)
        self.buffer.byte_buf = self.buffer.byte_buf[size:]

    return result

readbytes

readbytes()

Read from the internal contents as bytes and then clear them out.

Source code in cmd2/utils.py

def readbytes(self) -> bytes:
    """Read from the internal contents as bytes and then clear them out."""
    result = self.getbytes()
    self.clear()
    return result

clear

clear()

Clear the internal contents.

Source code in cmd2/utils.py

def clear(self) -> None:
    """Clear the internal contents."""
    self.buffer.byte_buf.clear()

isatty

isatty()

StdSim only considered an interactive stream if echo is True and inner_stream is a tty.

Source code in cmd2/utils.py

def isatty(self) -> bool:
    """StdSim only considered an interactive stream if `echo` is True and `inner_stream` is a tty."""
    if self.echo:
        return self.inner_stream.isatty()
    return False

ByteBuf

ByteBuf(std_sim_instance)

Used by StdSim to write binary data and stores the actual bytes written.

Initialize the ByteBuf instance.

Source code in cmd2/utils.py

def __init__(self, std_sim_instance: StdSim) -> None:
    """Initialize the ByteBuf instance."""
    self.byte_buf = bytearray()
    self.std_sim_instance = std_sim_instance

NEWLINES class-attribute instance-attribute

NEWLINES = (b'\n', b'\r')

byte_buf instance-attribute

byte_buf = bytearray()

std_sim_instance instance-attribute

std_sim_instance = std_sim_instance

write

write(b)

Add bytes to internal bytes buffer and if echo is True, echo contents to inner stream.

Source code in cmd2/utils.py

def write(self, b: bytes) -> None:
    """Add bytes to internal bytes buffer and if echo is True, echo contents to inner stream."""
    if not isinstance(b, bytes):
        raise TypeError(f'a bytes-like object is required, not {type(b)}')
    if not self.std_sim_instance.pause_storage:
        self.byte_buf += b
    if self.std_sim_instance.echo:
        self.std_sim_instance.inner_stream.buffer.write(b)

        # Since StdSim wraps TextIO streams, we will flush the stream if line buffering is on
        # and the bytes being written contain a new line character. This is helpful when StdSim
        # is being used to capture output of a shell command because it causes the output to print
        # to the screen more often than if we waited for the stream to flush its buffer.
        if self.std_sim_instance.line_buffering and any(newline in b for newline in ByteBuf.NEWLINES):
            self.std_sim_instance.flush()

ProcReader

ProcReader(proc, stdout, stderr)

Used to capture stdout and stderr from a Popen process if any of those were set to subprocess.PIPE.

If neither are pipes, then the process will run normally and no output will be captured.

ProcReader initializer.

PARAMETER	DESCRIPTION
proc	the Popen process being read from TYPE: PopenTextIO
stdout	the stream to write captured stdout TYPE: StdSim | TextIO
stderr	the stream to write captured stderr. TYPE: StdSim | TextIO

Source code in cmd2/utils.py

def __init__(self, proc: PopenTextIO, stdout: StdSim | TextIO, stderr: StdSim | TextIO) -> None:
    """ProcReader initializer.

    :param proc: the Popen process being read from
    :param stdout: the stream to write captured stdout
    :param stderr: the stream to write captured stderr.
    """
    self._proc = proc
    self._stdout = stdout
    self._stderr = stderr

    self._out_thread = threading.Thread(name='out_thread', target=self._reader_thread_func, kwargs={'read_stdout': True})

    self._err_thread = threading.Thread(name='err_thread', target=self._reader_thread_func, kwargs={'read_stdout': False})

    # Start the reader threads for pipes only
    if self._proc.stdout is not None:
        self._out_thread.start()
    if self._proc.stderr is not None:
        self._err_thread.start()

send_sigint

send_sigint()

Send a SIGINT to the process similar to if +C were pressed.

Source code in cmd2/utils.py

def send_sigint(self) -> None:
    """Send a SIGINT to the process similar to if <Ctrl>+C were pressed."""
    import signal

    if sys.platform.startswith('win'):
        # cmd2 started the Windows process in a new process group. Therefore we must send
        # a CTRL_BREAK_EVENT since CTRL_C_EVENT signals cannot be generated for process groups.
        self._proc.send_signal(signal.CTRL_BREAK_EVENT)
    else:
        # Since cmd2 uses shell=True in its Popen calls, we need to send the SIGINT to
        # the whole process group to make sure it propagates further than the shell
        try:
            group_id = os.getpgid(self._proc.pid)
            os.killpg(group_id, signal.SIGINT)
        except ProcessLookupError:
            return

terminate

terminate()

Terminate the process.

Source code in cmd2/utils.py

def terminate(self) -> None:
    """Terminate the process."""
    self._proc.terminate()

wait

wait()

Wait for the process to finish.

Source code in cmd2/utils.py

def wait(self) -> None:
    """Wait for the process to finish."""
    if self._out_thread.is_alive():
        self._out_thread.join()
    if self._err_thread.is_alive():
        self._err_thread.join()

    # Handle case where the process ended before the last read could be done.
    # This will return None for the streams that weren't pipes.
    out, err = self._proc.communicate()

    if out:
        self._write_bytes(self._stdout, out)
    if err:
        self._write_bytes(self._stderr, err)

ContextFlag

ContextFlag()

A context manager which is also used as a boolean flag value within the default sigint handler.

Its main use is as a flag to prevent the SIGINT handler in cmd2 from raising a KeyboardInterrupt while a critical code section has set the flag to True. Because signal handling is always done on the main thread, this class is not thread-safe since there is no need.

When this flag has a positive value, it is considered set. When it is 0, it is not set.

It should never go below 0.

Source code in cmd2/utils.py

def __init__(self) -> None:
    """When this flag has a positive value, it is considered set. When it is 0, it is not set.

    It should never go below 0.
    """
    self.__count = 0

RedirectionSavedState

RedirectionSavedState(self_stdout, stdouts_match, pipe_proc_reader, saved_redirecting)

Created by each command to store information required to restore state after redirection.

RedirectionSavedState initializer.

PARAMETER	DESCRIPTION
self_stdout	saved value of Cmd.stdout TYPE: StdSim | TextIO
stdouts_match	True if Cmd.stdout is equal to sys.stdout TYPE: bool
pipe_proc_reader	saved value of Cmd._cur_pipe_proc_reader TYPE: ProcReader | None
saved_redirecting	saved value of Cmd._redirecting. TYPE: bool

Source code in cmd2/utils.py

def __init__(
    self,
    self_stdout: StdSim | TextIO,
    stdouts_match: bool,
    pipe_proc_reader: ProcReader | None,
    saved_redirecting: bool,
) -> None:
    """RedirectionSavedState initializer.

    :param self_stdout: saved value of Cmd.stdout
    :param stdouts_match: True if Cmd.stdout is equal to sys.stdout
    :param pipe_proc_reader: saved value of Cmd._cur_pipe_proc_reader
    :param saved_redirecting: saved value of Cmd._redirecting.
    """
    # Tells if command is redirecting
    self.redirecting = False

    # Used to restore stdout values after redirection ends
    self.saved_self_stdout = self_stdout
    self.stdouts_match = stdouts_match

    # Used to restore values after command ends regardless of whether the command redirected
    self.saved_pipe_proc_reader = pipe_proc_reader
    self.saved_redirecting = saved_redirecting

redirecting instance-attribute

redirecting = False

saved_self_stdout instance-attribute

saved_self_stdout = self_stdout

stdouts_match instance-attribute

stdouts_match = stdouts_match

saved_pipe_proc_reader instance-attribute

saved_pipe_proc_reader = pipe_proc_reader

saved_redirecting instance-attribute

saved_redirecting = saved_redirecting

CompletionMode

Bases: Enum

Enum for what type of tab completion to perform in cmd2.Cmd.read_input().

NONE class-attribute instance-attribute

NONE = 1

COMMANDS class-attribute instance-attribute

COMMANDS = 2

CUSTOM class-attribute instance-attribute

CUSTOM = 3

CustomCompletionSettings

CustomCompletionSettings(parser, *, preserve_quotes=False)

Used by cmd2.Cmd.complete() to tab complete strings other than command arguments.

CustomCompletionSettings initializer.

PARAMETER	DESCRIPTION
parser	arg parser defining format of string being tab completed TYPE: ArgumentParser
preserve_quotes	if True, then quoted tokens will keep their quotes when processed by ArgparseCompleter. This is helpful in cases when you're tab completing flag-like tokens (e.g. -o, --option) and you don't want them to be treated as argparse flags when quoted. Set this to True if you plan on passing the string to argparse with the tokens still quoted. TYPE: bool DEFAULT: False

Source code in cmd2/utils.py

def __init__(self, parser: argparse.ArgumentParser, *, preserve_quotes: bool = False) -> None:
    """CustomCompletionSettings initializer.

    :param parser: arg parser defining format of string being tab completed
    :param preserve_quotes: if True, then quoted tokens will keep their quotes when processed by
                            ArgparseCompleter. This is helpful in cases when you're tab completing
                            flag-like tokens (e.g. -o, --option) and you don't want them to be
                            treated as argparse flags when quoted. Set this to True if you plan
                            on passing the string to argparse with the tokens still quoted.
    """
    self.parser = parser
    self.preserve_quotes = preserve_quotes

parser instance-attribute

parser = parser

preserve_quotes instance-attribute

preserve_quotes = preserve_quotes

to_bool

to_bool(val)

Convert 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()

PARAMETER	DESCRIPTION
val	value being converted TYPE: Any

RETURNS	DESCRIPTION
bool	boolean value expressed in the passed in value

RAISES	DESCRIPTION
ValueError	if the string does not contain a value corresponding to a boolean value

Source code in cmd2/utils.py

def to_bool(val: Any) -> bool:
    """Convert 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: 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):
        if val.capitalize() == str(True):
            return True
        if val.capitalize() == str(False):
            return False
        raise ValueError("must be True or False (case-insensitive)")
    if isinstance(val, bool):
        return val
    return bool(val)

is_text_file

is_text_file(file_path)

Return if a file contains only ASCII or UTF-8 encoded text and isn't empty.

PARAMETER	DESCRIPTION
file_path	path to the file being checked TYPE: str

RETURNS	DESCRIPTION
bool	True if the file is a non-empty text file, otherwise False

RAISES	DESCRIPTION
OSError	if file can't be read

Source code in cmd2/utils.py

def is_text_file(file_path: str) -> bool:
    """Return if a file contains only ASCII or UTF-8 encoded text and isn't empty.

    :param file_path: path to the file being checked
    :return: True if the file is a non-empty text file, otherwise False
    :raises OSError: if file can't be read
    """
    expanded_path = os.path.abspath(os.path.expanduser(file_path.strip()))
    valid_text_file = False

    # Only need to check for utf-8 compliance since that covers ASCII, too
    try:
        with open(expanded_path, encoding='utf-8', errors='strict') as f:
            # Make sure the file has only utf-8 text and is not empty
            if sum(1 for _ in f) > 0:
                valid_text_file = True
    except OSError:
        raise
    except UnicodeDecodeError:
        # Not UTF-8
        pass

    return valid_text_file

remove_duplicates

remove_duplicates(list_to_prune)

Remove duplicates from a list while preserving order of the items.

PARAMETER	DESCRIPTION
list_to_prune	the list being pruned of duplicates TYPE: list[_T]

RETURNS	DESCRIPTION
list[_T]	The pruned list

Source code in cmd2/utils.py

def remove_duplicates(list_to_prune: list[_T]) -> list[_T]:
    """Remove duplicates from a list while preserving order of the items.

    :param list_to_prune: the list being pruned of duplicates
    :return: The pruned list
    """
    temp_dict = dict.fromkeys(list_to_prune)
    return list(temp_dict.keys())

alphabetical_sort

alphabetical_sort(list_to_sort)

Sorts a list of strings alphabetically.

For example: ['a1', 'A11', 'A2', 'a22', 'a3']

To sort a list in place, don't call this method, which makes a copy. Instead, do this:

my_list.sort(key=norm_fold)

PARAMETER	DESCRIPTION
list_to_sort	the list being sorted TYPE: Iterable[str]

RETURNS	DESCRIPTION
list[str]	the sorted list

Source code in cmd2/utils.py

def alphabetical_sort(list_to_sort: Iterable[str]) -> list[str]:
    """Sorts a list of strings alphabetically.

    For example: ['a1', 'A11', 'A2', 'a22', 'a3']

    To sort a list in place, don't call this method, which makes a copy. Instead, do this:

    my_list.sort(key=norm_fold)

    :param list_to_sort: the list being sorted
    :return: the sorted list
    """
    return sorted(list_to_sort, key=su.norm_fold)

try_int_or_force_to_lower_case

try_int_or_force_to_lower_case(input_str)

Try to convert the passed-in string to an integer. If that fails, it converts it to lower case using norm_fold.

PARAMETER	DESCRIPTION
input_str	string to convert TYPE: str

RETURNS	DESCRIPTION
int | str	the string as an integer or a lower case version of the string.

Source code in cmd2/utils.py

def try_int_or_force_to_lower_case(input_str: str) -> int | str:
    """Try to convert the passed-in string to an integer. If that fails, it converts it to lower case using norm_fold.

    :param input_str: string to convert
    :return: the string as an integer or a lower case version of the string.
    """
    try:
        return int(input_str)
    except ValueError:
        return su.norm_fold(input_str)

natural_keys

natural_keys(input_str)

Convert a string into a list of integers and strings to support natural sorting (see natural_sort).

For example: natural_keys('abc123def') -> ['abc', '123', 'def']

PARAMETER	DESCRIPTION
input_str	string to convert TYPE: str

RETURNS	DESCRIPTION
list[int | str]	list of strings and integers

Source code in cmd2/utils.py

def natural_keys(input_str: str) -> list[int | str]:
    """Convert a string into a list of integers and strings to support natural sorting (see natural_sort).

    For example: natural_keys('abc123def') -> ['abc', '123', 'def']
    :param input_str: string to convert
    :return: list of strings and integers
    """
    return [try_int_or_force_to_lower_case(substr) for substr in re.split(r'(\d+)', input_str)]

natural_sort

natural_sort(list_to_sort)

Sorts a list of strings case insensitively as well as numerically.

For example: ['a1', 'A2', 'a3', 'A11', 'a22']

To sort a list in place, don't call this method, which makes a copy. Instead, do this:

my_list.sort(key=natural_keys)

PARAMETER	DESCRIPTION
list_to_sort	the list being sorted TYPE: Iterable[str]

RETURNS	DESCRIPTION
list[str]	the list sorted naturally

Source code in cmd2/utils.py

def natural_sort(list_to_sort: Iterable[str]) -> list[str]:
    """Sorts a list of strings case insensitively as well as numerically.

    For example: ['a1', 'A2', 'a3', 'A11', 'a22']

    To sort a list in place, don't call this method, which makes a copy. Instead, do this:

    my_list.sort(key=natural_keys)

    :param list_to_sort: the list being sorted
    :return: the list sorted naturally
    """
    return sorted(list_to_sort, key=natural_keys)

quote_specific_tokens

quote_specific_tokens(tokens, tokens_to_quote)

Quote specific tokens in a list.

PARAMETER	DESCRIPTION
tokens	token list being edited TYPE: list[str]
tokens_to_quote	the tokens, which if present in tokens, to quote TYPE: list[str]

Source code in cmd2/utils.py

def quote_specific_tokens(tokens: list[str], tokens_to_quote: list[str]) -> None:
    """Quote specific tokens in a list.

    :param tokens: token list being edited
    :param tokens_to_quote: the tokens, which if present in tokens, to quote
    """
    for i, token in enumerate(tokens):
        if token in tokens_to_quote:
            tokens[i] = su.quote(token)

unquote_specific_tokens

unquote_specific_tokens(tokens, tokens_to_unquote)

Unquote specific tokens in a list.

PARAMETER	DESCRIPTION
tokens	token list being edited TYPE: list[str]
tokens_to_unquote	the tokens, which if present in tokens, to unquote TYPE: list[str]

Source code in cmd2/utils.py

def unquote_specific_tokens(tokens: list[str], tokens_to_unquote: list[str]) -> None:
    """Unquote specific tokens in a list.

    :param tokens: token list being edited
    :param tokens_to_unquote: the tokens, which if present in tokens, to unquote
    """
    for i, token in enumerate(tokens):
        unquoted_token = su.strip_quotes(token)
        if unquoted_token in tokens_to_unquote:
            tokens[i] = unquoted_token

expand_user

expand_user(token)

Wrap os.expanduser() to support expanding ~ in quoted strings.

PARAMETER	DESCRIPTION
token	the string to expand TYPE: str

Source code in cmd2/utils.py

def expand_user(token: str) -> str:
    """Wrap os.expanduser() to support expanding ~ in quoted strings.

    :param token: the string to expand
    """
    if token:
        if su.is_quoted(token):
            quote_char = token[0]
            token = su.strip_quotes(token)
        else:
            quote_char = ''

        token = os.path.expanduser(token)

        # Restore the quotes even if not needed to preserve what the user typed
        if quote_char:
            token = quote_char + token + quote_char

    return token

expand_user_in_tokens

expand_user_in_tokens(tokens)

Call expand_user() on all tokens in a list of strings.

PARAMETER	DESCRIPTION
tokens	tokens to expand. TYPE: list[str]

Source code in cmd2/utils.py

def expand_user_in_tokens(tokens: list[str]) -> None:
    """Call expand_user() on all tokens in a list of strings.

    :param tokens: tokens to expand.
    """
    for index, _ in enumerate(tokens):
        tokens[index] = expand_user(tokens[index])

find_editor

find_editor()

Set cmd2.Cmd.DEFAULT_EDITOR. If EDITOR env variable is set, that will be used.

Otherwise the function will look for a known editor in directories specified by PATH env variable.

RETURNS	DESCRIPTION
str | None	Default editor or None.

Source code in cmd2/utils.py

def find_editor() -> str | None:
    """Set cmd2.Cmd.DEFAULT_EDITOR. If EDITOR env variable is set, that will be used.

    Otherwise the function will look for a known editor in directories specified by PATH env variable.
    :return: Default editor or None.
    """
    editor = os.environ.get('EDITOR')
    if not editor:
        if sys.platform[:3] == 'win':
            editors = ['edit', 'code.cmd', 'notepad++.exe', 'notepad.exe']
        else:
            editors = ['vim', 'vi', 'emacs', 'nano', 'pico', 'joe', 'code', 'subl', 'gedit', 'kate']

        # Get a list of every directory in the PATH environment variable and ignore symbolic links
        env_path = os.getenv('PATH')
        paths = [] if env_path is None else [p for p in env_path.split(os.path.pathsep) if not os.path.islink(p)]

        for possible_editor, path in itertools.product(editors, paths):
            editor_path = os.path.join(path, possible_editor)
            if os.path.isfile(editor_path) and os.access(editor_path, os.X_OK):
                if sys.platform[:3] == 'win':
                    # Remove extension from Windows file names
                    editor = os.path.splitext(possible_editor)[0]
                else:
                    editor = possible_editor
                break
        else:
            editor = None

    return editor

files_from_glob_pattern

files_from_glob_pattern(pattern, access=F_OK)

Return a list of file paths based on a glob pattern.

Only files are returned, not directories, and optionally only files for which the user has a specified access to.

PARAMETER	DESCRIPTION
pattern	file name or glob pattern TYPE: str
access	file access type to verify (os.* where * is F_OK, R_OK, W_OK, or X_OK) TYPE: int DEFAULT: F_OK

RETURNS	DESCRIPTION
list[str]	list of files matching the name or glob pattern

Source code in cmd2/utils.py

def files_from_glob_pattern(pattern: str, access: int = os.F_OK) -> list[str]:
    """Return a list of file paths based on a glob pattern.

    Only files are returned, not directories, and optionally only files for which the user has a specified access to.

    :param pattern: file name or glob pattern
    :param access: file access type to verify (os.* where * is F_OK, R_OK, W_OK, or X_OK)
    :return: list of files matching the name or glob pattern
    """
    return [f for f in glob.glob(pattern) if os.path.isfile(f) and os.access(f, access)]

files_from_glob_patterns

files_from_glob_patterns(patterns, access=F_OK)

Return a list of file paths based on a list of glob patterns.

Only files are returned, not directories, and optionally only files for which the user has a specified access to.

PARAMETER	DESCRIPTION
patterns	list of file names and/or glob patterns TYPE: list[str]
access	file access type to verify (os.* where * is F_OK, R_OK, W_OK, or X_OK) TYPE: int DEFAULT: F_OK

RETURNS	DESCRIPTION
list[str]	list of files matching the names and/or glob patterns

Source code in cmd2/utils.py

def files_from_glob_patterns(patterns: list[str], access: int = os.F_OK) -> list[str]:
    """Return a list of file paths based on a list of glob patterns.

    Only files are returned, not directories, and optionally only files for which the user has a specified access to.

    :param patterns: list of file names and/or glob patterns
    :param access: file access type to verify (os.* where * is F_OK, R_OK, W_OK, or X_OK)
    :return: list of files matching the names and/or glob patterns
    """
    files = []
    for pattern in patterns:
        matches = files_from_glob_pattern(pattern, access=access)
        files.extend(matches)
    return files

get_exes_in_path

get_exes_in_path(starts_with)

Return names of executables in a user's path.

PARAMETER	DESCRIPTION
starts_with	what the exes should start with. leave blank for all exes in path. TYPE: str

RETURNS	DESCRIPTION
list[str]	a list of matching exe names

Source code in cmd2/utils.py

def get_exes_in_path(starts_with: str) -> list[str]:
    """Return names of executables in a user's path.

    :param starts_with: what the exes should start with. leave blank for all exes in path.
    :return: a list of matching exe names
    """
    # Purposely don't match any executable containing wildcards
    wildcards = ['*', '?']
    for wildcard in wildcards:
        if wildcard in starts_with:
            return []

    # Get a list of every directory in the PATH environment variable and ignore symbolic links
    env_path = os.getenv('PATH')
    paths = [] if env_path is None else [p for p in env_path.split(os.path.pathsep) if not os.path.islink(p)]

    # Use a set to store exe names since there can be duplicates
    exes_set = set()

    # Find every executable file in the user's path that matches the pattern
    for path in paths:
        full_path = os.path.join(path, starts_with)
        matches = files_from_glob_pattern(full_path + '*', access=os.X_OK)

        for match in matches:
            exes_set.add(os.path.basename(match))

    return list(exes_set)

categorize

categorize(func, category)

Categorize a function.

The help command output will group the passed function under the specified category heading

PARAMETER	DESCRIPTION
func	function or list of functions to categorize TYPE: Callable[..., Any] | Iterable[Callable[..., Any]]
category	category to put it in Example: py import cmd2 class MyApp(cmd2.Cmd): def do_echo(self, arglist): self.poutput(' '.join(arglist) cmd2.utils.categorize(do_echo, "Text Processing") For an alternative approach to categorizing commands using a decorator, see cmd2.decorators.with_category TYPE: str

Source code in cmd2/utils.py

def categorize(func: Callable[..., Any] | Iterable[Callable[..., Any]], category: str) -> None:
    """Categorize a function.

    The help command output will group the passed function under the
    specified category heading

    :param func: function or list of functions to categorize
    :param category: category to put it in

    Example:
    ```py
    import cmd2
    class MyApp(cmd2.Cmd):
      def do_echo(self, arglist):
        self.poutput(' '.join(arglist)

      cmd2.utils.categorize(do_echo, "Text Processing")
    ```

    For an alternative approach to categorizing commands using a decorator, see [cmd2.decorators.with_category][]

    """
    if isinstance(func, Iterable):
        for item in func:
            setattr(item, constants.CMD_ATTR_HELP_CATEGORY, category)
    elif inspect.ismethod(func):
        setattr(func.__func__, constants.CMD_ATTR_HELP_CATEGORY, category)
    else:
        setattr(func, constants.CMD_ATTR_HELP_CATEGORY, category)

get_defining_class

get_defining_class(meth)

Attempt to resolve the class that defined a method.

Inspired by implementation published here: https://stackoverflow.com/a/25959545/1956611

PARAMETER	DESCRIPTION
meth	method to inspect TYPE: Callable[..., Any]

RETURNS	DESCRIPTION
type[Any] | None	class type in which the supplied method was defined. None if it couldn't be resolved.

Source code in cmd2/utils.py

def get_defining_class(meth: Callable[..., Any]) -> type[Any] | None:
    """Attempt to resolve the class that defined a method.

    Inspired by implementation published here:
        https://stackoverflow.com/a/25959545/1956611

    :param meth: method to inspect
    :return: class type in which the supplied method was defined. None if it couldn't be resolved.
    """
    if isinstance(meth, functools.partial):
        return get_defining_class(meth.func)
    if inspect.ismethod(meth) or (
        inspect.isbuiltin(meth) and hasattr(meth, '__self__') and hasattr(meth.__self__, '__class__')
    ):
        for cls in inspect.getmro(meth.__self__.__class__):
            if meth.__name__ in cls.__dict__:
                return cls
        meth = getattr(meth, '__func__', meth)  # fallback to __qualname__ parsing
    if inspect.isfunction(meth):
        cls = getattr(inspect.getmodule(meth), meth.__qualname__.split('.<locals>', 1)[0].rsplit('.', 1)[0])
        if isinstance(cls, type):
            return cls
    return cast(type, getattr(meth, '__objclass__', None))  # handle special descriptor objects

strip_doc_annotations

strip_doc_annotations(doc)

Strip annotations from a docstring leaving only the text description.

PARAMETER	DESCRIPTION
doc	documentation string TYPE: str

Source code in cmd2/utils.py

def strip_doc_annotations(doc: str) -> str:
    """Strip annotations from a docstring leaving only the text description.

    :param doc: documentation string
    """
    # Attempt to locate the first documentation block
    cmd_desc = ''
    found_first = False
    for doc_line in doc.splitlines():
        stripped_line = doc_line.strip()

        # Don't include :param type lines
        if stripped_line.startswith(':'):
            if found_first:
                break
        elif stripped_line:
            if found_first:
                cmd_desc += "\n"
            cmd_desc += stripped_line
            found_first = True
        elif found_first:
            break
    return cmd_desc

similarity_function

similarity_function(s1, s2)

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

Source code in cmd2/utils.py

def similarity_function(s1: str, s2: str) -> float:
    """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())

suggest_similar

suggest_similar(requested_command, options, similarity_function_to_use=None)

Given a requested command and an iterable of possible options returns the most similar (if any is similar).

PARAMETER	DESCRIPTION
requested_command	The command entered by the user TYPE: str
options	The list of available commands to search for the most similar TYPE: Iterable[str]
similarity_function_to_use	An optional callable to use to compare commands TYPE: Callable[[str, str], float] | None DEFAULT: None

RETURNS	DESCRIPTION
str | None	The most similar command or None if no one is similar

Source code in cmd2/utils.py

def suggest_similar(
    requested_command: str, options: Iterable[str], similarity_function_to_use: Callable[[str, str], float] | None = None
) -> str | None:
    """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

get_types

get_types(func_or_method)

Use inspect.get_annotations() to extract type hints for parameters and return value.

This is a thin convenience wrapper around inspect.get_annotations() that treats the return value annotation separately.

PARAMETER	DESCRIPTION
func_or_method	Function or method to return the type hints for TYPE: Callable[..., Any]

RETURNS	DESCRIPTION
tuple[dict[str, Any], Any]	tuple with first element being dictionary mapping param names to type hints and second element being the return type hint or None if there is no return value type hint

RAISES	DESCRIPTION
ValueError	if the func_or_method argument is not a valid object to pass to inspect.get_annotations

Source code in cmd2/utils.py

def get_types(func_or_method: Callable[..., Any]) -> tuple[dict[str, Any], Any]:
    """Use inspect.get_annotations() to extract type hints for parameters and return value.

    This is a thin convenience wrapper around inspect.get_annotations() that treats the return value
    annotation separately.

    :param func_or_method: Function or method to return the type hints for
    :return: tuple with first element being dictionary mapping param names to type hints
            and second element being the return type hint or None if there is no return value type hint
    :raises ValueError: if the `func_or_method` argument is not a valid object to pass to `inspect.get_annotations`
    """
    try:
        type_hints = inspect.get_annotations(func_or_method, eval_str=True)  # Get dictionary of type hints
    except TypeError as exc:
        raise ValueError("Argument passed to get_types should be a function or method") from exc
    ret_ann = type_hints.pop('return', None)  # Pop off the return annotation if it exists
    if inspect.ismethod(func_or_method):
        type_hints.pop('self', None)  # Pop off `self` hint for methods
    return type_hints, ret_ann