Simplified categorizing commands.

Author: kmvanbrunt

cmd2/__init__.py

@@ -19,10 +19,7 @@
 )
 from .cmd2 import Cmd
 from .colors import Color
-from .command_definition import (
-    CommandSet,
-    with_default_category,
-)
+from .command_definition import CommandSet
 from .completion import (
     Choices,
     CompletionItem,
@@ -80,7 +77,6 @@
     'with_argument_list',
     'with_argparser',
     'with_category',
-    'with_default_category',
     'as_subcommand_to',
     # Exceptions
     'Cmd2ArgparseError',

cmd2/cmd2.py

@@ -42,6 +42,7 @@
 import time
 from code import InteractiveConsole
 from collections import (
+    defaultdict,
     deque,
     namedtuple,
 )
@@ -60,6 +61,7 @@
     IO,
     TYPE_CHECKING,
     Any,
+    ClassVar,
     TextIO,
     TypeVar,
     Union,
@@ -123,7 +125,6 @@
     Completions,
 )
 from .constants import (
-    CMDSET_ATTR_DEFAULT_HELP_CATEGORY,
     COMMAND_FUNC_PREFIX,
     COMPLETER_FUNC_PREFIX,
     HELP_FUNC_PREFIX,
@@ -328,9 +329,22 @@ class Cmd:
     Line-oriented command interpreters are often useful for test harnesses, internal tools, and rapid prototypes.
     """
 
-    DEFAULT_COMPLETEKEY = 'tab'
-    DEFAULT_EDITOR = utils.find_editor()
-    DEFAULT_PROMPT = '(Cmd) '
+    DEFAULT_COMPLETEKEY: ClassVar[str] = "tab"
+    DEFAULT_EDITOR: ClassVar[str | None] = utils.find_editor()
+    DEFAULT_PROMPT: ClassVar[str] = "(Cmd) "
+
+    # Default category used for documented commands (those with a docstring,
+    # help function, or argparse decorator) defined in this class that have
+    # not been explicitly categorized with the @with_category decorator.
+    # This value is inherited by subclasses but they can set their own
+    # DEFAULT_CATEGORY to place their commands into a custom category.
+    DEFAULT_CATEGORY: ClassVar[str] = "Cmd2 Commands"
+
+    # 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,
@@ -537,19 +551,6 @@ def __init__(
         # Set text which prints right before all of the help tables are listed.
         self.doc_leader = ""
 
-        # Set header for table listing documented commands.
-        self.doc_header = "Documented Commands"
-
-        # Set header for table listing help topics not related to a command.
-        self.misc_header = "Miscellaneous Help Topics"
-
-        # Set header for table listing commands that have no help info.
-        self.undoc_header = "Undocumented Commands"
-
-        # If any command has been categorized, then all other documented commands that
-        # haven't been categorized will display under this section in the help output.
-        self.default_category = "Uncategorized Commands"
-
         # The error that prints when no help information can be found
         self.help_error = "No help on {}"
 
@@ -840,8 +841,6 @@ def register_command_set(self, cmdset: CommandSet) -> None:
             ),
         )
 
-        default_category = getattr(cmdset, CMDSET_ATTR_DEFAULT_HELP_CATEGORY, None)
-
         installed_attributes = []
         try:
             for cmd_func_name, command_method in methods:
@@ -864,9 +863,6 @@ def register_command_set(self, cmdset: CommandSet) -> None:
 
                 self._cmd_to_command_sets[command] = cmdset
 
-                if default_category and not hasattr(command_method, constants.CMD_ATTR_HELP_CATEGORY):
-                    utils.categorize(command_method, default_category)
-
                 # If this command is in a disabled category, then disable it
                 command_category = getattr(command_method, constants.CMD_ATTR_HELP_CATEGORY, None)
                 if command_category in self.disabled_categories:
@@ -4214,12 +4210,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], list[str]]:
+    def _build_command_info(self) -> tuple[dict[str, list[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 documented command names
                   - list of undocumented command names
                   - list of help topic names that are not also commands
         """
@@ -4228,9 +4223,9 @@ 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_doc: list[str] = []
+        cmds_cats: dict[str, list[str]] = defaultdict(list)
         cmds_undoc: list[str] = []
-        cmds_cats: dict[str, list[str]] = {}
+
         for command in visible_commands:
             func = cast(CommandFunc, self.cmd_func(command))
             has_help_func = False
@@ -4245,13 +4240,15 @@ def _build_command_info(self) -> tuple[dict[str, list[str]], list[str], list[str
 
             if hasattr(func, constants.CMD_ATTR_HELP_CATEGORY):
                 category: str = getattr(func, constants.CMD_ATTR_HELP_CATEGORY)
-                cmds_cats.setdefault(category, [])
                 cmds_cats[category].append(command)
             elif func.__doc__ or has_help_func or has_parser:
-                cmds_doc.append(command)
+                # Determine the category based on the defining class
+                defining_cls = get_defining_class(func)
+                category = getattr(defining_cls, 'DEFAULT_CATEGORY', self.DEFAULT_CATEGORY)
+                cmds_cats[category].append(command)
             else:
                 cmds_undoc.append(command)
-        return cmds_cats, cmds_doc, cmds_undoc, help_topics
+        return cmds_cats, cmds_undoc, help_topics
 
     @classmethod
     def _build_help_parser(cls) -> Cmd2ArgumentParser:
@@ -4284,7 +4281,7 @@ def do_help(self, args: argparse.Namespace) -> None:
         self.last_result = True
 
         if not args.command or args.verbose:
-            cmds_cats, cmds_doc, cmds_undoc, help_topics = self._build_command_info()
+            cmds_cats, cmds_undoc, help_topics = self._build_command_info()
 
             if self.doc_leader:
                 self.poutput()
@@ -4294,10 +4291,6 @@ def do_help(self, args: argparse.Namespace) -> None:
             # Print any categories first and then the remaining documented commands.
             sorted_categories = sorted(cmds_cats.keys(), key=utils.DEFAULT_STR_SORT_KEY)
             all_cmds = {category: cmds_cats[category] for category in sorted_categories}
-            if all_cmds:
-                all_cmds[self.default_category] = cmds_doc
-            else:
-                all_cmds[self.doc_header] = cmds_doc
 
             # Used to provide verbose table separation for better readability.
             previous_table_printed = False
@@ -4312,8 +4305,8 @@ def do_help(self, args: argparse.Namespace) -> None:
             if previous_table_printed and (help_topics or cmds_undoc):
                 self.poutput()
 
-            self.print_topics(self.misc_header, help_topics, 15, 80)
-            self.print_topics(self.undoc_header, cmds_undoc, 15, 80)
+            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

cmd2/command_definition.py

@@ -6,82 +6,34 @@
 )
 from typing import (
     TYPE_CHECKING,
+    ClassVar,
     TypeAlias,
-    TypeVar,
 )
 
-from .constants import (
-    CMDSET_ATTR_DEFAULT_HELP_CATEGORY,
-    COMMAND_FUNC_PREFIX,
-)
 from .exceptions import CommandSetRegistrationError
 from .utils import Settable
 
 if TYPE_CHECKING:  # pragma: no cover
     from .cmd2 import Cmd
 
-#: Callable signature for a basic command  function
-#: Further refinements are needed to define the input parameters
+# Callable signature for a basic command  function
+# Further refinements are needed to define the input parameters
 CommandFunc: TypeAlias = Callable[..., bool | None]
 
-CommandSetType = TypeVar('CommandSetType', bound=type['CommandSet'])
-
-
-def with_default_category(category: str, *, heritable: bool = True) -> Callable[[CommandSetType], CommandSetType]:
-    """Apply a category to all ``do_*`` command methods in a class that do not already have a category specified (Decorator).
-
-    CommandSets that are decorated by this with `heritable` set to True (default) will set a class attribute that is
-    inherited by all subclasses unless overridden. All commands of this CommandSet and all subclasses of this CommandSet
-    that do not declare an explicit category will be placed in this category. Subclasses may use this decorator to
-    override the default category.
-
-    If `heritable` is set to False, then only the commands declared locally to this CommandSet will be placed in the
-    specified category. Dynamically created commands and commands declared in sub-classes will not receive this
-    category.
-
-    :param category: category to put all uncategorized commands in
-    :param heritable: Flag whether this default category should apply to sub-classes. Defaults to True
-    :return: decorator function
-    """
-
-    def decorate_class(cls: CommandSetType) -> CommandSetType:
-        if heritable:
-            setattr(cls, CMDSET_ATTR_DEFAULT_HELP_CATEGORY, category)
-
-        import inspect
-
-        from .constants import CMD_ATTR_HELP_CATEGORY
-        from .decorators import with_category
-
-        # get members of the class that meet the following criteria:
-        # 1. Must be a function
-        # 2. Must start with COMMAND_FUNC_PREFIX (do_)
-        # 3. Must be a member of the class being decorated and not one inherited from a parent declaration
-        methods = inspect.getmembers(
-            cls,
-            predicate=lambda meth: (
-                inspect.isfunction(meth)
-                and meth.__name__.startswith(COMMAND_FUNC_PREFIX)
-                and meth in inspect.getmro(cls)[0].__dict__.values()
-            ),
-        )
-        category_decorator = with_category(category)
-        for method in methods:
-            if not hasattr(method[1], CMD_ATTR_HELP_CATEGORY):
-                setattr(cls, method[0], category_decorator(method[1]))
-        return cls
-
-    return decorate_class
-
 
 class CommandSet:
     """Base class for defining sets of commands to load in cmd2.
 
-    ``with_default_category`` can be used to apply a default category to all commands in the CommandSet.
-
     ``do_``, ``help_``, and ``complete_`` functions differ only in that self is the CommandSet instead of the cmd2 app
     """
 
+    # Default category used for documented commands (those with a docstring,
+    # help function, or argparse decorator) defined in this CommandSet that have
+    # not been explicitly categorized with the @with_category decorator.
+    # This value is inherited by subclasses but they can set their own
+    # DEFAULT_CATEGORY to place their commands into a custom category.
+    DEFAULT_CATEGORY: ClassVar[str] = "CommandSet Commands"
+
     def __init__(self) -> None:
         """Private reference to the CLI instance in which this CommandSet running.
 

cmd2/constants.py

@@ -78,9 +78,6 @@ def cmd2_public_attr_name(name: str) -> str:
 # Attached to a command function; defines whether tokens are unquoted before reaching argparse
 CMD_ATTR_PRESERVE_QUOTES = cmd2_private_attr_name('preserve_quotes')
 
-# Attached to a CommandSet class; defines a default help category for its member functions
-CMDSET_ATTR_DEFAULT_HELP_CATEGORY = cmd2_private_attr_name('default_help_category')
-
 # Attached to a subcommand function; defines the full command path to the parent (e.g., "foo" or "foo bar")
 SUBCMD_ATTR_COMMAND = cmd2_private_attr_name('parent_command')
 

cmd2/decorators.py

@@ -104,17 +104,17 @@ def _arg_swap(args: Sequence[Any], search_arg: Any, *replace_arg: Any) -> list[A
     return args_list
 
 
-#: Function signature for a command function that accepts a pre-processed argument list from user input
-#: and optionally returns a boolean
+# Function signature for a command function that accepts a pre-processed argument list from user input
+# and optionally returns a boolean
 ArgListCommandFuncOptionalBoolReturn: TypeAlias = Callable[[CmdOrSet, list[str]], bool | None]
-#: Function signature for a command function that accepts a pre-processed argument list from user input
-#: and returns a boolean
+# Function signature for a command function that accepts a pre-processed argument list from user input
+# and returns a boolean
 ArgListCommandFuncBoolReturn: TypeAlias = Callable[[CmdOrSet, list[str]], bool]
-#: Function signature for a command function that accepts a pre-processed argument list from user input
-#: and returns Nothing
+# Function signature for a command function that accepts a pre-processed argument list from user input
+# and returns Nothing
 ArgListCommandFuncNoneReturn: TypeAlias = Callable[[CmdOrSet, list[str]], None]
 
-#: Aggregate of all accepted function signatures for command functions that accept a pre-processed argument list
+# Aggregate of all accepted function signatures for command functions that accept a pre-processed argument list
 ArgListCommandFunc: TypeAlias = (
     ArgListCommandFuncOptionalBoolReturn[CmdOrSet]
     | ArgListCommandFuncBoolReturn[CmdOrSet]
@@ -184,24 +184,24 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
     return arg_decorator
 
 
-#: Function signatures for command functions that use a Cmd2ArgumentParser to process user input
-#: and optionally return a boolean
+# Function signatures for command functions that use a Cmd2ArgumentParser to process user input
+# and optionally return a boolean
 ArgparseCommandFuncOptionalBoolReturn: TypeAlias = Callable[[CmdOrSet, argparse.Namespace], bool | None]
 ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn: TypeAlias = Callable[
     [CmdOrSet, argparse.Namespace, list[str]], bool | None
 ]
 
-#: Function signatures for command functions that use a Cmd2ArgumentParser to process user input
-#: and return a boolean
+# Function signatures for command functions that use a Cmd2ArgumentParser to process user input
+# and return a boolean
 ArgparseCommandFuncBoolReturn: TypeAlias = Callable[[CmdOrSet, argparse.Namespace], bool]
 ArgparseCommandFuncWithUnknownArgsBoolReturn: TypeAlias = Callable[[CmdOrSet, argparse.Namespace, list[str]], bool]
 
-#: Function signatures for command functions that use a Cmd2ArgumentParser to process user input
-#: and return nothing
+# Function signatures for command functions that use a Cmd2ArgumentParser to process user input
+# and return nothing
 ArgparseCommandFuncNoneReturn: TypeAlias = Callable[[CmdOrSet, argparse.Namespace], None]
 ArgparseCommandFuncWithUnknownArgsNoneReturn: TypeAlias = Callable[[CmdOrSet, argparse.Namespace, list[str]], None]
 
-#: Aggregate of all accepted function signatures for an argparse command function
+# Aggregate of all accepted function signatures for an argparse command function
 ArgparseCommandFunc: TypeAlias = (
     ArgparseCommandFuncOptionalBoolReturn[CmdOrSet]
     | ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn[CmdOrSet]