From 2a0ded26b7af49ffd287046d89501e0c122d80ed Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Sun, 26 Jan 2020 22:04:54 -0500 Subject: Improved example in initialiation docs --- docs/features/initialization.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) (limited to 'docs/features') diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst index 936208f1..315709f0 100644 --- a/docs/features/initialization.rst +++ b/docs/features/initialization.rst @@ -6,7 +6,7 @@ capabilities which you may wish to utilize while initializing the app:: #!/usr/bin/env python3 # coding=utf-8 - """A simple example cmd2 appliction demonstrating the following: + """A simple example cmd2 application demonstrating the following: 1) Colorizing/stylizing output 2) Using multiline commands 3) Persistent history @@ -28,15 +28,27 @@ capabilities which you may wish to utilize while initializing the app:: super().__init__(multiline_commands=['echo'], persistent_history_file='cmd2_history.dat', startup_script='scripts/startup.txt', use_ipython=True) + # Prints an intro banner once upon application startup self.intro = style('Welcome to cmd2!', fg='red', bg='white', bold=True) + + # Show this as the prompt when asking for input self.prompt = 'myapp> ' + # Used as prompt for multiline commands after the first line + self.continuation_prompt = '... ' + # Allow access to your application in py and ipy via self self.locals_in_py = True # Set the default category name self.default_category = 'cmd2 Built-in Commands' + # Color to output text in with echo command + self.foreground_color = 'cyan' + + # Make echo_fg settable at runtime + self.settable['foreground_color'] = 'Foreground color to use with echo command' + @cmd2.with_category(CUSTOM_CATEGORY) def do_intro(self, _): """Display the intro banner""" @@ -45,7 +57,7 @@ capabilities which you may wish to utilize while initializing the app:: @cmd2.with_category(CUSTOM_CATEGORY) def do_echo(self, arg): """Example of a multiline command""" - self.poutput(arg) + self.poutput(style(arg, fg=self.foreground_color)) if __name__ == '__main__': -- cgit v1.2.1 From 9d1c2f7379f1d38515d357c2a01a7f4b335da0af Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Sun, 26 Jan 2020 22:07:28 -0500 Subject: Updated comment --- docs/features/initialization.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'docs/features') diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst index 315709f0..cb111a39 100644 --- a/docs/features/initialization.rst +++ b/docs/features/initialization.rst @@ -7,15 +7,16 @@ capabilities which you may wish to utilize while initializing the app:: #!/usr/bin/env python3 # coding=utf-8 """A simple example cmd2 application demonstrating the following: - 1) Colorizing/stylizing output - 2) Using multiline commands - 3) Persistent history - 4) How to run an initialization script at startup - 5) How to group and categorize commands when displaying them in help - 6) Opting-in to using the ipy command to run an IPython shell - 7) Allowing access to your application in py and ipy - 8) Displaying an intro banner upon starting your application - 9) Using a custom prompt + 1) Colorizing/stylizing output + 2) Using multiline commands + 3) Persistent history + 4) How to run an initialization script at startup + 5) How to group and categorize commands when displaying them in help + 6) Opting-in to using the ipy command to run an IPython shell + 7) Allowing access to your application in py and ipy + 8) Displaying an intro banner upon starting your application + 9) Using a custom prompt + 10) How to make custom attributes settable at runtime """ import cmd2 from cmd2 import style -- cgit v1.2.1 From 4308f95352ed5f9eea9dfa07f514dfff3b87bc6b Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Sun, 26 Jan 2020 23:43:29 -0500 Subject: Flushed out initialization documentation Also: - Rearranged some instance attributes in Cmd class to make it clear that they were not used by tab-completion functions. --- docs/features/initialization.rst | 97 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) (limited to 'docs/features') 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. -- cgit v1.2.1 From 64c1d702235f6e9c7aae64793bd39ce48a1c3b4a Mon Sep 17 00:00:00 2001 From: Kevin Van Brunt Date: Mon, 27 Jan 2020 16:05:59 -0500 Subject: Updated documentation --- docs/features/initialization.rst | 12 ++++++++---- docs/features/settings.rst | 6 +++--- 2 files changed, 11 insertions(+), 7 deletions(-) (limited to 'docs/features') diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst index 0574c1c5..7ad26b7d 100644 --- a/docs/features/initialization.rst +++ b/docs/features/initialization.rst @@ -108,7 +108,10 @@ override: 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``) +- **echo**: if ``True``, each command the user issues will be repeated to the + screen before it is executed. This is particularly useful when running + scripts. This behavior does not occur when a running command at the prompt. + (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 @@ -125,14 +128,15 @@ override: - **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) +- **max_completion_items**: max number of CompletionItems 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 + refer to the ``cmd2`` application by in order to call commands (Default: + ``app``) - **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**) diff --git a/docs/features/settings.rst b/docs/features/settings.rst index 697c68a7..b8f75934 100644 --- a/docs/features/settings.rst +++ b/docs/features/settings.rst @@ -69,9 +69,9 @@ trace will be printed. echo ~~~~ -If ``True``, each command the user issues will be repeated to the screen before -it is executed. This is particularly useful when running scripts. This -behavior does not occur when a running command at the prompt. +If ``True``, each command the user issues will be repeated to the screen +before it is executed. This is particularly useful when running scripts. +This behavior does not occur when a running command at the prompt. editor -- cgit v1.2.1 From 9dcc2078d41ffeef1e1ac675d5809b535d76a81d Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Mon, 27 Jan 2020 21:48:02 -0500 Subject: Deleted info on the instance attributes which might only be used in extremely rare circumstances --- docs/features/initialization.rst | 21 ++------------------- 1 file changed, 2 insertions(+), 19 deletions(-) (limited to 'docs/features') diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst index 7ad26b7d..39e36428 100644 --- a/docs/features/initialization.rst +++ b/docs/features/initialization.rst @@ -87,8 +87,8 @@ 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Public instance attributes +~~~~~~~~~~~~~~~~~~~~~~~~~~ Here are instance attributes of ``cmd2.Cmd`` which developers might wish override: @@ -148,20 +148,3 @@ override: 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. -- cgit v1.2.1