Skip to content

# 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, _T, _T], 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`

     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133

    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, _T, _T], 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`

    399
    400
    401
    402
    403
    404
    405
    406
    407
    408
    409
    410
    411
    412
    413
    414
    415
    416
    417
    418
    419

    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`

    421
    422
    423
    424
    425
    426
    427
    428
    429
    430
    431
    432

    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`

    434
    435
    436

    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`

    438
    439
    440

    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`

    442
    443
    444
    445
    446
    447
    448
    449
    450
    451
    452
    453
    454

    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`

    456
    457
    458
    459
    460

    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`

    462
    463
    464

    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`

    466
    467
    468
    469
    470

    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`

    496
    497
    498
    499

    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`

    501
    502
    503
    504
    505
    506
    507
    508
    509
    510
    511
    512
    513
    514
    515

    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`

    524
    525
    526
    527
    528
    529
    530
    531
    532
    533
    534
    535
    536
    537
    538
    539
    540
    541
    542
    543

    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 <Ctrl>+C were pressed.

Source code in `cmd2/utils.py`

    545
    546
    547
    548
    549
    550
    551
    552
    553
    554
    555
    556
    557
    558
    559
    560

    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`

    562
    563
    564

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

#### `` wait

    wait()

Wait for the process to finish.

Source code in `cmd2/utils.py`

    566
    567
    568
    569
    570
    571
    572
    573
    574
    575
    576
    577
    578
    579
    580

    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`

    628
    629
    630
    631
    632
    633

    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`

    653
    654
    655
    656
    657
    658
    659
    660
    661
    662
    663
    664
    665
    666
    667
    668
    669
    670
    671
    672
    673
    674
    675
    676

    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`

    756
    757
    758
    759
    760
    761
    762
    763
    764
    765
    766
    767

    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`

    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64

    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`

    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185

    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`

    188
    189
    190
    191
    192
    193
    194
    195

    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`

    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210

    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`

    213
    214
    215
    216
    217
    218
    219
    220
    221
    222

    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`

    225
    226
    227
    228
    229
    230
    231
    232

    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`

    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247

    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`

    250
    251
    252
    253
    254
    255
    256
    257
    258

    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`

    261
    262
    263
    264
    265
    266
    267
    268
    269
    270

    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`

    273
    274
    275
    276
    277
    278
    279
    280
    281
    282
    283
    284
    285
    286
    287
    288
    289
    290
    291

    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`

    294
    295
    296
    297
    298
    299
    300

    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`

    303
    304
    305
    306
    307
    308
    309
    310
    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326
    327
    328
    329
    330
    331
    332

    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`

    335
    336
    337
    338
    339
    340
    341
    342
    343
    344

    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`

    347
    348
    349
    350
    351
    352
    353
    354
    355
    356
    357
    358
    359
    360

    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`

    363
    364
    365
    366
    367
    368
    369
    370
    371
    372
    373
    374
    375
    376
    377
    378
    379
    380
    381
    382
    383
    384
    385
    386
    387
    388
    389
    390

    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`

    679
    680
    681
    682
    683
    684
    685
    686
    687
    688
    689
    690
    691
    692
    693
    694
    695
    696
    697
    698
    699
    700
    701
    702
    703
    704
    705
    706
    707

    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`

    710
    711
    712
    713
    714
    715
    716
    717
    718
    719
    720
    721
    722
    723
    724
    725
    726
    727
    728
    729
    730
    731
    732

    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`

    770
    771
    772
    773
    774
    775
    776
    777
    778
    779
    780
    781
    782
    783
    784
    785
    786
    787
    788
    789
    790
    791
    792

    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`

    795
    796
    797
    798
    799
    800

    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`

    806
    807
    808
    809
    810
    811
    812
    813
    814
    815
    816
    817
    818
    819
    820
    821
    822
    823
    824
    825

    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`

    828
    829
    830
    831
    832
    833
    834
    835
    836
    837
    838
    839
    840
    841
    842
    843
    844
    845
    846

    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