Completion

cmd2 adds tab-completion of file system paths for all built-in commands where it makes sense, including:

  • edit
  • run_pyscript
  • run_script
  • shell

cmd2 also adds tab-completion of shell commands to the shell command.

Additionally, it is trivial to add identical file system path completion to your own custom commands. Suppose you have defined a custom command foo by implementing the do_foo method. To enable path completion for the foo command, then add a line of code similar to the following to your class which inherits from cmd2.Cmd:

complete_foo = self.path_complete

This will effectively define the complete_foo readline completer method in your class and make it utilize the same path completion logic as the built-in commands.

The built-in logic allows for a few more advanced path completion capabilities, such as cases where you only want to match directories. Suppose you have a custom command bar implemented by the do_bar method. You can enable path completion of directories only for this command by adding a line of code similar to the following to your class which inherits from cmd2.Cmd:

# Make sure you have an "import functools" somewhere at the top
complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, path_filter=os.path.isdir)

Tab Completion Using Argparse Decorators

When using one the Argparse-based Decorators, cmd2 provides automatic tab-completion of flag names.

Tab-completion of argument values can be configured by using one of five parameters to argparse.ArgumentParser.add_argument()

  • choices
  • choices_function / choices_method
  • completer_function / completer_method

See the arg_decorators or colors example for a demonstration of how to use the choices parameter. See the tab_autocompletion example for a demonstration of how to use the choices_function and choices_method parameters. See the arg_decorators or tab_autocompletion example for a demonstration of how to use the completer_method parameter.

When tab-completing flags and/or argument values for a cmd2 command using one of these decorators, cmd2 keeps track of state so that once a flag has already previously been provided, it won’t attempt to tab-complete it again. When no completion results exists, a hint for the current argument will be displayed to help the user.

CompletionItem For Providing Extra Context

When tab-completing things like a unique ID from a database, it can often be beneficial to provide the user with some extra context about the item being completed, such as a description. To facilitate this, cmd2 defines the CompletionItem class which can be returned from any of the 4 completion functions: choices_function, choices_method, completion_function, or completion_method.

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

See the tab_autocompletion example or the implementation of the built-in set command for demonstration of how this is used.