Utility Functions¶
-
cmd2.utils.
is_quoted
(arg: str) → bool¶ Checks if a string is quoted
Parameters: arg – the string being checked for quotes Returns: True if a string is quoted
-
cmd2.utils.
quote_string_if_needed
(arg: str) → str¶ Quote a string if it contains spaces and isn’t already quoted
-
cmd2.utils.
strip_quotes
(arg: str) → str¶ Strip outer quotes from a string.
Applies to both single and double quotes.Parameters: arg – string to strip outer quotes from Returns: same string with potentially outer quotes stripped
-
cmd2.decorators.
categorize
(func: Union[Callable, Iterable[Callable]], category: str) → None¶ Categorize a function.
The help command output will group this function under the specified category heading
Parameters: - func – function or list of functions to categorize
- category – category to put it in
-
cmd2.utils.
align_text
(text: str, alignment: cmd2.utils.TextAlignment, *, fill_char: str = ' ', width: Optional[int] = None, tab_width: int = 4, truncate: bool = False) → str¶ Align text for display within a given width. Supports characters with display widths greater than 1. ANSI style sequences are safely ignored and do not count toward the display width. This means colored text is supported. If text has line breaks, then each line is aligned independently.
There are convenience wrappers around this function: align_left(), align_center(), and align_right()
Parameters: - text – text to align (can contain multiple lines)
- alignment – how to align the text
- fill_char – character that fills the alignment gap. Defaults to space. (Cannot be a line breaking character)
- width – display width of the aligned text. Defaults to width of the terminal.
- tab_width – any tabs in the text will be replaced with this many spaces. if fill_char is a tab, then it will be converted to a space.
- truncate – if True, then each line will be shortened to fit within the display width. The truncated portions are replaced by a ‘…’ character. Defaults to False.
Returns: aligned text
Raises: TypeError if fill_char is more than one character ValueError if text or fill_char contains an unprintable character ValueError if width is less than 1
-
cmd2.utils.
align_left
(text: str, *, fill_char: str = ' ', width: Optional[int] = None, tab_width: int = 4, truncate: bool = False) → str¶ Left align text for display within a given width. Supports characters with display widths greater than 1. ANSI style sequences are safely ignored and do not count toward the display width. This means colored text is supported. If text has line breaks, then each line is aligned independently.
Parameters: - text – text to left align (can contain multiple lines)
- fill_char – character that fills the alignment gap. Defaults to space. (Cannot be a line breaking character)
- width – display width of the aligned text. Defaults to width of the terminal.
- tab_width – any tabs in the text will be replaced with this many spaces. if fill_char is a tab, then it will be converted to a space.
- truncate – if True, then text will be shortened to fit within the display width. The truncated portion is replaced by a ‘…’ character. Defaults to False.
Returns: left-aligned text
Raises: TypeError if fill_char is more than one character ValueError if text or fill_char contains an unprintable character ValueError if width is less than 1
-
cmd2.utils.
align_center
(text: str, *, fill_char: str = ' ', width: Optional[int] = None, tab_width: int = 4, truncate: bool = False) → str¶ Center text for display within a given width. Supports characters with display widths greater than 1. ANSI style sequences are safely ignored and do not count toward the display width. This means colored text is supported. If text has line breaks, then each line is aligned independently.
Parameters: - text – text to center (can contain multiple lines)
- fill_char – character that fills the alignment gap. Defaults to space. (Cannot be a line breaking character)
- width – display width of the aligned text. Defaults to width of the terminal.
- tab_width – any tabs in the text will be replaced with this many spaces. if fill_char is a tab, then it will be converted to a space.
- truncate – if True, then text will be shortened to fit within the display width. The truncated portion is replaced by a ‘…’ character. Defaults to False.
Returns: centered text
Raises: TypeError if fill_char is more than one character ValueError if text or fill_char contains an unprintable character ValueError if width is less than 1
-
cmd2.utils.
align_right
(text: str, *, fill_char: str = ' ', width: Optional[int] = None, tab_width: int = 4, truncate: bool = False) → str¶ Right align text for display within a given width. Supports characters with display widths greater than 1. ANSI style sequences are safely ignored and do not count toward the display width. This means colored text is supported. If text has line breaks, then each line is aligned independently.
Parameters: - text – text to right align (can contain multiple lines)
- fill_char – character that fills the alignment gap. Defaults to space. (Cannot be a line breaking character)
- width – display width of the aligned text. Defaults to width of the terminal.
- tab_width – any tabs in the text will be replaced with this many spaces. if fill_char is a tab, then it will be converted to a space.
- truncate – if True, then text will be shortened to fit within the display width. The truncated portion is replaced by a ‘…’ character. Defaults to False.
Returns: right-aligned text
Raises: TypeError if fill_char is more than one character ValueError if text or fill_char contains an unprintable character ValueError if width is less than 1
-
cmd2.utils.
truncate_line
(line: str, max_width: int, *, tab_width: int = 4) → str¶ Truncate a single line to fit within a given display width. Any portion of the string that is truncated is replaced by a ‘…’ character. Supports characters with display widths greater than 1. ANSI style sequences are safely ignored and do not count toward the display width. This means colored text is supported.
Parameters: - line – text to truncate
- max_width – the maximum display width the resulting string is allowed to have
- tab_width – any tabs in the text will be replaced with this many spaces
Returns: line that has a display width less than or equal to width
Raises: ValueError if text contains an unprintable character like a new line ValueError if max_width is less than 1
-
cmd2.utils.
strip_quotes
(arg: str) → str Strip outer quotes from a string.
Applies to both single and double quotes.Parameters: arg – string to strip outer quotes from Returns: same string with potentially outer quotes stripped
-
cmd2.utils.
namedtuple_with_defaults
(typename: str, field_names: Union[str, List[str]], default_values: collections.abc.Iterable = ())¶ Convenience function for defining a namedtuple with default values
- Examples:
>>> Node = namedtuple_with_defaults('Node', 'val left right') >>> Node() Node(val=None, left=None, right=None) >>> Node = namedtuple_with_defaults('Node', 'val left right', [1, 2, 3]) >>> Node() Node(val=1, left=2, right=3) >>> Node = namedtuple_with_defaults('Node', 'val left right', {'right':7}) >>> Node() Node(val=None, left=None, right=7) >>> Node(4) Node(val=4, left=None, right=7)
-
cmd2.utils.
cast
(current: Any, new: str) → Any¶ Tries to force a new value into the same type as the current when trying to set the value for a parameter.
Parameters: - current – current value for the parameter, type varies
- new – new value
Returns: new value with same type as current, or the current value if there was an error casting
-
cmd2.utils.
which
(exe_name: str) → Optional[str]¶ Find the full path of a given executable on a Linux or Mac machine
Parameters: exe_name – name of the executable to check, ie ‘vi’ or ‘ls’ Returns: a full path or None if exe not found
-
cmd2.utils.
is_text_file
(file_path: str) → bool¶ Returns if a file contains only ASCII or UTF-8 encoded text.
Parameters: file_path – path to the file being checked Returns: True if the file is a text file, False if it is binary.
-
cmd2.utils.
remove_duplicates
(list_to_prune: List[T]) → List[T]¶ Removes duplicates from a list while preserving order of the items.
Parameters: list_to_prune – the list being pruned of duplicates Returns: The pruned list
-
cmd2.utils.
norm_fold
(astr: str) → str¶ Normalize and casefold Unicode strings for saner comparisons.
Parameters: astr – input unicode string Returns: a normalized and case-folded version of the input string
-
cmd2.utils.
try_int_or_force_to_lower_case
(input_str: str) → Union[int, str]¶ Tries 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
-
cmd2.utils.
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)
Parameters: list_to_sort – the list being sorted Returns: the sorted list
-
cmd2.utils.
unquote_specific_tokens
(args: List[str], tokens_to_unquote: List[str]) → None¶ Unquote a specific tokens in a list of command-line arguments This is used when certain tokens have to be passed to another command :param args: the command line args :param tokens_to_unquote: the tokens, which if present in args, to unquote
-
cmd2.utils.
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)
Parameters: list_to_sort – the list being sorted Returns: the list sorted naturally
-
cmd2.utils.
natural_keys
(input_str: str) → List[Union[int, str]]¶ Converts 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
-
cmd2.utils.
expand_user_in_tokens
(tokens: List[str]) → None¶ Call expand_user() on all tokens in a list of strings :param tokens: tokens to expand
-
cmd2.utils.
expand_user
(token: str) → str¶ Wrap os.expanduser() to support expanding ~ in quoted strings :param token: the string to expand
-
cmd2.utils.
find_editor
() → str¶ Find a reasonable editor to use by default for the system that the cmd2 application is running on.
-
cmd2.utils.
get_exes_in_path
(starts_with: str) → List[str]¶ Returns names of executables in a user’s path
Parameters: starts_with – what the exes should start with. leave blank for all exes in path. Returns: a list of matching exe names
-
cmd2.utils.
files_from_glob_patterns
(patterns: List[str], access=0) → 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.
Parameters: - patterns – list of file names and/or glob patterns
- access – file access type to verify (os.* where * is F_OK, R_OK, W_OK, or X_OK)
Returns: list of files matching the names and/or glob patterns
-
cmd2.utils.
files_from_glob_pattern
(pattern: str, access=0) → 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.
Parameters: - pattern – file name or glob pattern
- access – file access type to verify (os.* where * is F_OK, R_OK, W_OK, or X_OK)
Returns: list of files matching the name or glob pattern