Fixed enable_category() and disable_category() to support DEFAULT_CATEGORY.

Removed concept of undocumented commands.

Author: kmvanbrunt

CHANGELOG.md

@@ -76,6 +76,7 @@ prompt is displayed.
     - Removed `Cmd.doc_header` and the `with_default_category` decorator. Help categorization is now
       driven by the `DEFAULT_CATEGORY` class variable (see **Simplified command categorization** in
       the Enhancements section below for details).
+    - Removed `Cmd.undoc_header` since all commands are now considered categorized.
 - Enhancements
     - New `cmd2.Cmd` parameters
         - **auto_suggest**: (boolean) if `True`, provide fish shell style auto-suggestions. These

cmd2/cmd2.py

@@ -344,9 +344,6 @@ class Cmd:
     # Header for table listing help topics not related to a command.
     MISC_HEADER: ClassVar[str] = "Miscellaneous Help Topics"
 
-    # Header for table listing commands that have no help info.
-    UNDOC_HEADER: ClassVar[str] = "Undocumented Commands"
-
     def __init__(
         self,
         completekey: str | None = None,
@@ -868,7 +865,7 @@ def register_command_set(self, cmdset: CommandSet) -> None:
                 self._cmd_to_command_sets[command] = cmdset
 
                 # If this command is in a disabled category, then disable it
-                command_category = getattr(command_method, constants.CMD_ATTR_HELP_CATEGORY, None)
+                command_category = self._get_command_category(command_method)
                 if command_category in self.disabled_categories:
                     message_to_print = self.disabled_categories[command_category]
                     self.disable_command(command, message_to_print)
@@ -3338,6 +3335,23 @@ def cmd_func(self, command: str) -> CommandFunc | None:
         func = getattr(self, func_name, None)
         return cast(CommandFunc, func) if callable(func) else None
 
+    def _get_command_category(self, func: CommandFunc) -> str:
+        """Determine the category for a command.
+
+        :param func: the do_* function implementing the command
+        :return: category name
+        """
+        # Check if the command function has a category.
+        if hasattr(func, constants.CMD_ATTR_HELP_CATEGORY):
+            category: str = getattr(func, constants.CMD_ATTR_HELP_CATEGORY)
+
+        # Otherwise get the category from its defining class.
+        else:
+            defining_cls = get_defining_class(func)
+            category = getattr(defining_cls, 'DEFAULT_CATEGORY', self.DEFAULT_CATEGORY)
+
+        return category
+
     def onecmd(self, statement: Statement | str, *, add_to_history: bool = True) -> bool:
         """Execute the actual do_* method for a command.
 
@@ -4214,12 +4228,11 @@ def complete_help_subcommands(
         completer = argparse_completer.DEFAULT_AP_COMPLETER(argparser, self)
         return completer.complete_subcommand_help(text, line, begidx, endidx, arg_tokens['subcommands'])
 
-    def _build_command_info(self) -> tuple[dict[str, list[str]], list[str], list[str]]:
+    def _build_command_info(self) -> tuple[dict[str, list[str]], list[str]]:
         """Categorizes and sorts visible commands and help topics for display.
 
         :return: tuple containing:
                   - dictionary mapping category names to lists of command names
-                  - list of undocumented command names
                   - list of help topic names that are not also commands
         """
         # Get a sorted list of help topics
@@ -4228,36 +4241,18 @@ def _build_command_info(self) -> tuple[dict[str, list[str]], list[str], list[str
         # Get a sorted list of visible command names
         visible_commands = sorted(self.get_visible_commands(), key=utils.DEFAULT_STR_SORT_KEY)
         cmds_cats: dict[str, list[str]] = {}
-        cmds_undoc: list[str] = []
 
         for command in visible_commands:
-            func = cast(CommandFunc, self.cmd_func(command))
-            has_help_func = False
-            has_parser = func in self._command_parsers
-
+            # Prevent the command from showing as both a command and help topic in the output
             if command in help_topics:
-                # Prevent the command from showing as both a command and help topic in the output
                 help_topics.remove(command)
 
-                # Non-argparse commands can have help_functions for their documentation
-                has_help_func = not has_parser
-
-            # Determine the category
-            category: str | None = None
-
-            if hasattr(func, constants.CMD_ATTR_HELP_CATEGORY):
-                category = getattr(func, constants.CMD_ATTR_HELP_CATEGORY)
-            elif func.__doc__ or has_help_func or has_parser:
-                defining_cls = get_defining_class(func)
-                category = getattr(defining_cls, 'DEFAULT_CATEGORY', self.DEFAULT_CATEGORY)
-
-            # Store the command
-            if category is not None:
-                cmds_cats.setdefault(category, []).append(command)
-            else:
-                cmds_undoc.append(command)
+            # Store the command within its category
+            func = cast(CommandFunc, self.cmd_func(command))
+            category = self._get_command_category(func)
+            cmds_cats.setdefault(category, []).append(command)
 
-        return cmds_cats, cmds_undoc, help_topics
+        return cmds_cats, help_topics
 
     @classmethod
     def _build_help_parser(cls) -> Cmd2ArgumentParser:
@@ -4290,7 +4285,7 @@ def do_help(self, args: argparse.Namespace) -> None:
         self.last_result = True
 
         if not args.command or args.verbose:
-            cmds_cats, cmds_undoc, help_topics = self._build_command_info()
+            cmds_cats, help_topics = self._build_command_info()
 
             if self.doc_leader:
                 self.poutput()
@@ -4311,11 +4306,10 @@ def do_help(self, args: argparse.Namespace) -> None:
                 self._print_documented_command_topics(category, commands, args.verbose)
                 previous_table_printed = bool(commands) and args.verbose
 
-            if previous_table_printed and (help_topics or cmds_undoc):
+            if previous_table_printed and help_topics:
                 self.poutput()
 
             self.print_topics(self.MISC_HEADER, help_topics, 15, 80)
-            self.print_topics(self.UNDOC_HEADER, cmds_undoc, 15, 80)
 
         else:
             # Getting help for a specific command
@@ -5622,7 +5616,7 @@ def enable_category(self, category: str) -> None:
 
         for cmd_name in list(self.disabled_commands):
             func = self.disabled_commands[cmd_name].command_function
-            if getattr(func, constants.CMD_ATTR_HELP_CATEGORY, None) == category:
+            if self._get_command_category(func) == category:
                 self.enable_command(cmd_name)
 
         del self.disabled_categories[category]
@@ -5683,8 +5677,8 @@ def disable_category(self, category: str, message_to_print: str) -> None:
         all_commands = self.get_all_commands()
 
         for cmd_name in all_commands:
-            func = self.cmd_func(cmd_name)
-            if getattr(func, constants.CMD_ATTR_HELP_CATEGORY, None) == category:
+            func = cast(CommandFunc, self.cmd_func(cmd_name))
+            if self._get_command_category(func) == category:
                 self.disable_command(cmd_name, message_to_print)
 
         self.disabled_categories[category] = message_to_print

docs/features/initialization.md

@@ -24,7 +24,6 @@ The `cmd2.Cmd` class provides several class-level variables that can be overridd
 - **DEFAULT_EDITOR**: The default editor program used by the `edit` command.
 - **DEFAULT_PROMPT**: The default prompt string. (Default: `"(Cmd) "`)
 - **MISC_HEADER**: Header for the help section listing miscellaneous help topics. (Default: `"Miscellaneous Help Topics"`)
-- **UNDOC_HEADER**: Header for the help section listing undocumented commands. (Default: `"Undocumented Commands"`)
 
 ## Cmd instance attributes
 

examples/default_categories.py

@@ -59,10 +59,6 @@ def do_shortcuts(self, _: argparse.Namespace) -> None:
         """Overriding with @with_category(cmd2.Cmd.DEFAULT_CATEGORY) keeps it cmd2's category."""
         super().do_shortcuts("")
 
-    def do_undocumented(self, _: cmd2.Statement) -> None:
-        # This has no docstring and no help function, so it stays in "Undocumented Commands"
-        pass
-
 
 if __name__ == '__main__':
     import sys

tests/test_categories.py

@@ -33,18 +33,13 @@ class CategoryCmd(cmd2.Cmd):
 
     DEFAULT_CATEGORY = "CategoryCmd Commands"
 
-    def do_documented(self, _: cmd2.Statement) -> None:
-        """This function has a docstring.
+    def do_cmd_command(self, _: cmd2.Statement) -> None:
+        """The cmd command.
 
         Since this class DOES define its own DEFAULT_CATEGORY,
         this command will show in CategoryCmd.DEFAULT_CATEGORY
         """
 
-    # This function has no docstring and does not use argparse.
-    # Therefore it will be uncategorized.
-    def do_undocumented(self, _: cmd2.Statement) -> None:
-        pass
-
     @with_argparser(Cmd2ArgumentParser(description="Overridden quit command"))
     def do_quit(self, _: argparse.Namespace) -> None:
         """This function overrides the cmd2.Cmd quit command.
@@ -62,17 +57,15 @@ def do_shortcuts(self, _: argparse.Namespace) -> None:
         cmd2.Cmd.DEFAULT_CATEGORY for the parent class.
         """
 
-    # This function has no docstring but it has a help function
-    # so it will be in CategoryCmd.DEFAULT_CATEGORY
-    def do_helpless(self, _: cmd2.Statement) -> None:
-        pass
+    def do_has_help_func(self, _: cmd2.Statement) -> None:
+        """This command has a help function."""
 
-    def help_helpless(self) -> None:
-        """Help function for the helpless command."""
-        self.poutput("The function has help.")
+    def help_has_help_func(self) -> None:
+        """Help function for the has_help_func command."""
+        self.poutput("has_help_func help text.")
 
     def help_coding(self) -> None:
-        """This is help function not tied to a command.
+        """This help function not tied to a command.
 
         It will be in help topics.
         """
@@ -81,19 +74,18 @@ def help_coding(self) -> None:
 
 def test_no_category_cmd() -> None:
     app = NoCategoryCmd()
-    cmds_cats, _cmds_undoc, _help_topics = app._build_command_info()
+    cmds_cats, _help_topics = app._build_command_info()
     assert "inherit" in cmds_cats[cmd2.Cmd.DEFAULT_CATEGORY]
 
 
 def test_category_cmd() -> None:
     app = CategoryCmd()
-    cmds_cats, cmds_undoc, help_topics = app._build_command_info()
+    cmds_cats, help_topics = app._build_command_info()
 
-    assert "documented" in cmds_cats[CategoryCmd.DEFAULT_CATEGORY]
-    assert "undocumented" in cmds_undoc
+    assert "cmd_command" in cmds_cats[CategoryCmd.DEFAULT_CATEGORY]
     assert "quit" in cmds_cats[CategoryCmd.DEFAULT_CATEGORY]
     assert "shortcuts" in cmds_cats[cmd2.Cmd.DEFAULT_CATEGORY]
-    assert "helpless" in cmds_cats[CategoryCmd.DEFAULT_CATEGORY]
+    assert "has_help_func" in cmds_cats[CategoryCmd.DEFAULT_CATEGORY]
     assert "coding" in help_topics
 
 
@@ -116,8 +108,8 @@ class CategoryCommandSet(CommandSet):
 
     DEFAULT_CATEGORY = "CategoryCommandSet Commands"
 
-    def do_documented(self, _: cmd2.Statement) -> None:
-        """This function has a docstring.
+    def do_cmdset_command(self, _: cmd2.Statement) -> None:
+        """The cmdset command.
 
         Since this class DOES define its own DEFAULT_CATEGORY,
         this command will show in CategoryCommandSet.DEFAULT_CATEGORY
@@ -127,12 +119,12 @@ def do_documented(self, _: cmd2.Statement) -> None:
 def test_no_category_command_set() -> None:
     app = cmd2.Cmd()
     app.register_command_set(NoCategoryCommandSet())
-    cmds_cats, _cmds_undoc, _help_topics = app._build_command_info()
+    cmds_cats, _help_topics = app._build_command_info()
     assert "inherit" in cmds_cats[CommandSet.DEFAULT_CATEGORY]
 
 
 def test_category_command_set() -> None:
     app = cmd2.Cmd()
     app.register_command_set(CategoryCommandSet())
-    cmds_cats, _cmds_undoc, _help_topics = app._build_command_info()
-    assert "documented" in cmds_cats[CategoryCommandSet.DEFAULT_CATEGORY]
+    cmds_cats, _help_topics = app._build_command_info()
+    assert "cmdset_command" in cmds_cats[CategoryCommandSet.DEFAULT_CATEGORY]