diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/exceptions.rst | 11 | ||||
| -rw-r--r-- | docs/api/index.rst | 28 | ||||
| -rw-r--r-- | docs/features/commands.rst | 15 | ||||
| -rw-r--r-- | docs/features/hooks.rst | 6 |
4 files changed, 46 insertions, 14 deletions
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/docs/features/commands.rst b/docs/features/commands.rst index 823c3ca6..13a4ac1f 100644 --- a/docs/features/commands.rst +++ b/docs/features/commands.rst @@ -129,7 +129,7 @@ it should stop prompting for user input and cleanly exit. ``cmd2`` already includes a ``quit`` command, but if you wanted to make another one called ``finis`` you could:: - def do_finis(self, line): + def do_finish(self, line): """Exit the application""" return True @@ -186,6 +186,19 @@ catch it and display it for you. The `debug` :ref:`setting name and message. If `debug` is `true`, ``cmd2`` will display a traceback, and then display the exception name and message. +There are a few exceptions which commands can raise that do not print as +described above: + +- :attr:`cmd2.exceptions.SkipPostcommandHooks` - all postcommand hooks are + skipped and no exception prints +- :attr:`cmd2.exceptions.Cmd2ArgparseError` - behaves like + ``SkipPostcommandHooks`` +- ``SystemExit`` - ``stop`` will be set to ``True`` in an attempt to stop the + command loop +- ``KeyboardInterrupt`` - raised if running in a text script and ``stop`` isn't + already True to stop the script + +All other ``BaseExceptions`` are not caught by ``cmd2`` and will be raised Disabling or Hiding Commands ---------------------------- diff --git a/docs/features/hooks.rst b/docs/features/hooks.rst index fec8e258..4c615586 100644 --- a/docs/features/hooks.rst +++ b/docs/features/hooks.rst @@ -291,6 +291,12 @@ blindly returns ``False``, a prior hook's requst to exit the application will not be honored. It's best to return the value you were passed unless you have a compelling reason to do otherwise. +To purposefully and silently skip postcommand hooks, commands can raise any of +of the following exceptions. + +- :attr:`cmd2.exceptions.SkipPostcommandHooks` +- :attr:`cmd2.exceptions.Cmd2ArgparseError` + Command Finalization Hooks -------------------------- |