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 provided by cmd2 for argument processing, 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.