diff options
| -rw-r--r-- | cmd2/utils.py | 8 | ||||
| -rw-r--r-- | docs/features/completion.rst | 18 |
2 files changed, 22 insertions, 4 deletions
diff --git a/cmd2/utils.py b/cmd2/utils.py index 3fd9e3ac..5a4fdbf7 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -74,12 +74,12 @@ def str_to_bool(val: str) -> bool: class CompletionError(Exception): """ - Raised during tab completion operations to report any sort of error you want printed by the ArgparseCompleter - This can also be used just to display a message, even if it's not an error. ArgparseCompleter raises - CompletionErrors to display tab completion hints and sets apply_style to False so hints aren't colored - like error text. + Raised during tab completion operations to report any sort of error you want printed. This can also be used + just to display a message, even if it's not an error. For instance, ArgparseCompleter raises CompletionErrors + to display tab completion hints and sets apply_style to False so hints aren't colored like error text. Example use 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 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 ---------------------------------------- |