Completion¶
cmd2.Cmd
adds tab completion of file system paths for all built-in
commands where it makes sense, including:
cmd2.Cmd
also adds tab completion of shell commands to the
shell command.
It is easy 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 = cmd2.Cmd.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)
Included Tab Completion Functions¶
cmd2
provides the following tab completion functions
cmd2.utils.basic_complete
- helper method for tab completion against a listcmd2.Cmd.path_complete
- helper method provides flexible tab completion of file system paths- See the paged_output example for a simple use case
- See the python_scripting example for a more full-featured use case
cmd2.Cmd.delimiter_complete
- helper method for tab completion against a list but each match is split on a delimiter- See the basic_completion example for a demonstration of how to use this feature
cmd2.Cmd.flag_based_complete
- helper method for tab completion based on a particular flag preceding the token being completedcmd2.Cmd.index_based_complete
- helper method for tab completion based on a fixed position in the input string- See the basic_completion example for a demonstration of how to use these features
flag_based_complete()
andindex_based_complete()
are basic methods and should only be used if you are not familiar with argparse. The recommended approach for tab completing positional tokens and flags is to use argparse-based completion.
Raising Exceptions During Completion¶
There are times when an error occurs while tab completing and a message needs to be reported to the user. These include the following example cases:
- Reading a database to retrieve a tab completion data set failed
- A previous command line argument that determines the data set being completed is invalid
- Tab completion hints
cmd2
provides the cmd2.utils.CompletionError
exception class for
this capability. If an error occurs in which it is more desirable to display
a message than a stack trace, then raise a CompletionError
. By default, the
message displays in red like an error. However, CompletionError
has a
member called apply_style
. Set this False if the error style should not be
applied. For instance, ArgparseCompleter
sets it to False when displaying
completion hints.
Tab Completion Using argparse Decorators¶
When using one the argparse-based cmd2.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
orchoices_method
completer_function
orcompleter_method
See the arg_decorators or colors example for a demonstration of how to
use the choices
parameter. See the argparse_completion example for a
demonstration of how to use the choices_function
and choices_method
parameters. See the arg_decorators or argparse_completion example for a
demonstration of how to use the completer_method
parameter.
When tab completing flags 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
cmd2.argparse_custom.CompletionItem
class which can be returned from
any of the 4 completion functions: choices_function
, choices_method
,
completion_function
, or completion_method
.
See the argparse_completion example or the implementation of the built-in
do_set()
command for demonstration of how this is used.
For More Information¶
See cmd2.argparse_custom
for a more detailed discussion of argparse
completion.