diff options
| -rw-r--r-- | cmd2/__init__.py | 1 | ||||
| -rw-r--r-- | cmd2/cmd2.py | 14 | ||||
| -rw-r--r-- | cmd2/exceptions.py | 27 | ||||
| -rw-r--r-- | docs/api/exceptions.rst | 11 | ||||
| -rw-r--r-- | docs/api/index.rst | 28 | ||||
| -rw-r--r-- | tests/test_plugin.py | 15 |
6 files changed, 71 insertions, 25 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 diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst new file mode 100644 index 00000000..8ef0a61f --- /dev/null +++ b/docs/api/exceptions.rst @@ -0,0 +1,11 @@ +cmd2.exceptions +=============== + +Custom cmd2 exceptions + + +.. autoclass:: cmd2.exceptions.SkipPostcommandHooks + :members: + +.. autoclass:: cmd2.exceptions.Cmd2ArgparseError + :members: diff --git a/docs/api/index.rst b/docs/api/index.rst index 7b66a684..cc899ba1 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -19,37 +19,39 @@ This documentation is for ``cmd2`` version |version|. :hidden: cmd - decorators - parsing + ansi argparse_completer argparse_custom - ansi - utils + constants + decorators + exceptions history + parsing plugin py_bridge table_creator - constants + utils **Modules** - :ref:`api/cmd:cmd2.Cmd` - functions and attributes of the main class in this library -- :ref:`api/decorators:cmd2.decorators` - decorators for ``cmd2`` - commands -- :ref:`api/parsing:cmd2.parsing` - classes for parsing and storing - user input +- :ref:`api/ansi:cmd2.ansi` - convenience classes and functions for generating + ANSI escape sequences to style text in the terminal - :ref:`api/argparse_completer:cmd2.argparse_completer` - classes for ``argparse``-based tab completion - :ref:`api/argparse_custom:cmd2.argparse_custom` - classes and functions for extending ``argparse`` -- :ref:`api/ansi:cmd2.ansi` - convenience classes and functions for generating - ANSI escape sequences to style text in the terminal -- :ref:`api/utils:cmd2.utils` - various utility classes and functions +- :ref:`api/constants:cmd2.constants` - just like it says on the tin +- :ref:`api/decorators:cmd2.decorators` - decorators for ``cmd2`` + commands +- :ref:`api/exceptions:cmd2.exceptions` - custom ``cmd2`` exceptions - :ref:`api/history:cmd2.history` - classes for storing the history of previously entered commands +- :ref:`api/parsing:cmd2.parsing` - classes for parsing and storing + user input - :ref:`api/plugin:cmd2.plugin` - data classes for hook methods - :ref:`api/py_bridge:cmd2.py_bridge` - classes for bridging calls from the embedded python environment to the host app - :ref:`api/table_creator:cmd2.table_creator` - table creation module -- :ref:`api/constants:cmd2.constants` - just like it says on the tin +- :ref:`api/utils:cmd2.utils` - various utility classes and functions diff --git a/tests/test_plugin.py b/tests/test_plugin.py index 132361a6..f7eb7e39 100644 --- a/tests/test_plugin.py +++ b/tests/test_plugin.py @@ -256,6 +256,10 @@ class PluggedApp(Plugin, cmd2.Cmd): """Repeat back the arguments""" self.poutput(statement) + def do_skip_postcmd_hooks(self, _): + self.poutput("In do_skip_postcmd_hooks") + raise exceptions.SkipPostcommandHooks + parser = Cmd2ArgumentParser(description="Test parser") parser.add_argument("my_arg", help="some help text") @@ -847,6 +851,17 @@ def test_cmdfinalization_hook_exception(capsys): assert err assert app.called_cmdfinalization == 1 +def test_skip_postcmd_hooks(capsys): + app = PluggedApp() + app.register_postcmd_hook(app.postcmd_hook) + app.register_cmdfinalization_hook(app.cmdfinalization_hook) + + # Cause a SkipPostcommandHooks exception and verify no postcmd stuff runs but cmdfinalization_hook still does + app.onecmd_plus_hooks('skip_postcmd_hooks') + out, err = capsys.readouterr() + assert "In do_skip_postcmd_hooks" in out + assert app.called_postcmd == 0 + assert app.called_cmdfinalization == 1 def test_cmd2_argparse_exception(capsys): """ |