Merge pull request #929 from python-cmd2/completion_docs

Completion docs

Author: kmvanbrunt

README.md

@@ -171,16 +171,18 @@ Instructions for implementing each feature follow.
         - And also provide help hints for values associated with these flags
         - Experiment with the [argprint.py](https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py) example
         using the **oprint** and **pprint** commands to get a feel for how this works
+    - `basic_complete` helper method for tab completion against a list
     - `path_complete` helper method provides flexible tab completion of file system paths
         - See the [paged_output.py](https://github.com/python-cmd2/cmd2/blob/master/examples/paged_output.py) example for a simple use case
         - See the [python_scripting.py](https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py) example for a more full-featured use case
-    - `flag_based_complete` helper method for tab completion based on a particular flag preceding the token being completed
-        - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use this feature
-    - `index_based_complete` helper method for tab completion based on a fixed position in the input string
-        - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use this feature
-    - `basic_complete` helper method for tab completion against a list
     - `delimiter_complete` helper method for tab completion against a list but each match is split on a delimiter 
         - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use this feature
+    - `flag_based_complete` helper method for tab completion based on a particular flag preceding the token being completed
+    - `index_based_complete` helper method for tab completion based on a fixed position in the input string
+        - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use these features
+        - `flag_based_complete()` and `index_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
     - `cmd2` in combination with `argparse` also provide several advanced capabilities for automatic tab completion
         - See the [argparse_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/argparse_completion.py) example for more info
 

cmd2/argparse_custom.py

@@ -188,18 +188,15 @@ def my_completer_method(self, text, line, begidx, endidx, arg_tokens)
 
 **Patched argparse functions**
 
-argparse._ActionsContainer.add_argument - adds arguments related to tab
-                                          completion and enables nargs range
-                                          parsing See _add_argument_wrapper for
-                                          more details on these argument
-
-argparse.ArgumentParser._get_nargs_pattern - adds support to for nargs ranges
-                                             See _get_nargs_pattern_wrapper for
-                                             more details
-
-argparse.ArgumentParser._match_argument - adds support to for nargs ranges See
-                                          _match_argument_wrapper for more
-                                          details
+``argparse._ActionsContainer.add_argument`` - adds arguments related to tab
+completion and enables nargs range parsing. See _add_argument_wrapper for
+more details on these arguments.
+
+``argparse.ArgumentParser._get_nargs_pattern`` - adds support to for nargs
+ranges. See _get_nargs_pattern_wrapper for more details.
+
+``argparse.ArgumentParser._match_argument`` - adds support to for nargs ranges.
+See _match_argument_wrapper for more details.
 """
 
 import argparse

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

docs/features/completion.rst

@@ -34,10 +34,65 @@ 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)
 
 
-Tab Completion Using Argparse Decorators
+Included Tab Completion Functions
+---------------------------------
+``cmd2`` provides the following tab completion functions
+
+- :attr:`cmd2.utils.basic_complete` - helper method for tab completion against
+  a list
+- :attr:`cmd2.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
+
+- :attr:`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
+
+- :attr:`cmd2.Cmd.flag_based_complete` - helper method for tab completion based
+  on a particular flag preceding the token being completed
+- :attr:`cmd2.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()`` and ``index_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.
+
+.. _paged_output: https://github.com/python-cmd2/cmd2/blob/master/examples/paged_output.py
+.. _python_scripting: https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py
+.. _basic_completion: https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py
+
+
+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 :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.
+
+.. _argparse-based:
+
+Tab Completion Using argparse Decorators
 ----------------------------------------
 
-When using one the Argparse-based :ref:`api/decorators:cmd2.decorators`,
+When using one the argparse-based :ref:`api/decorators:cmd2.decorators`,
 ``cmd2`` provides automatic tab completion of flag names.
 
 Tab completion of argument values can be configured by using one of five
@@ -80,4 +135,5 @@ See the argparse_completion_ example or the implementation of the built-in
 For More Information
 --------------------
 
-See :mod:`cmd2.argparse_custom` for more details.
+See :mod:`cmd2.argparse_custom` for a more detailed discussion of argparse
+completion.

examples/basic_completion.py

@@ -4,7 +4,7 @@
 A simple example demonstrating how to enable tab completion by assigning a completer function to do_* commands.
 This also demonstrates capabilities of the following completer features included with cmd2:
 - CompletionError exceptions
-- delimiter_completer()
+- delimiter_complete()
 - flag_based_complete() (see note below)
 - index_based_complete() (see note below)