diff options
Diffstat (limited to 'docs/features/initialization.rst')
| -rw-r--r-- | docs/features/initialization.rst | 97 |
1 files changed, 97 insertions, 0 deletions
diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst index cb111a39..0574c1c5 100644 --- a/docs/features/initialization.rst +++ b/docs/features/initialization.rst @@ -64,3 +64,100 @@ capabilities which you may wish to utilize while initializing the app:: if __name__ == '__main__': app = BasicApp() app.cmdloop() + + +Cmd class initializer +--------------------- + +A ``cmd2.Cmd`` instance or subclass instance is an interactive CLI application +framework. There is no good reason to instantiate ``Cmd`` itself; rather, it’s +useful as a superclass of a class you define yourself in order to inherit +``Cmd``’s methods and encapsulate action methods. + +Certain things must be initialized within the ``__init__()`` method of your +class derived from ``cmd2.Cmd``(all arguments to ``__init__()`` are optional): + +.. automethod:: cmd2.cmd2.Cmd.__init__ + :noindex: + +Cmd instance attributes +----------------------- + +The ``cmd2.Cmd`` class provides a large number of public instance attributes +which allow developers to customize a ``cmd2`` application further beyond the +options provided by the ``__init__()`` method. + +Common instance attributes to override +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Here are instance attributes of ``cmd2.Cmd`` which developers might wish +override: + +- **broken_pipe_warning**: if non-empty, this string will be displayed if a + broken pipe error occurs +- **continuation_prompt**: used for multiline commands on 2nd+ line of input +- **debug**: if ``True`` show full stack trace on error (Default: ``False``) +- **default_category**: if any command has been categorized, then all other + commands that haven't been categorized will display under this section in the + help output. +- **default_error**: the error that prints when a non-existent command is run +- **default_sort_key**: the default key for sorting string results. Its default + value performs a case-insensitive alphabetical sort. +- **default_to_shell**: if ``True`` attempt to run unrecognized commands as + shell commands (Default: ``False``) +- **disabled_commands**: commands that have been disabled from use. This is to + support commands that are only available during specific states of the + application. This dictionary's keys are the command names and its values are + DisabledCommand objects. +- **echo**: if ``True`` echo command issued into output (Default: ``False``) +- **editor**: text editor program to use with *edit* command (e.g. ``vim``) +- **exclude_from_history**: commands to exclude from the *history* command +- **exit_code**: this determines the value returned by ``cmdloop()`` when + exiting the application +- **feedback_to_output**: if ``True`` send nonessential output to stdout, if + ``False`` send them to stderr (Default: ``False``) +- **help_error**: the error that prints when no help information can be found +- **hidden_commands**: commands to exclude from the help menu and tab + completion +- **last_result**: stores results from the last command run to enable usage + of results in a Python script or interactive console. Built-in commands don't + make use of this. It is purely there for user-defined commands and + convenience. +- **locals_in_py**: if ``True`` allow access to your application in *py* + command via ``self`` (Default: ``False``) +- **macros**: dictionary of macro names and their values +- **max_completion_items**: max number of items to display during tab- + completion (Default: 50) +- **pager**: sets the pager command used by the ``Cmd.ppaged()`` method for + displaying wrapped output using a pager +- **pager_chop**: sets the pager command used by the ``Cmd.ppaged()`` method + for displaying chopped/truncated output using a pager +- **py_bridge_name**: name by which embedded Python environments and scripts + refer to the ``cmd2`` application by in order to call commands +- **py_locals**: dictionary that defines specific variables/functions available + in Python shells and scripts (provides more fine-grained control than making + everything available with **locals_in_py**) +- **quiet**: if ``True`` then completely suppress nonessential output (Default: + ``False``) +- **quit_on_sigint**: if ``True`` quit the main loop on interrupt instead of + just resetting prompt +- **settable**: dictionary that controls which of these instance attributes + are settable at runtime using the *set* command +- **timing**: if ``True`` display execution time for each command (Default: + ``False``) + +Rare instance attributes to override +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These instance attributes are used by built-in tab-completion functions. + +These instance attributes really are not intended for ``cmd2`` developers to +override, but they are there for unusual circumstances where it may be +necessary: + +- **sigint_protection**: context manager used to protect critical sections in + the main thread from stopping due to a KeyboardInterrupt +- **statement_parser**: object which parses all command line arguments (it + would be extremely rare to use something other than the default for this) +- **terminal_lock**: this lock should be acquired before doing any asynchronous + changes to the terminal to ensure the updates to the terminal don't interfere + with the input being typed or output being printed by a command. |