Updated examples and documentation pertaining to disabling commands

Author: kmvanbrunt

CHANGELOG.md

@@ -10,6 +10,14 @@
         * Added **-v**, **--verbose** flag
             * display history and include expanded commands if they differ from the typed command
     * Added ``matches_sort_key`` to override the default way tab completion matches are sorted
+    * Added ability to disable/enable individual commands and entire categories of commands. When a command
+      is disabled, it will not show up in the help menu or tab complete. If a user tries to run the command
+      or call help on it, a command-specific message supplied by the developer will be printed. The following
+      commands were added to support this feature.
+        * ``enable_command()``
+        * ``enable_category()``
+        * ``disable_command()``
+        * ``disable_category()``
 * Potentially breaking changes
     * Made ``cmd2_app`` a positional and required argument of ``AutoCompleter`` since certain functionality now
     requires that it can't be ``None``.

cmd2/cmd2.py

@@ -3654,7 +3654,7 @@ def disable_command(self, command: str, message_to_print: str) -> None:
         """
         Disable a command and overwrite its functions
         :param command: the command being disabled
-        :param message_to_print: what to print when this command or its help function is run while disabled
+        :param message_to_print: what to print when this command is run or help is called on it while disabled
         """
         import functools
 
@@ -3683,7 +3683,8 @@ def disable_category(self, category: str, message_to_print: str) -> None:
         """
         Disable an entire category of commands
         :param category: the category to disable
-        :param message_to_print: what to print when anything in this category is run while disabled
+        :param message_to_print: what to print when anything in this category is run or help is called on it
+                                 while disabled
         """
         all_commands = self.get_all_commands()
 

docs/argument_processing.rst

@@ -195,138 +195,6 @@ Which yields:
 .. _argparse: https://docs.python.org/3/library/argparse.html
 
 
-Grouping Commands
-=================
-
-By default, the ``help`` command displays::
-
-  Documented commands (type help <topic>):
-  ========================================
-  alias    findleakers  pyscript    sessions             status       vminfo
-  config   help         quit        set                  stop         which
-  connect  history      redeploy    shell                thread_dump
-  deploy   list         resources   shortcuts            unalias
-  edit     load         restart     sslconnectorciphers  undeploy
-  expire   py           serverinfo  start                version
-
-If you have a large number of commands, you can optionally group your commands into categories.
-Here's the output from the example ``help_categories.py``::
-
-  Documented commands (type help <topic>):
-
-  Application Management
-  ======================
-  deploy  findleakers  redeploy  sessions  stop
-  expire  list         restart   start     undeploy
-
-  Connecting
-  ==========
-  connect  which
-
-  Server Information
-  ==================
-  resources  serverinfo  sslconnectorciphers  status  thread_dump  vminfo
-
-  Other
-  =====
-  alias   edit  history  py        quit  shell      unalias
-  config  help  load     pyscript  set   shortcuts  version
-
-
-There are 2 methods of specifying command categories, using the ``@with_category`` decorator or with the
-``categorize()`` function. Once a single command category is detected, the help output switches to a categorized
-mode of display. All commands with an explicit category defined default to the category `Other`.
-
-Using the ``@with_category`` decorator::
-
-  @with_category(CMD_CAT_CONNECTING)
-  def do_which(self, _):
-      """Which command"""
-      self.poutput('Which')
-
-Using the ``categorize()`` function:
-
-    You can call with a single function::
-
-        def do_connect(self, _):
-            """Connect command"""
-            self.poutput('Connect')
-
-        # Tag the above command functions under the category Connecting
-        categorize(do_connect, CMD_CAT_CONNECTING)
-
-    Or with an Iterable container of functions::
-
-        def do_undeploy(self, _):
-            """Undeploy command"""
-            self.poutput('Undeploy')
-
-        def do_stop(self, _):
-            """Stop command"""
-            self.poutput('Stop')
-
-        def do_findleakers(self, _):
-            """Find Leakers command"""
-            self.poutput('Find Leakers')
-
-        # Tag the above command functions under the category Application Management
-        categorize((do_undeploy,
-                    do_stop,
-                    do_findleakers), CMD_CAT_APP_MGMT)
-
-The ``help`` command also has a verbose option (``help -v`` or ``help --verbose``) that combines
-the help categories with per-command Help Messages::
-
-    Documented commands (type help <topic>):
-
-    Application Management
-    ================================================================================
-    deploy              Deploy command
-    expire              Expire command
-    findleakers         Find Leakers command
-    list                List command
-    redeploy            Redeploy command
-    restart             usage: restart [-h] {now,later,sometime,whenever}
-    sessions            Sessions command
-    start               Start command
-    stop                Stop command
-    undeploy            Undeploy command
-
-    Connecting
-    ================================================================================
-    connect             Connect command
-    which               Which command
-
-    Server Information
-    ================================================================================
-    resources              Resources command
-    serverinfo             Server Info command
-    sslconnectorciphers    SSL Connector Ciphers command is an example of a command that contains
-                           multiple lines of help information for the user. Each line of help in a
-                           contiguous set of lines will be printed and aligned in the verbose output
-                           provided with 'help --verbose'
-    status                 Status command
-    thread_dump            Thread Dump command
-    vminfo                 VM Info command
-
-    Other
-    ================================================================================
-    alias               Define or display aliases
-    config              Config command
-    edit                Edit a file in a text editor
-    help                List available commands with "help" or detailed help with "help cmd"
-    history             usage: history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg]
-    load                Runs commands in script file that is encoded as either ASCII or UTF-8 text
-    py                  Invoke python command, shell, or script
-    pyscript            Runs a python script file inside the console
-    quit                Exits this application
-    set                 usage: set [-h] [-a] [-l] [settable [settable ...]]
-    shell               Execute a command as if at the OS prompt
-    shortcuts           Lists shortcuts available
-    unalias             Unsets aliases
-    version             Version command
-
-
 Receiving an argument list
 ==========================
 

docs/unfreefeatures.rst

@@ -237,3 +237,165 @@ set_window_title()
 The easiest way to understand these functions is to see the AsyncPrinting_ example for a demonstration.
 
 .. _AsyncPrinting: https://github.com/python-cmd2/cmd2/blob/master/examples/async_printing.py
+
+
+Grouping Commands
+=================
+
+By default, the ``help`` command displays::
+
+  Documented commands (type help <topic>):
+  ========================================
+  alias    findleakers  pyscript    sessions             status       vminfo
+  config   help         quit        set                  stop         which
+  connect  history      redeploy    shell                thread_dump
+  deploy   list         resources   shortcuts            unalias
+  edit     load         restart     sslconnectorciphers  undeploy
+  expire   py           serverinfo  start                version
+
+If you have a large number of commands, you can optionally group your commands into categories.
+Here's the output from the example ``help_categories.py``::
+
+  Documented commands (type help <topic>):
+
+  Application Management
+  ======================
+  deploy  findleakers  redeploy  sessions  stop
+  expire  list         restart   start     undeploy
+
+  Connecting
+  ==========
+  connect  which
+
+  Server Information
+  ==================
+  resources  serverinfo  sslconnectorciphers  status  thread_dump  vminfo
+
+  Other
+  =====
+  alias   edit  history  py        quit  shell      unalias
+  config  help  load     pyscript  set   shortcuts  version
+
+
+There are 2 methods of specifying command categories, using the ``@with_category`` decorator or with the
+``categorize()`` function. Once a single command category is detected, the help output switches to a categorized
+mode of display. All commands with an explicit category defined default to the category `Other`.
+
+Using the ``@with_category`` decorator::
+
+  @with_category(CMD_CAT_CONNECTING)
+  def do_which(self, _):
+      """Which command"""
+      self.poutput('Which')
+
+Using the ``categorize()`` function:
+
+    You can call with a single function::
+
+        def do_connect(self, _):
+            """Connect command"""
+            self.poutput('Connect')
+
+        # Tag the above command functions under the category Connecting
+        categorize(do_connect, CMD_CAT_CONNECTING)
+
+    Or with an Iterable container of functions::
+
+        def do_undeploy(self, _):
+            """Undeploy command"""
+            self.poutput('Undeploy')
+
+        def do_stop(self, _):
+            """Stop command"""
+            self.poutput('Stop')
+
+        def do_findleakers(self, _):
+            """Find Leakers command"""
+            self.poutput('Find Leakers')
+
+        # Tag the above command functions under the category Application Management
+        categorize((do_undeploy,
+                    do_stop,
+                    do_findleakers), CMD_CAT_APP_MGMT)
+
+The ``help`` command also has a verbose option (``help -v`` or ``help --verbose``) that combines
+the help categories with per-command Help Messages::
+
+    Documented commands (type help <topic>):
+
+    Application Management
+    ================================================================================
+    deploy              Deploy command
+    expire              Expire command
+    findleakers         Find Leakers command
+    list                List command
+    redeploy            Redeploy command
+    restart             usage: restart [-h] {now,later,sometime,whenever}
+    sessions            Sessions command
+    start               Start command
+    stop                Stop command
+    undeploy            Undeploy command
+
+    Connecting
+    ================================================================================
+    connect             Connect command
+    which               Which command
+
+    Server Information
+    ================================================================================
+    resources              Resources command
+    serverinfo             Server Info command
+    sslconnectorciphers    SSL Connector Ciphers command is an example of a command that contains
+                           multiple lines of help information for the user. Each line of help in a
+                           contiguous set of lines will be printed and aligned in the verbose output
+                           provided with 'help --verbose'
+    status                 Status command
+    thread_dump            Thread Dump command
+    vminfo                 VM Info command
+
+    Other
+    ================================================================================
+    alias               Define or display aliases
+    config              Config command
+    edit                Edit a file in a text editor
+    help                List available commands with "help" or detailed help with "help cmd"
+    history             usage: history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg]
+    load                Runs commands in script file that is encoded as either ASCII or UTF-8 text
+    py                  Invoke python command, shell, or script
+    pyscript            Runs a python script file inside the console
+    quit                Exits this application
+    set                 usage: set [-h] [-a] [-l] [settable [settable ...]]
+    shell               Execute a command as if at the OS prompt
+    shortcuts           Lists shortcuts available
+    unalias             Unsets aliases
+    version             Version command
+
+
+Disabling Commands
+==================
+
+``cmd2`` supports disabling commands during runtime. This is useful if certain commands should only be available
+when the application is in a specific state. When a command is disabled, it will not show up in the help menu or
+tab complete. If a user tries to run the command, a command-specific message supplied by the developer will be
+printed. The following functions support this feature.
+
+enable_command()
+    Enable an individual command
+
+enable_category()
+    Enable an entire category of commands
+
+disable_command()
+    Disable an individual command and set the message that will print when this command is run or help is called
+    on it while disabled
+
+disable_category()
+    Disable an entire category of commands and set the message that will print when anything in this category is
+    run or help is called on it while disabled
+
+See the definitions of these functions for descriptions of their arguments.
+
+See the ``do_enable_commands()`` and ``do_disable_commands()`` functions in the HelpCategories_ example for
+a demonstration.
+
+.. _HelpCategories: https://github.com/python-cmd2/cmd2/blob/master/examples/help_categories.py

examples/help_categories.py

@@ -140,6 +140,18 @@ def do_version(self, _):
         """Version command"""
         self.poutput(cmd2.__version__)
 
+    @cmd2.with_category("Command Management")
+    def do_disable_commands(self, _):
+        """Disable the Application Management commands"""
+        self.disable_category(self.CMD_CAT_APP_MGMT, "Application Management is currently disabled")
+        self.poutput("The Application Management commands have been disabled")
+
+    @cmd2.with_category("Command Management")
+    def do_enable_commands(self, _):
+        """Enable the Application Management commands"""
+        self.enable_category(self.CMD_CAT_APP_MGMT)
+        self.poutput("The Application Management commands have been enabled")
+
 
 if __name__ == '__main__':
     c = HelpCategories()