Made three public attributes of cmd2.Cmd no longer settable at runtime by end users

The 3 attributes are:
- continuation_prompt
- locals_in_py
- prompt

Author: tleonhardt

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.9.26 (January 26, 2020)
+* Breaking changes
+    * The following public attributes of `cmd2.Cmd` are no longer settable at runtime by end users:
+        * `continuation_prompt`
+        * `locals_in_py`
+        * `prompt`
+    
 ## 0.9.25 (January 26, 2020)
 * Enhancements
     * Reduced what gets put in package downloadable from PyPI (removed irrelevant CI config files and such)

cmd2/cmd2.py

@@ -188,21 +188,18 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
         self.allow_redirection = allow_redirection  # Security setting to prevent redirection of stdout
 
         # Attributes which ARE dynamically settable via the set command at runtime
-        self.continuation_prompt = '> '
         self.debug = False
         self.echo = False
         self.editor = Cmd.DEFAULT_EDITOR
         self.feedback_to_output = False  # Do not include nonessentials in >, | output by default (things like timing)
-        self.locals_in_py = False
+        self.quiet = False  # Do not suppress nonessential output
+        self.timing = False  # Prints elapsed time for each command
 
         # The maximum number of CompletionItems to display during tab completion. If the number of completion
         # suggestions exceeds this number, they will be displayed in the typical columnized format and will
         # not include the description value of the CompletionItems.
         self.max_completion_items = 50
 
-        self.quiet = False  # Do not suppress nonessential output
-        self.timing = False  # Prints elapsed time for each command
-
         # To make an attribute settable with the "do_set" command, add it to this ...
         self.settable = \
             {
@@ -211,18 +208,21 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
                                 '(valid values: {}, {}, {})'.format(ansi.STYLE_TERMINAL,
                                                                     ansi.STYLE_ALWAYS,
                                                                     ansi.STYLE_NEVER)),
-                'continuation_prompt': 'On 2nd+ line of input',
                 'debug': 'Show full error stack on error',
                 'echo': 'Echo command issued into output',
                 'editor': 'Program used by ``edit``',
                 'feedback_to_output': 'Include nonessentials in `|`, `>` results',
-                'locals_in_py': 'Allow access to your application in py via self',
                 'max_completion_items': 'Maximum number of CompletionItems to display during tab completion',
-                'prompt': 'The prompt issued to solicit input',
                 'quiet': "Don't print nonessential feedback",
                 'timing': 'Report execution times'
             }
 
+        # Use as prompt for multiline commands on the 2nd+ line of input
+        self.continuation_prompt = '> '
+
+        # Allow access to your application in embedded Python shells and scripts py via self
+        self.locals_in_py = False
+
         # Commands to exclude from the help menu and tab completion
         self.hidden_commands = ['eof', '_relative_load', '_relative_run_script']
 

docs/features/builtin_commands.rst

@@ -93,14 +93,11 @@ within a running application:
 
     (Cmd) set --long
     allow_style: Terminal          # Allow ANSI text style sequences in output (valid values: Terminal, Always, Never)
-    continuation_prompt: >         # On 2nd+ line of input
     debug: False                   # Show full error stack on error
     echo: False                    # Echo command issued into output
     editor: vim                    # Program used by ``edit``
     feedback_to_output: False      # include nonessentials in `|`, `>` results
-    locals_in_py: False            # Allow access to your application in py via self
     max_completion_items: 50       # Maximum number of CompletionItems to display during tab completion
-    prompt: (Cmd)                  # The prompt issued to solicit input
     quiet: False                   # Don't print nonessential feedback
     timing: False                  # Report execution times
 

docs/features/embedded_python_shells.rst

@@ -10,9 +10,7 @@ your cmd2 application while maintaining isolation.
 You may optionally enable full access to to your application by setting
 ``locals_in_py`` to ``True``.  Enabling this flag adds ``self`` to the python
 session, which is a reference to your Cmd2 application. This can be useful for
-debugging your application.  To prevent users from enabling this ability
-manually you'll need to remove ``locals_in_py`` from the ``settable``
-dictionary.
+debugging your application.
 
 The ``app`` object (or your custom name) provides access to application
 commands through raw commands.  For example, any application command call be

docs/features/initialization.rst

@@ -110,7 +110,7 @@ override:
   DisabledCommand objects.
 - **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.
+  scripts. This behavior does not occur when running a 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

docs/features/multiline_commands.rst

@@ -10,3 +10,13 @@ blank line is *always* considered a command terminator (cannot be overridden).
 
 In multiline commands, output redirection characters like ``>`` and ``|`` are
 part of the command arguments unless they appear after the terminator.
+
+Continuation prompt
+-------------------
+
+When a user types a :ref:`Multiline Command
+<features/multiline_commands:Multiline Commands>` it may span more than one
+line of input. The prompt for the first line of input is specified by the
+``cmd2.Cmd.prompt`` instance attribute - see
+:ref:`features/prompt:Customizing the Prompt`. The prompt for subsequent lines
+of input is defined by the ``cmd2.Cmd.continuation_prompt`` attribute.

docs/features/prompt.rst

@@ -3,6 +3,13 @@ Prompt
 
 ``cmd2`` can issue a prompt before soliciting user input.
 
+Customizing the Prompt
+----------------------
+
+This prompt can be configured by setting the `cmd2.Cmd.prompt` instance
+attribute. This contains the string which should be printed as a prompt
+for user input.
+
 Asynchronous Feedback
 ---------------------
 

docs/features/settings.rst

@@ -47,16 +47,6 @@ This setting can be one of three values:
 - ``Always`` - ANSI escape sequences are always passed through to the output
 
 
-continuation_prompt
-~~~~~~~~~~~~~~~~~~~
-
-When a user types a :ref:`Multiline Command
-<features/multiline_commands:Multiline Commands>` it may span more than one
-line of input. The prompt for the first line of input is specified by the
-:ref:`features/settings:prompt` setting. The prompt for subsequent lines of
-input is defined by this setting.
-
-
 debug
 ~~~~~
 
@@ -71,7 +61,7 @@ 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.
+This behavior does not occur when running a command at the prompt.
 
 
 editor
@@ -95,13 +85,6 @@ feedback output will be mixed in with and indistinguishable from output
 generated with :meth:`~cmd2.cmd2.Cmd.poutput`.
 
 
-locals_in_py
-~~~~~~~~~~~~
-
-Allow access to your application in one of the
-:ref:`features/embedded_python_shells:Embedded Python Shells` via ``self``.
-
-
 max_completion_items
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -115,13 +98,6 @@ they will be displayed in the typical columnized format and will not include
 the description text of the CompletionItem.
 
 
-prompt
-~~~~~~
-
-This setting contains the string which should be printed as a prompt for user
-input.
-
-
 quiet
 ~~~~~
 
@@ -180,14 +156,13 @@ You may want to prevent a user from modifying a builtin setting. A setting
 must appear in the :attr:`cmd2.cmd2.Cmd.settable` dictionary in order for it
 to be available to the :ref:`features/builtin_commands:set` command.
 
-Let's say your program does not have any
-:ref:`features/multiline_commands:Multiline Commands`. You might want to hide
-the :ref:`features/settings:continuation_prompt` setting from your users since
-it is only applicable to multiline commands. To do so, remove it from the
+Let's say that you never want end users of your program to be able to enable
+full debug tracebacks to print out if an error occurs. You might want to hide
+the :ref:`features/settings:debug` setting. To do so, remove it from the
 :attr:`cmd2.cmd2.Cmd.settable` dictionary after you initialize your object::
 
   class MyApp(cmd2.Cmd):
 
     def __init__(self):
         super().__init__()
-        self.settable.pop('continuation_prompt')
+        self.settable.pop('debug')

docs/features/transcripts.rst

@@ -146,8 +146,8 @@ the path instead of specifying it verbatim, or we can escape the slashes::
    invisible, you can add a regular expression to match them, so that you can
    see where they are when you look at the transcript::
 
-      (Cmd) set prompt
-      prompt: (Cmd)/ /
+      (Cmd) set editor
+      editor: vim/ /
 
    Some terminal emulators strip trailing space when you copy text from them.
    This could make the actual data generated by your app different than the

examples/scripts/save_help_text.py

@@ -60,7 +60,7 @@ def main() -> None:
 
     # Make sure we have access to self
     if 'self' not in globals():
-        print("Run 'set locals_in_py true' and then rerun this script")
+        print("Re-run this script from a cmd2 application where locals_in_py is True")
         return
 
     # Make sure the user passed in an output file