From 5fd8e00010e068eb0632b6cb20860a18774181a5 Mon Sep 17 00:00:00 2001 From: Kevin Van Brunt Date: Thu, 23 Apr 2020 16:35:17 -0400 Subject: Documented CompletionError class --- docs/features/completion.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs/features') diff --git a/docs/features/completion.rst b/docs/features/completion.rst index 3a2c50e0..0735893a 100644 --- a/docs/features/completion.rst +++ b/docs/features/completion.rst @@ -34,6 +34,24 @@ similar to the following to your class which inherits from :class:`cmd2.Cmd`:: complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, path_filter=os.path.isdir) +Raising exceptions during completion +------------------------------------ +There are times when tab completion fails 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 :class:`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 ---------------------------------------- -- cgit v1.2.1