cmd2.argparse_custom

This module adds capabilities to argparse by patching a few of its functions. It also defines a parser class called Cmd2ArgumentParser which improves error and help output over normal argparse. All cmd2 code uses this parser and it is recommended that developers of cmd2-based apps either use it or write their own parser that inherits from it. This will give a consistent look-and-feel between the help/error output of built-in cmd2 commands and the app-specific commands. If you wish to override the parser used by cmd2’s built-in commands, see override_parser.py example.

Since the new capabilities are added by patching at the argparse API level, they are available whether or not Cmd2ArgumentParser is used. However, the help and error output of Cmd2ArgumentParser is customized to notate nargs ranges whereas any other parser class won’t be as explicit in their output.

Added capabilities

Extends argparse nargs functionality by allowing tuples which specify a range (min, max). To specify a max value with no upper bound, use a 1-item tuple (min,)

Example:

# -f argument expects at least 3 values
parser.add_argument('-f', nargs=(3,))

# -f argument expects 3 to 5 values
parser.add_argument('-f', nargs=(3, 5))

Tab Completion

cmd2 uses its ArgparseCompleter class to enable argparse-based tab completion on all commands that use the @with_argparse wrappers. Out of the box you get tab completion of commands, subcommands, and flag names, as well as instructive hints about the current argument that print when tab is pressed. In addition, you can add tab completion for each argument’s values using parameters passed to add_argument().

Below are the 5 add_argument() parameters for enabling tab completion of an argument’s value. Only one can be used at a time.

choices - pass a list of values to the choices parameter.

Example:

parser.add_argument('-o', '--options', choices=['An Option', 'SomeOtherOption'])
parser.add_argument('-o', '--options', choices=my_list)

choices_function - pass a function that returns choices. This is good in cases where the choice list is dynamically generated when the user hits tab.

Example:

def my_choices_function():
    ...
    return my_generated_list

parser.add_argument('-o', '--options', choices_function=my_choices_function)

choices_method - this is equivalent to choices_function, but the function needs to be an instance method of a cmd2.Cmd or cmd2.CommandSet subclass. When ArgparseCompleter calls the method, it well detect whether is is bound to a CommandSet or Cmd subclass. If bound to a cmd2.Cmd subclass, it will pass the app instance as the self argument. This is good in cases where the list of choices being generated relies on state data of the cmd2-based app. If bound to a cmd2.CommandSet subclass, it will pass the CommandSet instance as the self argument.

Example:

def my_choices_method(self):
    ...
    return my_generated_list

parser.add_argument("arg", choices_method=my_choices_method)

completer_function - pass a tab completion function that does custom completion. Since custom tab completion operations commonly need to modify cmd2’s instance variables related to tab completion, it will be rare to need a completer function. completer_method should be used in those cases.

Example:

def my_completer_function(text, line, begidx, endidx):
    ...
    return completions
parser.add_argument('-o', '--options', completer_function=my_completer_function)

completer_method - this is equivalent to completer_function, but the function needs to be an instance method of a cmd2.Cmd or cmd2.CommandSet subclass. When ArgparseCompleter calls the method, it well detect whether is is bound to a CommandSet or Cmd subclass. If bound to a cmd2.Cmd subclass, it will pass the app instance as the self argument. This is good in cases where the list of choices being generated relies on state data of the cmd2-based app. If bound to a cmd2.CommandSet subclass, it will pass the CommandSet instance as the self argument, and the app instance as the positional argument. cmd2 provides a few completer methods for convenience (e.g., path_complete, delimiter_complete)

Example:

# This adds file-path completion to an argument
parser.add_argument('-o', '--options', completer_method=cmd2.Cmd.path_complete)

You can use functools.partial() to prepopulate values of the underlying choices and completer functions/methods.

Example:

# This says to call path_complete with a preset value for its path_filter argument
completer_method = functools.partial(path_complete,
                                     path_filter=lambda path: os.path.isdir(path))
parser.add_argument('-o', '--options', choices_method=completer_method)

Of the 5 tab completion parameters, choices is the only one where argparse validates user input against items in the choices list. This is because the other 4 parameters are meant to tab complete data sets that are viewed as dynamic. Therefore it is up to the developer to validate if the user has typed an acceptable value for these arguments.

The following functions exist in cases where you may want to manually add a choice-providing function/method to an existing argparse action. For instance, in __init__() of a custom action class.

  • set_choices_function(action, func)
  • set_choices_method(action, method)
  • set_completer_function(action, func)
  • set_completer_method(action, method)

There are times when what’s being tab completed is determined by a previous argument on the command line. In theses cases, Autocompleter can pass a dictionary that maps the command line tokens up through the one being completed to their argparse argument name. To receive this dictionary, your choices/completer function should have an argument called arg_tokens.

Example:

def my_choices_method(self, arg_tokens)
def my_completer_method(self, text, line, begidx, endidx, arg_tokens)

All values of the arg_tokens dictionary are lists, even if a particular argument expects only 1 token. Since ArgparseCompleter is for tab completion, it does not convert the tokens to their actual argument types or validate their values. All tokens are stored in the dictionary as the raw strings provided on the command line. It is up to the developer to determine if the user entered the correct argument type (e.g. int) and validate their values.

CompletionItem Class - This class was added to help in cases where uninformative data is being tab completed. For instance, tab completing ID numbers isn’t very helpful to a user without context. Returning a list of CompletionItems instead of a regular string for completion results will signal the ArgparseCompleter to output the completion results in a table of completion tokens with descriptions instead of just a table of tokens:

Instead of this:
    1     2     3

The user sees this:
    ITEM_ID     Item Name
    1           My item
    2           Another item
    3           Yet another item

The left-most column is the actual value being tab completed and its header is that value’s name. The right column header is defined using the descriptive_header parameter of add_argument(). The right column values come from the CompletionItem.description value.

Example:

token = 1
token_description = "My Item"
completion_item = CompletionItem(token, token_description)

Since descriptive_header and CompletionItem.description are just strings, you can format them in such a way to have multiple columns:

ITEM_ID     Item Name            Checked Out    Due Date
1           My item              True           02/02/2022
2           Another item         False
3           Yet another item     False

To use CompletionItems, just return them from your choices or completer functions.

To avoid printing a ton of information to the screen at once when a user presses tab, there is a maximum threshold for the number of CompletionItems that will be shown. Its value is defined in cmd2.Cmd.max_completion_items. It defaults to 50, but can be changed. If the number of completion suggestions exceeds this number, they will be displayed in the typical columnized format and will not include the description value of the CompletionItems.

Patched argparse functions

argparse._ActionsContainer.add_argument - adds arguments related to tab completion and enables nargs range parsing. See _add_argument_wrapper for more details on these arguments.

argparse.ArgumentParser._get_nargs_pattern - adds support for nargs ranges. See _get_nargs_pattern_wrapper for more details.

argparse.ArgumentParser._match_argument - adds support for nargs ranges. See _match_argument_wrapper for more details.

argparse._SubParsersAction.remove_parser - new function which removes a sub-parser from a sub-parsers group. See _SubParsersAction_remove_parser for more details.

class cmd2.argparse_custom.ChoicesCallable(is_method: bool, is_completer: bool, to_call: Callable)

Enables using a callable as the choices provider for an argparse argument. While argparse has the built-in choices attribute, it is limited to an iterable.

class cmd2.argparse_custom.Cmd2ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=None, formatter_class=<class 'cmd2.argparse_custom.Cmd2HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True)

Custom ArgumentParser class that improves error and help output

add_subparsers(**kwargs)

Custom override. Sets a default title if one was not given.

Parameters:kwargs – additional keyword arguments
Returns:argparse Subparser Action
error(message: str) → None

Custom override that applies custom formatting to the error message

format_help() → str

Copy of format_help() from argparse.ArgumentParser with tweaks to separately display required parameters

class cmd2.argparse_custom.Cmd2AttributeWrapper(attribute: Any)

Wraps a cmd2-specific attribute added to an argparse Namespace. This makes it easy to know which attributes in a Namespace are arguments from a parser and which were added by cmd2.

get() → Any

Get the value of the attribute

set(new_val: Any) → None

Set the value of the attribute

class cmd2.argparse_custom.Cmd2HelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Custom help formatter to configure ordering of help text

class cmd2.argparse_custom.CompletionItem(value: object, desc: str = '', *args, **kwargs)

Completion item with descriptive text attached

See header of this file for more information

cmd2.argparse_custom.DEFAULT_ARGUMENT_PARSER

alias of cmd2.argparse_custom.Cmd2ArgumentParser

cmd2.argparse_custom.generate_range_error(range_min: int, range_max: Union[int, float]) → str

Generate an error message when the the number of arguments provided is not within the expected range

cmd2.argparse_custom.set_choices_function(action: argparse.Action, choices_function: Callable) → None

Set choices_function on an argparse action

cmd2.argparse_custom.set_choices_method(action: argparse.Action, choices_method: Callable) → None

Set choices_method on an argparse action

cmd2.argparse_custom.set_completer_function(action: argparse.Action, completer_function: Callable) → None

Set completer_function on an argparse action

cmd2.argparse_custom.set_completer_method(action: argparse.Action, completer_method: Callable) → None

Set completer_method on an argparse action

cmd2.argparse_custom.set_default_argument_parser(parser: Type[argparse.ArgumentParser]) → None

Set the default ArgumentParser class for a cmd2 app