Merge pull request #864 from python-cmd2/reduce_settable_attributes

Reduce settable attributes and renamed locals_in_py

Author: tleonhardt

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.9.26 (TBD, 2020)
+* Breaking changes
+    * Renamed `locals_in_py` attribute of `cmd2.Cmd` to `self_in_py`
+    * The following public attributes of `cmd2.Cmd` are no longer settable at runtime by end users:
+        * `continuation_prompt`
+        * `self_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)

README.md

@@ -318,14 +318,11 @@ example/transcript_regex.txt:
 # regexes on prompts just make the trailing space obvious
 (Cmd) set
 allow_style: Terminal
-continuation_prompt: >/ /
 debug: False
 echo: False
 editor: /.*?/
 feedback_to_output: False
-locals_in_py: True
 maxrepeats: 3
-prompt: (Cmd)/ /
 quiet: False
 timing: False
 ```
@@ -350,14 +347,14 @@ Open source projects using cmd2
 
 Here are a few examples of open-source projects which use `cmd2`:
 
+* [Jok3r](http://www.jok3r-framework.com)
+    * Network & Web Pentest Automation Framework
 * [CephFS Shell](http://docs.ceph.com/docs/master/cephfs/cephfs-shell/)
     * [Ceph](https://ceph.com/) is a distributed object, block, and file storage platform
 * [JSShell](https://github.com/Den1al/JSShell)
     * An interactive multi-user web JavaScript shell
 * [psiTurk](https://psiturk.org)
     * An open platform for science on Amazon Mechanical Turk
-* [Jok3r](http://www.jok3r-framework.com)
-    * Network & Web Pentest Automation Framework
 * [Poseidon](https://github.com/CyberReboot/poseidon)
     * Leverages software-defined networks (SDNs) to acquire and then feed network traffic to a number of machine learning techniques
 * [Unipacker](https://github.com/unipacker/unipacker)

cmd2/cmd2.py

@@ -181,28 +181,23 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
         super().__init__(completekey=completekey, stdin=stdin, stdout=stdout)
 
         # Attributes which should NOT be dynamically settable via the set command at runtime
-        # To prevent a user from altering these with the py/ipy commands, remove locals_in_py from the
-        # settable dictionary during your applications's __init__ method.
         self.default_to_shell = False  # Attempt to run unrecognized commands as shell commands
         self.quit_on_sigint = False  # Quit the loop on interrupt instead of just resetting prompt
         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 +206,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.self_in_py = False
+
         # Commands to exclude from the help menu and tab completion
         self.hidden_commands = ['eof', '_relative_load', '_relative_run_script']
 
@@ -3118,7 +3116,7 @@ def py_quit():
             self.py_locals['quit'] = py_quit
             self.py_locals['exit'] = py_quit
 
-            if self.locals_in_py:
+            if self.self_in_py:
                 self.py_locals['self'] = self
             elif 'self' in self.py_locals:
                 del self.py_locals['self']
@@ -3238,7 +3236,7 @@ def load_ipy(cmd2_app: Cmd, py_bridge: PyBridge):
                 exec("{} = py_bridge".format(cmd2_app.py_bridge_name))
 
                 # Add self variable pointing to cmd2_app, if allowed
-                if cmd2_app.locals_in_py:
+                if cmd2_app.self_in_py:
                     exec("self = cmd2_app")
 
                 # Delete these names from the environment so IPython can't use them

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

@@ -8,11 +8,9 @@ arguments, it enters an interactive Python session.  The session can call
 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
+``self_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

@@ -39,7 +39,7 @@ capabilities which you may wish to utilize while initializing the app::
             self.continuation_prompt = '... '
 
             # Allow access to your application in py and ipy via self
-            self.locals_in_py = True
+            self.self_in_py = True
 
             # Set the default category name
             self.default_category = 'cmd2 Built-in Commands'
@@ -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
@@ -125,7 +125,7 @@ override:
   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*
+- **self_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 CompletionItems to display during
@@ -139,7 +139,7 @@ override:
   ``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**)
+  everything available with **self_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

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