cmd2 2.5.8__py3-none-any.whl → 2.5.10__py3-none-any.whl

cmd2/ansi.py

@@ -165,7 +165,7 @@ def clear_screen(clear_type: int = 2) -> str:
                        2 - clear entire screen
                        3 - clear entire screen and delete all lines saved in the scrollback buffer
     :return: the clear screen string
-    :raises: ValueError if clear_type is not a valid value
+    :raises ValueError: if clear_type is not a valid value
     """
     if 0 <= clear_type <= 3:
         return f"{CSI}{clear_type}J"
@@ -182,7 +182,7 @@ def clear_line(clear_type: int = 2) -> str:
                        1 - clear from cursor to beginning of the line
                        2 - clear entire line
     :return: the clear line string
-    :raises: ValueError if clear_type is not a valid value
+    :raises ValueError: if clear_type is not a valid value
     """
     if 0 <= clear_type <= 2:
         return f"{CSI}{clear_type}K"
@@ -915,7 +915,7 @@ class RgbFg(FgColor):
         :param r: integer from 0-255 for the red component of the color
         :param g: integer from 0-255 for the green component of the color
         :param b: integer from 0-255 for the blue component of the color
-        :raises: ValueError if r, g, or b is not in the range 0-255
+        :raises ValueError: if r, g, or b is not in the range 0-255
         """
         if any(c < 0 or c > 255 for c in [r, g, b]):
             raise ValueError("RGB values must be integers in the range of 0 to 255")
@@ -944,7 +944,7 @@ class RgbBg(BgColor):
         :param r: integer from 0-255 for the red component of the color
         :param g: integer from 0-255 for the green component of the color
         :param b: integer from 0-255 for the blue component of the color
-        :raises: ValueError if r, g, or b is not in the range 0-255
+        :raises ValueError: if r, g, or b is not in the range 0-255
         """
         if any(c < 0 or c > 255 for c in [r, g, b]):
             raise ValueError("RGB values must be integers in the range of 0 to 255")
@@ -988,8 +988,8 @@ def style(
     :param overline: apply the overline style if True. Defaults to False.
     :param strikethrough: apply the strikethrough style if True. Defaults to False.
     :param underline: apply the underline style if True. Defaults to False.
-    :raises: TypeError if fg isn't None or a subclass of FgColor
-    :raises: TypeError if bg isn't None or a subclass of BgColor
+    :raises TypeError: if fg isn't None or a subclass of FgColor
+    :raises TypeError: if bg isn't None or a subclass of BgColor
     :return: the stylized string
     """
     # List of strings that add style
@@ -1043,13 +1043,13 @@ def style(
 # These can be altered to suit an application's needs and only need to be a
 # function with the following structure: func(str) -> str
 style_success = functools.partial(style, fg=Fg.GREEN)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify success"""
+"""Partial function supplying arguments to [cmd2.ansi.style][] which colors text to signify success"""
 
 style_warning = functools.partial(style, fg=Fg.LIGHT_YELLOW)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify a warning"""
+"""Partial function supplying arguments to [cmd2.ansi.style][] which colors text to signify a warning"""
 
 style_error = functools.partial(style, fg=Fg.LIGHT_RED)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify an error"""
+"""Partial function supplying arguments to [cmd2.ansi.style][] which colors text to signify an error"""
 
 
 def async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_offset: int, alert_msg: str) -> str:

cmd2/argparse_completer.py

@@ -226,7 +226,7 @@ class ArgparseCompleter:
         :param cmd_set: if tab completing a command, the CommandSet the command's function belongs to, if applicable.
                         Defaults to None.
 
-        :raises: CompletionError for various types of tab completion errors
+        :raises CompletionError: for various types of tab completion errors
         """
         if not tokens:
             return []
@@ -264,7 +264,7 @@ class ArgparseCompleter:
             Check if an argument belongs to a mutually exclusive group and either mark that group
             as complete or print an error if the group has already been completed
             :param arg_action: the action of the argument
-            :raises: CompletionError if the group is already completed
+            :raises CompletionError: if the group is already completed
             """
             # Check if this action is in a mutually exclusive group
             for group in self._parser._mutually_exclusive_groups:
@@ -679,7 +679,7 @@ class ArgparseCompleter:
         """
         Tab completion routine for an argparse argument
         :return: list of completions
-        :raises: CompletionError if the completer or choices function this calls raises one
+        :raises CompletionError: if the completer or choices function this calls raises one
         """
         # Check if the arg provides choices to the user
         arg_choices: Union[List[str], ChoicesCallable]

cmd2/argparse_custom.py

@@ -198,31 +198,20 @@ more details.
 cmd2 has patched ``argparse.Action`` to include the following accessor methods
 for cases in which you need to manually access the cmd2-specific attributes.
 
-- ``argparse.Action.get_choices_callable()`` - See
-  :func:`_action_get_choices_callable` for more details.
-- ``argparse.Action.set_choices_provider()`` - See
-  :func:`_action_set_choices_provider` for more details.
-- ``argparse.Action.set_completer()`` - See
-  :func:`_action_set_completer` for more details.
-- ``argparse.Action.get_descriptive_header()`` - See
-  :func:`_action_get_descriptive_header` for more details.
-- ``argparse.Action.set_descriptive_header()`` - See
-  :func:`_action_set_descriptive_header` for more details.
-- ``argparse.Action.get_nargs_range()`` - See
-  :func:`_action_get_nargs_range` for more details.
-- ``argparse.Action.set_nargs_range()`` - See
-  :func:`_action_set_nargs_range` for more details.
-- ``argparse.Action.get_suppress_tab_hint()`` - See
-  :func:`_action_get_suppress_tab_hint` for more details.
-- ``argparse.Action.set_suppress_tab_hint()`` - See
-  :func:`_action_set_suppress_tab_hint` for more details.
+- ``argparse.Action.get_choices_callable()`` - See `action_get_choices_callable` for more details.
+- ``argparse.Action.set_choices_provider()`` - See `_action_set_choices_provider` for more details.
+- ``argparse.Action.set_completer()`` - See `_action_set_completer` for more details.
+- ``argparse.Action.get_descriptive_header()`` - See `_action_get_descriptive_header` for more details.
+- ``argparse.Action.set_descriptive_header()`` - See `_action_set_descriptive_header` for more details.
+- ``argparse.Action.get_nargs_range()`` - See `_action_get_nargs_range` for more details.
+- ``argparse.Action.set_nargs_range()`` - See `_action_set_nargs_range` for more details.
+- ``argparse.Action.get_suppress_tab_hint()`` - See `_action_get_suppress_tab_hint` for more details.
+- ``argparse.Action.set_suppress_tab_hint()`` - See `_action_set_suppress_tab_hint` for more details.
 
 cmd2 has patched ``argparse.ArgumentParser`` to include the following accessor methods
 
-- ``argparse.ArgumentParser.get_ap_completer_type()`` - See
-  :func:`_ArgumentParser_get_ap_completer_type` for more details.
-- ``argparse.Action.set_ap_completer_type()`` - See
-  :func:`_ArgumentParser_set_ap_completer_type` for more details.
+- ``argparse.ArgumentParser.get_ap_completer_type()`` - See `_ArgumentParser_get_ap_completer_type` for more details.
+- ``argparse.Action.set_ap_completer_type()`` - See `_ArgumentParser_set_ap_completer_type` for more details.
 
 **Subcommand removal**
 
@@ -230,8 +219,7 @@ cmd2 has patched ``argparse._SubParsersAction`` to include a ``remove_parser()``
 method which can be used to remove a subcommand.
 
 ``argparse._SubParsersAction.remove_parser`` - new function which removes a
-sub-parser from a sub-parsers group. See
-:func:`_SubParsersAction_remove_parser` for more details.
+sub-parser from a sub-parsers group. See _SubParsersAction_remove_parser` for more details.
 """
 
 import argparse
@@ -312,7 +300,6 @@ class CompletionItem(str):
         :param value: the value being tab completed
         :param description: description text to display
         :param args: args for str __init__
-        :param kwargs: kwargs for str __init__
         """
         super().__init__(*args)
         self.description = description
@@ -485,16 +472,15 @@ def _action_set_choices_callable(self: argparse.Action, choices_callable: Choice
 
     :param self: action being edited
     :param choices_callable: the ChoicesCallable instance to use
-    :raises: TypeError if used on incompatible action type
+    :raises TypeError: if used on incompatible action type
     """
     # Verify consistent use of parameters
     if self.choices is not None:
-        err_msg = "None of the following parameters can be used alongside a choices parameter:\n" "choices_provider, completer"
+        err_msg = "None of the following parameters can be used alongside a choices parameter:\nchoices_provider, completer"
         raise (TypeError(err_msg))
     elif self.nargs == 0:
         err_msg = (
-            "None of the following parameters can be used on an action that takes no arguments:\n"
-            "choices_provider, completer"
+            "None of the following parameters can be used on an action that takes no arguments:\nchoices_provider, completer"
         )
         raise (TypeError(err_msg))
 
@@ -517,7 +503,7 @@ def _action_set_choices_provider(
 
     :param self: action being edited
     :param choices_provider: the choices_provider instance to use
-    :raises: TypeError if used on incompatible action type
+    :raises TypeError: if used on incompatible action type
     """
     self._set_choices_callable(ChoicesCallable(is_completer=False, to_call=choices_provider))  # type: ignore[attr-defined]
 
@@ -538,7 +524,7 @@ def _action_set_completer(
 
     :param self: action being edited
     :param completer: the completer instance to use
-    :raises: TypeError if used on incompatible action type
+    :raises TypeError: if used on incompatible action type
     """
     self._set_choices_callable(ChoicesCallable(is_completer=True, to_call=completer))  # type: ignore[attr-defined]
 
@@ -771,14 +757,14 @@ def _add_argument_wrapper(
           See the header of this file for more information
 
     :return: the created argument action
-    :raises: ValueError on incorrect parameter usage
+    :raises ValueError: on incorrect parameter usage
     """
     # Verify consistent use of arguments
     choices_callables = [choices_provider, completer]
     num_params_set = len(choices_callables) - choices_callables.count(None)
 
     if num_params_set > 1:
-        err_msg = "Only one of the following parameters may be used at a time:\n" "choices_provider, completer"
+        err_msg = "Only one of the following parameters may be used at a time:\nchoices_provider, completer"
         raise (ValueError(err_msg))
 
     # Pre-process special ranged nargs

cmd2/cmd2.py

@@ -305,7 +305,7 @@ class Cmd(cmd.Cmd):
     DEFAULT_EDITOR = utils.find_editor()
 
     INTERNAL_COMMAND_EPILOG = (
-        "Notes:\n" "  This command is for internal use and is not intended to be called from the\n" "  command line."
+        "Notes:\n  This command is for internal use and is not intended to be called from the\n  command line."
     )
 
     # Sorting keys for strings
@@ -349,7 +349,7 @@ class Cmd(cmd.Cmd):
                                        suppressed. Anything written to stderr will still display.
         :param include_py: should the "py" command be included for an embedded Python shell
         :param include_ipy: should the "ipy" command be included for an embedded IPython shell
-        :param allow_cli_args: if ``True``, then :meth:`cmd2.Cmd.__init__` will process command
+        :param allow_cli_args: if ``True``, then [cmd2.Cmd.__init__][] will process command
                                line arguments as either commands to be run or, if ``-t`` or
                                ``--test`` are given, transcript files to run. This should be
                                set to ``False`` if your application parses its own command line
@@ -1134,7 +1134,7 @@ class Cmd(cmd.Cmd):
         Convenience method for removing a settable parameter from ``self.settables``
 
         :param name: name of the settable being removed
-        :raises: KeyError if the Settable matches this name
+        :raises KeyError: if the Settable matches this name
         """
         try:
             del self._settables[name]
@@ -2446,50 +2446,47 @@ class Cmd(cmd.Cmd):
 
     def precmd(self, statement: Union[Statement, str]) -> Statement:
         """Hook method executed just before the command is executed by
-        :meth:`~cmd2.Cmd.onecmd` and after adding it to history.
+        [cmd2.Cmd.onecmd][] and after adding it to history.
 
         :param statement: subclass of str which also contains the parsed input
         :return: a potentially modified version of the input Statement object
 
-        See :meth:`~cmd2.Cmd.register_postparsing_hook` and
-        :meth:`~cmd2.Cmd.register_precmd_hook` for more robust ways
+        See [cmd2.Cmd.register_postparsing_hook][] and
+        [cmd2.Cmd.register_precmd_hook][] for more robust ways
         to run hooks before the command is executed. See
-        :ref:`features/hooks:Postparsing Hooks` and
-        :ref:`features/hooks:Precommand Hooks` for more information.
+        [Hooks](../features/hooks.md) for more information.
         """
         return Statement(statement) if not isinstance(statement, Statement) else statement
 
     def postcmd(self, stop: bool, statement: Union[Statement, str]) -> bool:
         """Hook method executed just after a command is executed by
-        :meth:`~cmd2.Cmd.onecmd`.
+        [cmd2.Cmd.onecmd][].
 
         :param stop: return `True` to request the command loop terminate
         :param statement: subclass of str which also contains the parsed input
 
-        See :meth:`~cmd2.Cmd.register_postcmd_hook` and :meth:`~cmd2.Cmd.register_cmdfinalization_hook` for more robust ways
+        See [cmd2.Cmd.register_postcmd_hook][] and [cmd2.Cmd.register_cmdfinalization_hook][] for more robust ways
         to run hooks after the command is executed. See
-        :ref:`features/hooks:Postcommand Hooks` and
-        :ref:`features/hooks:Command Finalization Hooks` for more information.
+        [Hooks](../features/hooks.md) for more information.
         """
         return stop
 
     def preloop(self) -> None:
-        """Hook method executed once when the :meth:`~.cmd2.Cmd.cmdloop()`
+        """Hook method executed once when the [cmd2.Cmd.cmdloop][]
         method is called.
 
-        See :meth:`~cmd2.Cmd.register_preloop_hook` for a more robust way
+        See [cmd2.Cmd.register_preloop_hook][] for a more robust way
         to run hooks before the command loop begins. See
-        :ref:`features/hooks:Application Lifecycle Hooks` for more information.
+        [Hooks](../features/hooks.md) for more information.
         """
         pass
 
     def postloop(self) -> None:
-        """Hook method executed once when the :meth:`~.cmd2.Cmd.cmdloop()`
-        method is about to return.
+        """Hook method executed once when the [cmd2.Cmd.cmdloop][] method is about to return.
 
-        See :meth:`~cmd2.Cmd.register_postloop_hook` for a more robust way
+        See [cmd2.Cmd.register_postloop_hook][] for a more robust way
         to run hooks after the command loop completes. See
-        :ref:`features/hooks:Application Lifecycle Hooks` for more information.
+        [Hooks](../features/hooks.md) for more information.
         """
         pass
 
@@ -2704,8 +2701,8 @@ class Cmd(cmd.Cmd):
                                        This is used to assist in combining multiline readline history entries and is only
                                        populated by cmd2. Defaults to None.
         :return: the completed Statement
-        :raises: Cmd2ShlexError if a shlex error occurs (e.g. No closing quotation)
-        :raises: EmptyStatement when the resulting Statement is blank
+        :raises Cmd2ShlexError: if a shlex error occurs (e.g. No closing quotation)
+        :raises EmptyStatement: when the resulting Statement is blank
         """
 
         def combine_rl_history(statement: Statement) -> None:
@@ -2791,8 +2788,8 @@ class Cmd(cmd.Cmd):
                                        This is used to assist in combining multiline readline history entries and is only
                                        populated by cmd2. Defaults to None.
         :return: parsed command line as a Statement
-        :raises: Cmd2ShlexError if a shlex error occurs (e.g. No closing quotation)
-        :raises: EmptyStatement when the resulting Statement is blank
+        :raises Cmd2ShlexError: if a shlex error occurs (e.g. No closing quotation)
+        :raises EmptyStatement: when the resulting Statement is blank
         """
         used_macros = []
         orig_line = None
@@ -2882,7 +2879,7 @@ class Cmd(cmd.Cmd):
 
         :param statement: a parsed statement from the user
         :return: A bool telling if an error occurred and a utils.RedirectionSavedState object
-        :raises: RedirectionError if an error occurs trying to pipe or redirect
+        :raises RedirectionError: if an error occurs trying to pipe or redirect
         """
         import io
         import subprocess
@@ -3028,9 +3025,11 @@ class Cmd(cmd.Cmd):
 
         :param command: the name of the command
 
-        :Example:
+        Example:
 
-        >>> helpfunc = self.cmd_func('help')
+        ```py
+        helpfunc = self.cmd_func('help')
+        ```
 
         helpfunc now contains a reference to the ``do_help`` method
         """
@@ -3136,7 +3135,7 @@ class Cmd(cmd.Cmd):
         :param parser: an argument parser which supports the tab completion of multiple arguments
 
         :return: the line read from stdin with all trailing new lines removed
-        :raises: any exceptions raised by input() and stdin.readline()
+        :raises Exception: any exceptions raised by input() and stdin.readline()
         """
         readline_configured = False
         saved_completer: Optional[CompleterFunc] = None
@@ -3261,7 +3260,7 @@ class Cmd(cmd.Cmd):
 
         :param prompt: prompt to display to user
         :return: command line text of 'eof' if an EOFError was caught
-        :raises: whatever exceptions are raised by input() except for EOFError
+        :raises Exception: whatever exceptions are raised by input() except for EOFError
         """
         try:
             # Wrap in try since terminal_lock may not be locked
@@ -3381,8 +3380,8 @@ class Cmd(cmd.Cmd):
     #############################################################
 
     # Top-level parser for alias
-    alias_description = "Manage aliases\n" "\n" "An alias is a command that enables replacement of a word by another string."
-    alias_epilog = "See also:\n" "  macro"
+    alias_description = "Manage aliases\n\nAn alias is a command that enables replacement of a word by another string."
+    alias_epilog = "See also:\n  macro"
     alias_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=alias_description, epilog=alias_epilog)
     alias_parser.add_subparsers(metavar='SUBCOMMAND', required=True)
 
@@ -3549,8 +3548,8 @@ class Cmd(cmd.Cmd):
     #############################################################
 
     # Top-level parser for macro
-    macro_description = "Manage macros\n" "\n" "A macro is similar to an alias, but it can contain argument placeholders."
-    macro_epilog = "See also:\n" "  alias"
+    macro_description = "Manage macros\n\nA macro is similar to an alias, but it can contain argument placeholders."
+    macro_epilog = "See also:\n  alias"
     macro_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=macro_description, epilog=macro_epilog)
     macro_parser.add_subparsers(metavar='SUBCOMMAND', required=True)
 
@@ -3807,7 +3806,7 @@ class Cmd(cmd.Cmd):
         return completer.complete_subcommand_help(text, line, begidx, endidx, arg_tokens['subcommands'])
 
     help_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(
-        description="List available commands or provide " "detailed help for a specific command"
+        description="List available commands or provide detailed help for a specific command"
     )
     help_parser.add_argument(
         '-v', '--verbose', action='store_true', help="print a list of all commands with descriptions of each"
@@ -4700,22 +4699,22 @@ class Cmd(cmd.Cmd):
 
     history_format_group = history_parser.add_argument_group(title='formatting')
     history_format_group.add_argument(
-        '-s', '--script', action='store_true', help='output commands in script format, i.e. without command\n' 'numbers'
+        '-s', '--script', action='store_true', help='output commands in script format, i.e. without command\nnumbers'
     )
     history_format_group.add_argument(
         '-x',
         '--expanded',
         action='store_true',
-        help='output fully parsed commands with any aliases and\n' 'macros expanded, instead of typed commands',
+        help='output fully parsed commands with any aliases and\nmacros expanded, instead of typed commands',
     )
     history_format_group.add_argument(
         '-v',
         '--verbose',
         action='store_true',
-        help='display history and include expanded commands if they\n' 'differ from the typed command',
+        help='display history and include expanded commands if they\ndiffer from the typed command',
     )
     history_format_group.add_argument(
-        '-a', '--all', action='store_true', help='display all commands, including ones persisted from\n' 'previous sessions'
+        '-a', '--all', action='store_true', help='display all commands, including ones persisted from\nprevious sessions'
     )
 
     history_arg_help = (
@@ -5081,7 +5080,7 @@ class Cmd(cmd.Cmd):
         Run a text editor and optionally open a file with it
 
         :param file_path: optional path of the file to edit. Defaults to None.
-        :raises: EnvironmentError if self.editor is not set
+        :raises EnvironmentError: if self.editor is not set
         """
         if not self.editor:
             raise EnvironmentError("Please use 'set editor' to specify your text editing program of choice.")
@@ -5190,7 +5189,7 @@ class Cmd(cmd.Cmd):
         "interpreted relative to the already-running script's directory."
     )
 
-    relative_run_script_epilog = "Notes:\n" "  This command is intended to only be used within text file scripts."
+    relative_run_script_epilog = "Notes:\n  This command is intended to only be used within text file scripts."
 
     relative_run_script_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(
         description=relative_run_script_description, epilog=relative_run_script_epilog
@@ -5516,9 +5515,9 @@ class Cmd(cmd.Cmd):
         """
         Report when a disabled command has been run or had help called on it
 
-        :param args: not used
+        :param _args: not used
         :param message_to_print: the message reporting that the command is disabled
-        :param kwargs: not used
+        :param _kwargs: not used
         """
         # Set apply_style to False so message_to_print's style is not overridden
         self.perror(message_to_print, apply_style=False)
@@ -5672,7 +5671,7 @@ class Cmd(cmd.Cmd):
             raise TypeError(f'{func.__name__} does not have a declared return type, expected {data_type}')
         if signature.return_annotation != data_type:
             raise TypeError(
-                f'{func.__name__} has incompatible return type {signature.return_annotation}, expected ' f'{data_type}'
+                f'{func.__name__} has incompatible return type {signature.return_annotation}, expected {data_type}'
             )
 
     def register_precmd_hook(self, func: Callable[[plugin.PrecommandData], plugin.PrecommandData]) -> None:

cmd2/command_definition.py

@@ -114,7 +114,7 @@ class CommandSet(object):
         Override this property if you need to change its return type to a
         child class of Cmd.
 
-        :raises: CommandSetRegistrationError if CommandSet is not registered.
+        :raises CommandSetRegistrationError: if CommandSet is not registered.
         """
         if self.__cmd_internal is None:
             raise CommandSetRegistrationError('This CommandSet is not registered')
@@ -127,7 +127,7 @@ class CommandSet(object):
         requiring access to the Cmd object (e.g. configure commands and their parsers based on CLI state data).
 
         :param cmd: The cmd2 main application
-        :raises: CommandSetRegistrationError if CommandSet is already registered.
+        :raises CommandSetRegistrationError: if CommandSet is already registered.
         """
         if self.__cmd_internal is None:
             self.__cmd_internal = cmd
@@ -185,7 +185,7 @@ class CommandSet(object):
         Convenience method for removing a settable parameter from the CommandSet
 
         :param name: name of the settable being removed
-        :raises: KeyError if the Settable matches this name
+        :raises KeyError: if the Settable matches this name
         """
         try:
             del self._settables[name]

cmd2/decorators.py

@@ -43,15 +43,17 @@ def with_category(category: str) -> Callable[[CommandFunc], CommandFunc]:
     :param category: the name of the category in which this command should
                      be grouped when displaying the list of commands.
 
-    :Example:
+    Example:
 
-    >>> class MyApp(cmd2.Cmd):
-    >>>   @cmd2.with_category('Text Functions')
-    >>>   def do_echo(self, args)
-    >>>     self.poutput(args)
+    ```py
+    class MyApp(cmd2.Cmd):
+        @cmd2.with_category('Text Functions')
+        def do_echo(self, args)
+            self.poutput(args)
+    ```
 
     For an alternative approach to categorizing commands using a function, see
-    :func:`~cmd2.utils.categorize`
+    [cmd2.utils.categorize][]
     """
 
     def cat_decorator(func: CommandFunc) -> CommandFunc:
@@ -89,7 +91,7 @@ def _parse_positionals(args: Tuple[Any, ...]) -> Tuple['cmd2.Cmd', Union[Stateme
             Cmd,
         )
 
-        if (isinstance(arg, Cmd) or isinstance(arg, CommandSet)) and len(args) > pos:
+        if isinstance(arg, (Cmd, CommandSet)) and len(args) > pos + 1:
             if isinstance(arg, CommandSet):
                 arg = arg._cmd
             next_arg = args[pos + 1]
@@ -98,7 +100,7 @@ def _parse_positionals(args: Tuple[Any, ...]) -> Tuple['cmd2.Cmd', Union[Stateme
 
     # This shouldn't happen unless we forget to pass statement in `Cmd.onecmd` or
     # somehow call the unbound class method.
-    raise TypeError('Expected arguments: cmd: cmd2.Cmd, statement: Union[Statement, str] Not found')  # pragma: no cover
+    raise TypeError('Expected arguments: cmd: cmd2.Cmd, statement: Union[Statement, str] Not found')
 
 
 def _arg_swap(args: Union[Sequence[Any]], search_arg: Any, *replace_arg: Any) -> List[Any]:
@@ -116,17 +118,17 @@ def _arg_swap(args: Union[Sequence[Any]], search_arg: Any, *replace_arg: Any) ->
     return args_list
 
 
-#: Function signature for an Command Function that accepts a pre-processed argument list from user input
+#: Function signature for a command function that accepts a pre-processed argument list from user input
 #: and optionally returns a boolean
 ArgListCommandFuncOptionalBoolReturn = Callable[[CommandParent, List[str]], Optional[bool]]
-#: Function signature for an Command Function that accepts a pre-processed argument list from user input
+#: Function signature for a command function that accepts a pre-processed argument list from user input
 #: and returns a boolean
 ArgListCommandFuncBoolReturn = Callable[[CommandParent, List[str]], bool]
-#: Function signature for an Command Function that accepts a pre-processed argument list from user input
+#: Function signature for a command function that accepts a pre-processed argument list from user input
 #: and returns Nothing
 ArgListCommandFuncNoneReturn = Callable[[CommandParent, 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 = Union[
     ArgListCommandFuncOptionalBoolReturn[CommandParent],
     ArgListCommandFuncBoolReturn[CommandParent],
@@ -152,12 +154,13 @@ def with_argument_list(
     :param preserve_quotes: if ``True``, then argument quotes will not be stripped
     :return: function that gets passed a list of argument strings
 
-    :Example:
-
-    >>> class MyApp(cmd2.Cmd):
-    >>>     @cmd2.with_argument_list
-    >>>     def do_echo(self, arglist):
-    >>>         self.poutput(' '.join(arglist)
+    Example:
+    ```py
+    class MyApp(cmd2.Cmd):
+        @cmd2.with_argument_list
+        def do_echo(self, arglist):
+            self.poutput(' '.join(arglist)
+    ```
     """
     import functools
 
@@ -246,21 +249,29 @@ def _set_parser_prog(parser: argparse.ArgumentParser, prog: str) -> None:
             req_args.append(action.dest)
 
 
-#: Function signature for a Command Function that uses an argparse.ArgumentParser to process user input
-#: and optionally returns a boolean
+#: Function signatures for command functions that use an argparse.ArgumentParser to process user input
+#: and optionally return a boolean
 ArgparseCommandFuncOptionalBoolReturn = Callable[[CommandParent, argparse.Namespace], Optional[bool]]
-#: Function signature for a Command Function that uses an argparse.ArgumentParser to process user input
-#: and returns a boolean
+ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn = Callable[[CommandParent, argparse.Namespace, List[str]], Optional[bool]]
+
+#: Function signatures for command functions that use an argparse.ArgumentParser to process user input
+#: and return a boolean
 ArgparseCommandFuncBoolReturn = Callable[[CommandParent, argparse.Namespace], bool]
-#: Function signature for an Command Function that uses an argparse.ArgumentParser to process user input
-#: and returns nothing
+ArgparseCommandFuncWithUnknownArgsBoolReturn = Callable[[CommandParent, argparse.Namespace, List[str]], bool]
+
+#: Function signatures for command functions that use an argparse.ArgumentParser to process user input
+#: and return nothing
 ArgparseCommandFuncNoneReturn = Callable[[CommandParent, argparse.Namespace], None]
+ArgparseCommandFuncWithUnknownArgsNoneReturn = Callable[[CommandParent, 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 = Union[
     ArgparseCommandFuncOptionalBoolReturn[CommandParent],
+    ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn[CommandParent],
     ArgparseCommandFuncBoolReturn[CommandParent],
+    ArgparseCommandFuncWithUnknownArgsBoolReturn[CommandParent],
     ArgparseCommandFuncNoneReturn[CommandParent],
+    ArgparseCommandFuncWithUnknownArgsNoneReturn[CommandParent],
 ]
 
 
@@ -285,38 +296,41 @@ def with_argparser(
     :param preserve_quotes: if ``True``, then arguments passed to argparse maintain their quotes
     :param with_unknown_args: if true, then capture unknown args
     :return: function that gets passed argparse-parsed args in a ``Namespace``
-             A :class:`cmd2.argparse_custom.Cmd2AttributeWrapper` called ``cmd2_statement`` is included
-             in the ``Namespace`` to provide access to the :class:`cmd2.Statement` object that was created when
+             A [cmd2.argparse_custom.Cmd2AttributeWrapper][] called ``cmd2_statement`` is included
+             in the ``Namespace`` to provide access to the [cmd2.Statement][] object that was created when
              parsing the command line. This can be useful if the command function needs to know the command line.
 
-    :Example:
-
-    >>> parser = cmd2.Cmd2ArgumentParser()
-    >>> parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
-    >>> parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
-    >>> parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
-    >>> parser.add_argument('words', nargs='+', help='words to print')
-    >>>
-    >>> class MyApp(cmd2.Cmd):
-    >>>     @cmd2.with_argparser(parser, preserve_quotes=True)
-    >>>     def do_argprint(self, args):
-    >>>         "Print the options and argument list this options command was called with."
-    >>>         self.poutput(f'args: {args!r}')
-
-    :Example with unknown args:
-
-    >>> parser = cmd2.Cmd2ArgumentParser()
-    >>> parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
-    >>> parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
-    >>> parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
-    >>>
-    >>> class MyApp(cmd2.Cmd):
-    >>>     @cmd2.with_argparser(parser, with_unknown_args=True)
-    >>>     def do_argprint(self, args, unknown):
-    >>>         "Print the options and argument list this options command was called with."
-    >>>         self.poutput(f'args: {args!r}')
-    >>>         self.poutput(f'unknowns: {unknown}')
-
+    Example:
+
+    ```py
+    parser = cmd2.Cmd2ArgumentParser()
+    parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
+    parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
+    parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
+    parser.add_argument('words', nargs='+', help='words to print')
+
+    class MyApp(cmd2.Cmd):
+        @cmd2.with_argparser(parser, preserve_quotes=True)
+        def do_argprint(self, args):
+            "Print the options and argument list this options command was called with."
+            self.poutput(f'args: {args!r}')
+    ```
+
+    Example with unknown args:
+
+    ```py
+    parser = cmd2.Cmd2ArgumentParser()
+    parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
+    parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
+    parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
+
+    class MyApp(cmd2.Cmd):
+        @cmd2.with_argparser(parser, with_unknown_args=True)
+        def do_argprint(self, args, unknown):
+            "Print the options and argument list this options command was called with."
+            self.poutput(f'args: {args!r}')
+            self.poutput(f'unknowns: {unknown}')
+    ```
     """
     import functools
 
@@ -340,7 +354,7 @@ def with_argparser(
                             contiguously somewhere in the list
             :param kwargs: any keyword arguments being passed to command function
             :return: return value of command function
-            :raises: Cmd2ArgparseError if argparse has error parsing command line
+            :raises Cmd2ArgparseError: if argparse has error parsing command line
             """
             cmd2_app, statement_arg = _parse_positionals(args)
             statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(

cmd2/history.py

@@ -150,13 +150,13 @@ class HistoryItem:
 
 
 class History(List[HistoryItem]):
-    """A list of :class:`~cmd2.history.HistoryItem` objects with additional methods
+    """A list of [HistoryItem][cmd2.history.HistoryItem] objects with additional methods
     for searching and managing the list.
 
-    :class:`~cmd2.Cmd` instantiates this class into the :data:`~cmd2.Cmd.history`
+    [cmd2.Cmd][] instantiates this class into the `cmd2.Cmd.history`
     attribute, and adds commands to it as a user enters them.
 
-    See :ref:`features/history:History` for information about the built-in command
+    See [History](../features/history.md) for information about the built-in command
     which allows users to view, search, run, and save previously entered commands.
 
     Developers interested in accessing previously entered commands can use this
@@ -207,7 +207,7 @@ class History(List[HistoryItem]):
         """Get item from the History list using 1-based indexing.
 
         :param index: optional item to get
-        :return: a single :class:`~cmd2.history.HistoryItem`
+        :return: a single [cmd2.history.HistoryItem][]
         """
         if index == 0:
             raise IndexError('The first command in history is command 1.')

cmd2/parsing.py

@@ -98,7 +98,7 @@ class Statement(str):  # type: ignore[override]
     we add our own attributes to this subclass.
 
     Instances of this class should not be created by anything other than the
-    :meth:`cmd2.parsing.StatementParser.parse` method, nor should any of the
+    [StatementParser.parse][cmd2.parsing.StatementParser.parse] method, nor should any of the
     attributes be modified once the object is created.
 
     The string portion of the class contains the arguments, but not the
@@ -108,15 +108,15 @@ class Statement(str):  # type: ignore[override]
 
     1. `argparse <https://docs.python.org/3/library/argparse.html>`_ is your
        friend for anything complex. ``cmd2`` has the decorator
-       (:func:`~cmd2.decorators.with_argparser`) which you can
+       ([cmd2.decorators.with_argparser][]) which you can
        use to make your command method receive a namespace of parsed arguments,
        whether positional or denoted with switches.
 
     2. For commands with simple positional arguments, use
-       :attr:`~cmd2.Statement.args` or :attr:`~cmd2.Statement.arg_list`
+       [args][cmd2.Statement.args] or [arg_list][cmd2.Statement.arg_list]
 
     3. If you don't want to have to worry about quoted arguments, see
-       :attr:`argv` for a trick which strips quotes off for you.
+       [argv][cmd2.Statement.argv] for a trick which strips quotes off for you.
     """
 
     # the arguments, but not the command, nor the output redirection clauses.
@@ -202,8 +202,7 @@ class Statement(str):  # type: ignore[override]
 
     @property
     def expanded_command_line(self) -> str:
-        """Concatenate :meth:`~cmd2.Statement.command_and_args`
-        and :meth:`~cmd2.Statement.post_command`"""
+        """Concatenate [command_and_args][cmd2.Statement.command_and_args] and [post_command][cmd2.Statement.post_command]"""
         return self.command_and_args + self.post_command
 
     @property
@@ -377,7 +376,7 @@ class StatementParser:
 
         :param line: the command line being lexed
         :return: A list of tokens
-        :raises: Cmd2ShlexError if a shlex error occurs (e.g. No closing quotation)
+        :raises Cmd2ShlexError: if a shlex error occurs (e.g. No closing quotation)
         """
 
         # expand shortcuts and aliases
@@ -399,13 +398,13 @@ class StatementParser:
 
     def parse(self, line: str) -> Statement:
         """
-        Tokenize the input and parse it into a :class:`~cmd2.Statement` object,
+        Tokenize the input and parse it into a [cmd2.parsing.Statement][] object,
         stripping comments, expanding aliases and shortcuts, and extracting output
         redirection directives.
 
         :param line: the command line being parsed
-        :return: a new :class:`~cmd2.Statement` object
-        :raises: Cmd2ShlexError if a shlex error occurs (e.g. No closing quotation)
+        :return: a new [cmd2.parsing.Statement][] object
+        :raises Cmd2ShlexError: if a shlex error occurs (e.g. No closing quotation)
         """
 
         # handle the special case/hardcoded terminator of a blank line
@@ -544,7 +543,7 @@ class StatementParser:
         return statement
 
     def parse_command_only(self, rawinput: str) -> Statement:
-        """Partially parse input into a :class:`~cmd2.Statement` object.
+        """Partially parse input into a [cmd2.Statement][] object.
 
         The command is identified, and shortcuts and aliases are expanded.
         Multiline commands are identified, but terminators and output
@@ -553,21 +552,21 @@ class StatementParser:
         This method is used by tab completion code and therefore must not
         generate an exception if there are unclosed quotes.
 
-        The :class:`~cmd2.Statement` object returned by this method can at most
+        The [cmd2.parsing.Statement][] object returned by this method can at most
         contain values in the following attributes:
-        :attr:`~cmd2.Statement.args`, :attr:`~cmd2.Statement.raw`,
-        :attr:`~cmd2.Statement.command`,
-        :attr:`~cmd2.Statement.multiline_command`
+        [cmd2.parsing.Statement.args][], [cmd2.parsing.Statement.raw][],
+        [cmd2.parsing.Statement.command][],
+        [cmd2.parsing.Statement.multiline_command][]
 
-        :attr:`~cmd2.Statement.args` will include all output redirection
+        [cmd2.parsing.Statement.args][] will include all output redirection
         clauses and command terminators.
 
-        Different from :meth:`~cmd2.parsing.StatementParser.parse` this method
+        Different from [cmd2.parsing.StatementParser.parse][] this method
         does not remove redundant whitespace within args. However, it does
         ensure args has no leading or trailing whitespace.
 
         :param rawinput: the command line as entered by the user
-        :return: a new :class:`~cmd2.Statement` object
+        :return: a new [cmd2.Statement][] object
         """
         # expand shortcuts and aliases
         line = self._expand(rawinput)
@@ -617,18 +616,18 @@ class StatementParser:
         :param command_name: name of the command being run
         :param to_parse: what is being passed to the ``do_*`` method. It can be one of two types:
 
-                             1. An already parsed :class:`~cmd2.Statement`
+                             1. An already parsed [cmd2.Statement][]
                              2. An argument string in cases where a ``do_*`` method is
                                 explicitly called. Calling ``do_help('alias create')`` would
                                 cause ``to_parse`` to be 'alias create'.
 
                                 In this case, the string will be converted to a
-                                :class:`~cmd2.Statement` and returned along with
+                                [cmd2.Statement][] and returned along with
                                 the argument list.
 
         :param preserve_quotes: if ``True``, then quotes will not be stripped from
                                 the arguments
-        :return: A tuple containing the :class:`~cmd2.Statement` and a list of
+        :return: A tuple containing the [cmd2.Statement][] and a list of
                  strings representing the arguments
         """
         # Check if to_parse needs to be converted to a Statement

cmd2/py_bridge.py

@@ -57,7 +57,7 @@ class CommandResult(NamedTuple):
         if isinstance(sys.stderr, StdSim):
             sys.stderr.pause_storage = True
 
-    See :class:`~cmd2.utils.StdSim` for more information.
+    See [cmd2.utils.StdSim][] for more information.
 
     .. note::
 

cmd2/table_creator.py

@@ -92,8 +92,8 @@ class Column:
                                 (defaults to True)
         :param max_data_lines: maximum lines allowed in a data cell. If line count exceeds this, then the final
                                line displayed will be truncated with an ellipsis. (defaults to INFINITY)
-        :raises: ValueError if width is less than 1
-        :raises: ValueError if max_data_lines is less than 1
+        :raises ValueError: if width is less than 1
+        :raises ValueError: if max_data_lines is less than 1
         """
         self.header = header
 
@@ -138,7 +138,7 @@ class TableCreator:
         :param cols: column definitions for this table
         :param tab_width: all tabs will be replaced with this many spaces. If a row's fill_char is a tab,
                           then it will be converted to one space.
-        :raises: ValueError if tab_width is less than 1
+        :raises ValueError: if tab_width is less than 1
         """
         if tab_width < 1:
             raise ValueError("Tab width cannot be less than 1")
@@ -443,9 +443,9 @@ class TableCreator:
         :param post_line: string to print after each line of a row. This can be used for padding after
                           the last cell's text and a right row border. (Defaults to blank)
         :return: row string
-        :raises: ValueError if row_data isn't the same length as self.cols
-        :raises: TypeError if fill_char is more than one character (not including ANSI style sequences)
-        :raises: ValueError if fill_char, pre_line, inter_cell, or post_line contains an unprintable
+        :raises ValueError: if row_data isn't the same length as self.cols
+        :raises TypeError: if fill_char is more than one character (not including ANSI style sequences)
+        :raises ValueError: if fill_char, pre_line, inter_cell, or post_line contains an unprintable
                  character like a newline
         """
 
@@ -570,10 +570,10 @@ class SimpleTable(TableCreator):
                              want a divider row. Defaults to dash. (Cannot be a line breaking character)
         :param header_bg: optional background color for header cells (defaults to None)
         :param data_bg: optional background color for data cells (defaults to None)
-        :raises: ValueError if tab_width is less than 1
-        :raises: ValueError if column_spacing is less than 0
-        :raises: TypeError if divider_char is longer than one character
-        :raises: ValueError if divider_char is an unprintable character
+        :raises ValueError: if tab_width is less than 1
+        :raises ValueError: if column_spacing is less than 0
+        :raises TypeError: if divider_char is longer than one character
+        :raises ValueError: if divider_char is an unprintable character
         """
         super().__init__(cols, tab_width=tab_width)
 
@@ -626,8 +626,8 @@ class SimpleTable(TableCreator):
         :param num_cols: how many columns the table will have
         :param column_spacing: how many spaces to place between columns. Defaults to 2.
         :return: base width
-        :raises: ValueError if column_spacing is less than 0
-        :raises: ValueError if num_cols is less than 1
+        :raises ValueError: if column_spacing is less than 0
+        :raises ValueError: if num_cols is less than 1
         """
         if num_cols < 1:
             raise ValueError("Column count cannot be less than 1")
@@ -685,7 +685,7 @@ class SimpleTable(TableCreator):
 
         :param row_data: data with an entry for each column in the row
         :return: data row string
-        :raises: ValueError if row_data isn't the same length as self.cols
+        :raises ValueError: if row_data isn't the same length as self.cols
         """
         if len(row_data) != len(self.cols):
             raise ValueError("Length of row_data must match length of cols")
@@ -712,7 +712,7 @@ class SimpleTable(TableCreator):
         :param include_header: If True, then a header will be included at top of table. (Defaults to True)
         :param row_spacing: A number 0 or greater specifying how many blank lines to place between
                             each row (Defaults to 1)
-        :raises: ValueError if row_spacing is less than 0
+        :raises ValueError: if row_spacing is less than 0
         """
         if row_spacing < 0:
             raise ValueError("Row spacing cannot be less than 0")
@@ -771,8 +771,8 @@ class BorderedTable(TableCreator):
         :param border_bg: optional background color for borders (defaults to None)
         :param header_bg: optional background color for header cells (defaults to None)
         :param data_bg: optional background color for data cells (defaults to None)
-        :raises: ValueError if tab_width is less than 1
-        :raises: ValueError if padding is less than 0
+        :raises ValueError: if tab_width is less than 1
+        :raises ValueError: if padding is less than 0
         """
         super().__init__(cols, tab_width=tab_width)
         self.empty_data = [EMPTY] * len(self.cols)
@@ -827,7 +827,7 @@ class BorderedTable(TableCreator):
         :param column_borders: if True, borders between columns will be included in the calculation (Defaults to True)
         :param padding: number of spaces between text and left/right borders of cell
         :return: base width
-        :raises: ValueError if num_cols is less than 1
+        :raises ValueError: if num_cols is less than 1
         """
         if num_cols < 1:
             raise ValueError("Column count cannot be less than 1")
@@ -976,7 +976,7 @@ class BorderedTable(TableCreator):
 
         :param row_data: data with an entry for each column in the row
         :return: data row string
-        :raises: ValueError if row_data isn't the same length as self.cols
+        :raises ValueError: if row_data isn't the same length as self.cols
         """
         if len(row_data) != len(self.cols):
             raise ValueError("Length of row_data must match length of cols")
@@ -1077,8 +1077,8 @@ class AlternatingTable(BorderedTable):
         :param header_bg: optional background color for header cells (defaults to None)
         :param odd_bg: optional background color for odd numbered data rows (defaults to None)
         :param even_bg: optional background color for even numbered data rows (defaults to StdBg.DARK_GRAY)
-        :raises: ValueError if tab_width is less than 1
-        :raises: ValueError if padding is less than 0
+        :raises ValueError: if tab_width is less than 1
+        :raises ValueError: if padding is less than 0
         """
         super().__init__(
             cols,

cmd2/utils.py

@@ -101,7 +101,7 @@ def to_bool(val: Any) -> bool:
 
     :param val: value being converted
     :return: boolean value expressed in the passed in value
-    :raises: ValueError if the string does not contain a value corresponding to a boolean value
+    :raises ValueError: if the string does not contain a value corresponding to a boolean value
     """
     if isinstance(val, str):
         if val.capitalize() == str(True):
@@ -209,7 +209,7 @@ def is_text_file(file_path: str) -> bool:
 
     :param file_path: path to the file being checked
     :return: True if the file is a non-empty text file, otherwise False
-    :raises OSError if file can't be read
+    :raises OSError: if file can't be read
     """
     import codecs
 
@@ -858,9 +858,9 @@ def align_text(
     :param truncate: if True, then each line will be shortened to fit within the display width. The truncated
                      portions are replaced by a '…' character. Defaults to False.
     :return: aligned text
-    :raises: TypeError if fill_char is more than one character (not including ANSI style sequences)
-    :raises: ValueError if text or fill_char contains an unprintable character
-    :raises: ValueError if width is less than 1
+    :raises TypeError: if fill_char is more than one character (not including ANSI style sequences)
+    :raises ValueError: if text or fill_char contains an unprintable character
+    :raises ValueError: if width is less than 1
     """
     import io
     import shutil
@@ -982,9 +982,9 @@ def align_left(
     :param truncate: if True, then text will be shortened to fit within the display width. The truncated portion is
                      replaced by a '…' character. Defaults to False.
     :return: left-aligned text
-    :raises: TypeError if fill_char is more than one character (not including ANSI style sequences)
-    :raises: ValueError if text or fill_char contains an unprintable character
-    :raises: ValueError if width is less than 1
+    :raises TypeError: if fill_char is more than one character (not including ANSI style sequences)
+    :raises ValueError: if text or fill_char contains an unprintable character
+    :raises ValueError: if width is less than 1
     """
     return align_text(text, TextAlignment.LEFT, fill_char=fill_char, width=width, tab_width=tab_width, truncate=truncate)
 
@@ -1005,9 +1005,9 @@ def align_center(
     :param truncate: if True, then text will be shortened to fit within the display width. The truncated portion is
                      replaced by a '…' character. Defaults to False.
     :return: centered text
-    :raises: TypeError if fill_char is more than one character (not including ANSI style sequences)
-    :raises: ValueError if text or fill_char contains an unprintable character
-    :raises: ValueError if width is less than 1
+    :raises TypeError: if fill_char is more than one character (not including ANSI style sequences)
+    :raises ValueError: if text or fill_char contains an unprintable character
+    :raises ValueError: if width is less than 1
     """
     return align_text(text, TextAlignment.CENTER, fill_char=fill_char, width=width, tab_width=tab_width, truncate=truncate)
 
@@ -1028,9 +1028,9 @@ def align_right(
     :param truncate: if True, then text will be shortened to fit within the display width. The truncated portion is
                      replaced by a '…' character. Defaults to False.
     :return: right-aligned text
-    :raises: TypeError if fill_char is more than one character (not including ANSI style sequences)
-    :raises: ValueError if text or fill_char contains an unprintable character
-    :raises: ValueError if width is less than 1
+    :raises TypeError: if fill_char is more than one character (not including ANSI style sequences)
+    :raises ValueError: if text or fill_char contains an unprintable character
+    :raises ValueError: if width is less than 1
     """
     return align_text(text, TextAlignment.RIGHT, fill_char=fill_char, width=width, tab_width=tab_width, truncate=truncate)
 
@@ -1053,8 +1053,8 @@ def truncate_line(line: str, max_width: int, *, tab_width: int = 4) -> str:
     :param max_width: the maximum display width the resulting string is allowed to have
     :param tab_width: any tabs in the text will be replaced with this many spaces
     :return: line that has a display width less than or equal to width
-    :raises: ValueError if text contains an unprintable character like a newline
-    :raises: ValueError if max_width is less than 1
+    :raises ValueError: if text contains an unprintable character like a newline
+    :raises ValueError: if max_width is less than 1
     """
     import io
 
@@ -1152,17 +1152,18 @@ def categorize(func: Union[Callable[..., Any], Iterable[Callable[..., Any]]], ca
     :param func: function or list of functions to categorize
     :param category: category to put it in
 
-    :Example:
+    Example:
 
-    >>> import cmd2
-    >>> class MyApp(cmd2.Cmd):
-    >>>   def do_echo(self, arglist):
-    >>>     self.poutput(' '.join(arglist)
-    >>>
-    >>>   cmd2.utils.categorize(do_echo, "Text Processing")
+    ```py
+    import cmd2
+    class MyApp(cmd2.Cmd):
+      def do_echo(self, arglist):
+        self.poutput(' '.join(arglist)
 
-    For an alternative approach to categorizing commands using a decorator, see
-    :func:`~cmd2.decorators.with_category`
+      cmd2.utils.categorize(do_echo, "Text Processing")
+    ```
+
+    For an alternative approach to categorizing commands using a decorator, see [cmd2.decorators.with_category][]
     """
     if isinstance(func, Iterable):
         for item in func:

{cmd2-2.5.8.dist-info → cmd2-2.5.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: cmd2
-Version: 2.5.8
+Version: 2.5.10
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License: The MIT License (MIT)
@@ -43,43 +43,10 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: gnureadline; platform_system == "Darwin"
-Requires-Dist: pyperclip
-Requires-Dist: pyreadline3; platform_system == "Windows"
-Requires-Dist: wcwidth
-Provides-Extra: build
-Requires-Dist: build; extra == "build"
-Requires-Dist: setuptools; extra == "build"
-Requires-Dist: setuptools-scm; extra == "build"
-Provides-Extra: dev
-Requires-Dist: codecov; extra == "dev"
-Requires-Dist: doc8; extra == "dev"
-Requires-Dist: invoke; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: pytest-mock; extra == "dev"
-Requires-Dist: sphinx; extra == "dev"
-Requires-Dist: sphinx-autobuild; extra == "dev"
-Requires-Dist: sphinx-rtd-theme; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Provides-Extra: docs
-Requires-Dist: setuptools; extra == "docs"
-Requires-Dist: setuptools_scm; extra == "docs"
-Requires-Dist: sphinx; extra == "docs"
-Requires-Dist: sphinx-autobuild; extra == "docs"
-Requires-Dist: sphinx-rtd-theme; extra == "docs"
-Provides-Extra: test
-Requires-Dist: codecov; extra == "test"
-Requires-Dist: coverage; extra == "test"
-Requires-Dist: pytest; extra == "test"
-Requires-Dist: pytest-cov; extra == "test"
-Requires-Dist: pytest-mock; extra == "test"
-Provides-Extra: validate
-Requires-Dist: mypy; extra == "validate"
-Requires-Dist: ruff; extra == "validate"
-Requires-Dist: types-setuptools; extra == "validate"
+Requires-Dist: gnureadline>=8; platform_system == "Darwin"
+Requires-Dist: pyperclip>=1.8
+Requires-Dist: pyreadline3>=3.4; platform_system == "Windows"
+Requires-Dist: wcwidth>=0.2.10
 
 <h1 align="center">cmd2 : immersive interactive command line applications</h1>
 
@@ -172,13 +139,16 @@ The best way to learn the cmd2 api is to delve into the example applications loc
 ## Tutorials
 
 - PyOhio 2019 presentation:
-  - [video](https://www.youtube.com/watch?v=pebeWrTqIIw)
-  - [slides](https://github.com/python-cmd2/talks/blob/master/PyOhio_2019/cmd2-PyOhio_2019.pdf)
-  - [example code](https://github.com/python-cmd2/talks/tree/master/PyOhio_2019/examples)
+    - [video](https://www.youtube.com/watch?v=pebeWrTqIIw)
+    - [slides](https://github.com/python-cmd2/talks/blob/master/PyOhio_2019/cmd2-PyOhio_2019.pdf)
+    - [example code](https://github.com/python-cmd2/talks/tree/master/PyOhio_2019/examples)
 - [Cookiecutter](https://github.com/cookiecutter/cookiecutter) Templates from community
-  - Basic cookiecutter template for cmd2 application : https://github.com/jayrod/cookiecutter-python-cmd2
-  - Advanced cookiecutter template with external plugin support : https://github.com/jayrod/cookiecutter-python-cmd2-ext-plug
-- [Example Applications](https://github.com/jayrod/cmd2-example-apps)
+    - Basic cookiecutter template for cmd2 application : https://github.com/jayrod/cookiecutter-python-cmd2
+    - Advanced cookiecutter template with external plugin support : https://github.com/jayrod/cookiecutter-python-cmd2-ext-plug
+- [cmd2 example applications](https://github.com/python-cmd2/cmd2/tree/master/examples)
+    - Basic cmd2 examples to demonstrate how to use various features
+- [Advanced Examples](https://github.com/jayrod/cmd2-example-apps)
+    - More complex examples that demonstrate more featuers about how to put together a complete application
 
 ## Hello World
 

cmd2-2.5.10.dist-info/RECORD

@@ -0,0 +1,24 @@
+cmd2/__init__.py,sha256=C6IHJ_uHgkqejuRwA10IK0-OzPxHKyZbPn82nMUwn-A,2602
+cmd2/ansi.py,sha256=nKpnciNvebb9FG0VLfs4yRfq9H49DI27flLoRBMscSo,32036
+cmd2/argparse_completer.py,sha256=M2D1dnc-2SfjzPUUXpBUcD3EJpT34qSsk9ekQtQFOXs,36505
+cmd2/argparse_custom.py,sha256=DqRehL5bEiz5FAQAa1aG2mj3vs91pgeYEtADo_NiEgE,57642
+cmd2/clipboard.py,sha256=7EISono76d7djj17hbvR9cCTB7jVGSBkUjgVQiMyUjE,549
+cmd2/cmd2.py,sha256=VWc-AN_3EYucH5WxrQZpJXxZmQNY25ORnueDhzGosVE,261112
+cmd2/command_definition.py,sha256=g0BWrzQSOrWwvO1BbH5I8yNKNnvYLlXqL9ooKbDaUNY,7655
+cmd2/constants.py,sha256=DioxETv-_HzcMUnjuPyz7Cqw4YEt_MTrzOMotiHj-Jo,1981
+cmd2/decorators.py,sha256=agpCAUqeOhT0PFvYSJ7FNPcccZQntZLw2KAmLAF2AEY,20261
+cmd2/exceptions.py,sha256=DwX7rQmon4eRyX1ZK4yne4lObdPO1j5Agg3Bav6pXwU,3600
+cmd2/history.py,sha256=4iFi0Bny1CTjMx0ByQplrElvlZcus3lUgj2IyBfvAf0,14988
+cmd2/parsing.py,sha256=uVWU_-WEZ_aow5IX9ktbVSE2WB_N86dY0D-GK8kzOhw,28297
+cmd2/plugin.py,sha256=CCzzuHeBQbxH7YuG3UCdQ0uArnKYbodjhj-sYCbXSa0,814
+cmd2/py.typed,sha256=qrkHrYJvGoZpU2BpVLNxJB44LlhqVSKyYOwD_L_1m3s,10
+cmd2/py_bridge.py,sha256=DJCa7ff-XLwcz7Ij47nrwxgDDVUIVS5bRReLmayok1Q,5016
+cmd2/rl_utils.py,sha256=HVPdNjuYyU67-XerPUJArmzhohzI1ABrZhU9cLc-EIs,11538
+cmd2/table_creator.py,sha256=D9HgHaCu66ueCQRI7YIrdCX2g7Ow9hYN3Dj8gRJhXxs,47544
+cmd2/transcript.py,sha256=I0sD38RbG79Qz9GXIlfh1pHSNmWBTY2SLZAKEdSLWI4,9182
+cmd2/utils.py,sha256=50iSIHSenAmpBTefE0_32wT0CM9U5GdT5q4aX8mtzjM,49367
+cmd2-2.5.10.dist-info/LICENSE,sha256=QXrW0Z0merk9mncyUkn-sgRxhT8_o1dL5HEaBNH47Q4,1099
+cmd2-2.5.10.dist-info/METADATA,sha256=HrBCCwsip1J1m09TS9BXQfYrLTFTfX3PolKu3aaOwoM,17104
+cmd2-2.5.10.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+cmd2-2.5.10.dist-info/top_level.txt,sha256=gJbOJmyrARwLhm5diXAtzlNQdxbDZ8iRJ8HJi65_5hg,5
+cmd2-2.5.10.dist-info/RECORD,,

{cmd2-2.5.8.dist-info → cmd2-2.5.10.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.6.0)
+Generator: setuptools (75.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

cmd2-2.5.8.dist-info/RECORD

@@ -1,24 +0,0 @@
-cmd2/__init__.py,sha256=C6IHJ_uHgkqejuRwA10IK0-OzPxHKyZbPn82nMUwn-A,2602
-cmd2/ansi.py,sha256=DD1yVk4EnbKSmGM9Tj8jxWv23UZBVjbhdf0oOVhhl_c,32054
-cmd2/argparse_completer.py,sha256=6z0zmODqM7vhQhI0c6JUvCmR2V4qfdWQEyTZeNIea8c,36505
-cmd2/argparse_custom.py,sha256=bbAYRr79ZSJWGchd7trmRQDHWAsSJaW0dTQMp65Mrv4,57806
-cmd2/clipboard.py,sha256=7EISono76d7djj17hbvR9cCTB7jVGSBkUjgVQiMyUjE,549
-cmd2/cmd2.py,sha256=--45LzbUB5vLrrHYPV_pSQK3H9ePAacb4lBlXBQfB1A,261355
-cmd2/command_definition.py,sha256=OscFEk-O2N20fb8_fhkczqclaCxOwYyxNTnXWXOlngg,7655
-cmd2/constants.py,sha256=DioxETv-_HzcMUnjuPyz7Cqw4YEt_MTrzOMotiHj-Jo,1981
-cmd2/decorators.py,sha256=XXQKqei5CVM6k5zt8CdBmIDan-QwuN3YgJiaIsabbuA,19820
-cmd2/exceptions.py,sha256=DwX7rQmon4eRyX1ZK4yne4lObdPO1j5Agg3Bav6pXwU,3600
-cmd2/history.py,sha256=GkJ3pZQNGNoXa9pYLul_iaqLeK132V5nLZZG6MsIEus,15000
-cmd2/parsing.py,sha256=zWG_iDjUU6TWVNwMeY-yn6AIa2jx12Q9ey4DA9DGZFc,28272
-cmd2/plugin.py,sha256=CCzzuHeBQbxH7YuG3UCdQ0uArnKYbodjhj-sYCbXSa0,814
-cmd2/py.typed,sha256=qrkHrYJvGoZpU2BpVLNxJB44LlhqVSKyYOwD_L_1m3s,10
-cmd2/py_bridge.py,sha256=YUkEnng_kAwnFbh1sPMyeMya_BF7G1kg6MT-6mW-IG4,5022
-cmd2/rl_utils.py,sha256=HVPdNjuYyU67-XerPUJArmzhohzI1ABrZhU9cLc-EIs,11538
-cmd2/table_creator.py,sha256=qoxt9s3MxQkfSkp4cIPFMlVzC7kRjUU55p0ow7pFQus,47544
-cmd2/transcript.py,sha256=I0sD38RbG79Qz9GXIlfh1pHSNmWBTY2SLZAKEdSLWI4,9182
-cmd2/utils.py,sha256=4eBvbG6yqe3wg9wwi2jdng2iy5gghueNQjuF2afSyuI,49385
-cmd2-2.5.8.dist-info/LICENSE,sha256=QXrW0Z0merk9mncyUkn-sgRxhT8_o1dL5HEaBNH47Q4,1099
-cmd2-2.5.8.dist-info/METADATA,sha256=-y-uEodZc06B7Akuvlb5oRWVfaTmuUqjwJZ4kGuvR_I,18098
-cmd2-2.5.8.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-cmd2-2.5.8.dist-info/top_level.txt,sha256=gJbOJmyrARwLhm5diXAtzlNQdxbDZ8iRJ8HJi65_5hg,5
-cmd2-2.5.8.dist-info/RECORD,,