Added SkipPostcommandHooks exception and made Cmd2ArgparseError inherit from it.

Both exception classes have been added to the public API.

3 files changed, 30 insertions, 12 deletions

diff --git a/cmd2/__init__.py b/cmd2/__init__.py
index eb5c275d..d49427f2 100644
--- a/cmd2/__init__.py
+++ b/cmd2/__init__.py
@@ -25,6 +25,7 @@ from .argparse_custom import DEFAULT_ARGUMENT_PARSER
 from .cmd2 import Cmd
 from .constants import COMMAND_NAME, DEFAULT_SHORTCUTS
 from .decorators import with_argument_list, with_argparser, with_argparser_and_unknown_args, with_category
+from .exceptions import Cmd2ArgparseError, SkipPostcommandHooks
 from .parsing import Statement
 from .py_bridge import CommandResult
 from .utils import categorize, CompletionError, Settable
diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py
index 49c181f1..38fdd7b0 100644
--- a/cmd2/cmd2.py
+++ b/cmd2/cmd2.py
@@ -46,7 +46,7 @@ from . import ansi, constants, plugin, utils
 from .argparse_custom import DEFAULT_ARGUMENT_PARSER, CompletionItem
 from .clipboard import can_clip, get_paste_buffer, write_to_paste_buffer
 from .decorators import with_argparser
-from .exceptions import Cmd2ArgparseError, Cmd2ShlexError, EmbeddedConsoleExit, EmptyStatement, RedirectionError
+from .exceptions import Cmd2ShlexError, EmbeddedConsoleExit, EmptyStatement, RedirectionError, SkipPostcommandHooks
 from .history import History, HistoryItem
 from .parsing import Macro, MacroArg, Statement, StatementParser, shlex_split
 from .rl_utils import RlType, rl_get_point, rl_make_safe_prompt, rl_set_prompt, rl_type, rl_warning, vt100_support
@@ -1670,7 +1670,7 @@ class Cmd(cmd.Cmd):
         except KeyboardInterrupt as ex:
             if raise_keyboard_interrupt:
                 raise ex
-        except (Cmd2ArgparseError, EmptyStatement):
+        except (SkipPostcommandHooks, EmptyStatement):
             # Don't do anything, but do allow command finalization hooks to run
             pass
         except Cmd2ShlexError as ex:
@@ -3894,7 +3894,7 @@ class Cmd(cmd.Cmd):
 
         IMPORTANT: This function will not print an alert unless it can acquire self.terminal_lock to ensure
                    a prompt is onscreen.  Therefore it is best to acquire the lock before calling this function
-                   to guarantee the alert prints.
+                   to guarantee the alert prints and to avoid raising a RuntimeError.
 
         :param alert_msg: the message to display to the user
         :param new_prompt: if you also want to change the prompt that is displayed, then include it here
@@ -3956,7 +3956,7 @@ class Cmd(cmd.Cmd):
 
         IMPORTANT: This function will not update the prompt unless it can acquire self.terminal_lock to ensure
                    a prompt is onscreen.  Therefore it is best to acquire the lock before calling this function
-                   to guarantee the prompt changes.
+                   to guarantee the prompt changes and to avoid raising a RuntimeError.
 
                    If user is at a continuation prompt while entering a multiline command, the onscreen prompt will
                    not change. However self.prompt will still be updated and display immediately after the multiline
@@ -3971,9 +3971,9 @@ class Cmd(cmd.Cmd):
 
         Raises a `RuntimeError` if called while another thread holds `terminal_lock`.
 
-        IMPORTANT: This function will not set the title unless it can acquire self.terminal_lock to avoid
-                   writing to stderr while a command is running. Therefore it is best to acquire the lock
-                   before calling this function to guarantee the title changes.
+        IMPORTANT: This function will not set the title unless it can acquire self.terminal_lock to avoid writing
+                   to stderr while a command is running. Therefore it is best to acquire the lock before calling
+                   this function to guarantee the title changes and to avoid raising a RuntimeError.
 
         :param title: the new window title
         """
diff --git a/cmd2/exceptions.py b/cmd2/exceptions.py
index 635192e1..d0a922db 100644
--- a/cmd2/exceptions.py
+++ b/cmd2/exceptions.py
@@ -1,16 +1,33 @@
 # coding=utf-8
-"""Custom exceptions for cmd2.  These are NOT part of the public API and are intended for internal use only."""
+"""Custom exceptions for cmd2"""
 
 
-class Cmd2ArgparseError(Exception):
+############################################################################################################
+# The following exceptions are part of the public API
+############################################################################################################
+
+class SkipPostcommandHooks(Exception):
     """
-    Custom exception class for when a command has an error parsing its arguments.
-    This can be raised by argparse decorators or the command functions themselves.
-    The main use of this exception is to tell cmd2 not to run Postcommand hooks.
+    Custom exception class for when a command has a failure bad enough to skip post command
+    hooks, but not bad enough to print the exception to the user.
     """
     pass
 
 
+class Cmd2ArgparseError(SkipPostcommandHooks):
+    """
+    A ``SkipPostcommandHooks`` exception for when a command fails parsing its arguments.
+    This is raised by argparse decorators but can also be raised by command functions.
+    If a command function still needs to run post command hooks when parsing fails,
+    just return instead of raising an exception.
+    """
+    pass
+
+
+############################################################################################################
+# The following exceptions are NOT part of the public API and are intended for internal use only.
+############################################################################################################
+
 class Cmd2ShlexError(Exception):
     """Raised when shlex fails to parse a command line string in StatementParser"""
     pass