Merge pull request #899 from python-cmd2/api_docs

API documentation

Author: tleonhardt

cmd2/ansi.py

@@ -17,11 +17,33 @@
 
 # Values for allow_style setting
 STYLE_NEVER = 'Never'
+"""
+Constant for ``cmd2.ansi.allow_style`` to indicate ANSI sequences
+should be removed from all output.
+"""
 STYLE_TERMINAL = 'Terminal'
+"""
+Constant for ``cmd2.ansi.allow_style`` to indicate ANSI sequences
+should be removed if the output is not going to the terminal.
+"""
 STYLE_ALWAYS = 'Always'
+"""
+Constant for ``cmd2.ansi.allow_style`` to indicate ANSI sequences
+should alwyas be output.
+"""
 
 # Controls when ANSI style style sequences are allowed in output
 allow_style = STYLE_TERMINAL
+"""When using outside of a cmd2 app, set this variable to one of:
+
+- ``STYLE_NEVER`` - remove ANSI sequences from all output
+- ``STYLE_TERMINAL`` - remove ANSI sequences if the output is not going to the terminal
+- ``STYLE_ALWAYS`` - always output ANSI sequences
+
+to control the output of ANSI sequences by methods in this module.
+
+The default is ``STYLE_TERMINAL``.
+"""
 
 # Regular expression to match ANSI style sequences (including 8-bit and 24-bit colors)
 ANSI_STYLE_RE = re.compile(r'\x1b\[[^m]*m')
@@ -32,7 +54,9 @@ class ColorBase(Enum):
     Base class used for defining color enums. See fg and bg classes for examples.
 
     Child classes should define enums in the follow structure:
+
         key: color name (e.g. black)
+
         value: anything that when cast to a string returns an ANSI sequence
     """
     def __str__(self) -> str:
@@ -111,17 +135,25 @@ class bg(ColorBase):
 
 
 FG_RESET = fg.reset.value
+"""ANSI sequence to reset the foreground attributes"""
 BG_RESET = bg.reset.value
+"""ANSI sequence to reset the terminal background attributes"""
 RESET_ALL = Style.RESET_ALL
+"""ANSI sequence to reset all terminal attributes"""
 
 # Text intensities
 INTENSITY_BRIGHT = Style.BRIGHT
+"""ANSI sequence to make the text bright"""
 INTENSITY_DIM = Style.DIM
+"""ANSI sequence to make the text dim"""
 INTENSITY_NORMAL = Style.NORMAL
+"""ANSI sequence to make the text normal"""
 
 # ANSI style sequences not provided by colorama
 UNDERLINE_ENABLE = colorama.ansi.code_to_chars(4)
+"""ANSI sequence to turn on underline"""
 UNDERLINE_DISABLE = colorama.ansi.code_to_chars(24)
+"""ANSI sequence to turn off underline"""
 
 
 def strip_style(text: str) -> str:

cmd2/argparse_custom.py

@@ -135,28 +135,41 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
                  allow_cli_args: bool = True, transcript_files: Optional[List[str]] = None,
                  allow_redirection: bool = True, multiline_commands: Optional[List[str]] = None,
                  terminators: Optional[List[str]] = None, shortcuts: Optional[Dict[str, str]] = None) -> None:
-        """An easy but powerful framework for writing line-oriented command interpreters, extends Python's cmd package.
+        """An easy but powerful framework for writing line-oriented command
+        interpreters. Extends Python's cmd package.
 
         :param completekey: readline name of a completion key, default to Tab
         :param stdin: alternate input file object, if not specified, sys.stdin is used
         :param stdout: alternate output file object, if not specified, sys.stdout is used
         :param persistent_history_file: file path to load a persistent cmd2 command history from
-        :param persistent_history_length: max number of history items to write to the persistent history file
+        :param persistent_history_length: max number of history items to write
+                                          to the persistent history file
         :param startup_script: file path to a script to execute at startup
         :param use_ipython: should the "ipy" command be included for an embedded IPython shell
-        :param allow_cli_args: if True, then cmd2 will process command line arguments as either
-                               commands to be run or, if -t is specified, transcript files to run.
-                               This should be set to False if your application parses its own arguments.
-        :param transcript_files: allow running transcript tests when allow_cli_args is False
-        :param allow_redirection: should output redirection and pipes be allowed. this is only a security setting
-                                  and does not alter parsing behavior.
+        :param allow_cli_args: if ``True``, then :meth:`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
+                               arguments.
+        :param transcript_files: pass a list of transcript files to be run on initialization.
+                                 This allows running transcript tests when ``allow_cli_args``
+                                 is ``False``. If ``allow_cli_args`` is ``True`` this parameter
+                                 is ignored.
+        :param allow_redirection: If ``False``, prevent output redirection and piping to shell
+                                  commands. This parameter prevents redirection and piping, but
+                                  does not alter parsing behavior. A user can still type
+                                  redirection and piping tokens, and they will be parsed as such
+                                  but they won't do anything.
         :param multiline_commands: list of commands allowed to accept multi-line input
-        :param terminators: list of characters that terminate a command. These are mainly intended for terminating
-                            multiline commands, but will also terminate single-line commands. If not supplied, then
-                            defaults to semicolon. If your app only contains single-line commands and you want
-                            terminators to be treated as literals by the parser, then set this to an empty list.
-        :param shortcuts: dictionary containing shortcuts for commands. If not supplied, then defaults to
-                          constants.DEFAULT_SHORTCUTS.
+        :param terminators: list of characters that terminate a command. These are mainly
+                            intended for terminating multiline commands, but will also
+                            terminate single-line commands. If not supplied, the default
+                            is a semicolon. If your app only contains single-line commands
+                            and you want terminators to be treated as literals by the parser,
+                            then set this to an empty list.
+        :param shortcuts: dictionary containing shortcuts for commands. If not supplied,
+                          then defaults to constants.DEFAULT_SHORTCUTS. If you do not want
+                          any shortcuts, pass an empty dictionary.
         """
         # If use_ipython is False, make sure the ipy command isn't available in this instance
         if not use_ipython:
@@ -192,7 +205,7 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
 
         # A dictionary mapping settable names to their Settable instance
         self.settables = dict()
-        self.build_settables()
+        self._build_settables()
 
         # Use as prompt for multiline commands on the 2nd+ line of input
         self.continuation_prompt = '> '
@@ -374,24 +387,26 @@ def __init__(self, completekey: str = 'tab', stdin=None, stdout=None, *,
 
     def add_settable(self, settable: Settable) -> None:
         """
-        Convenience method to add a settable parameter to self.settables
+        Convenience method to add a settable parameter to ``self.settables``
+
         :param settable: Settable object being added
         """
         self.settables[settable.name] = settable
 
     def remove_settable(self, name: str) -> None:
         """
-        Convenience method for removing a settable parameter from self.settables
+        Convenience method for removing a settable parameter from ``self.settables``
+
         :param name: name of the settable being removed
-        :raises: KeyError if the no Settable matches this name
+        :raises: KeyError if the Settable matches this name
         """
         try:
             del self.settables[name]
         except KeyError:
             raise KeyError(name + " is not a settable parameter")
 
-    def build_settables(self):
-        """Populates self.add_settable with parameters that can be edited via the set command"""
+    def _build_settables(self):
+        """Construct the default settings"""
         self.add_settable(Settable('allow_style', str,
                                    'Allow ANSI text style sequences in output (valid values: '
                                    '{}, {}, {})'.format(ansi.STYLE_TERMINAL,
@@ -1508,13 +1523,54 @@ def sigint_handler(self, signum: int, frame) -> None:
             raise KeyboardInterrupt("Got a keyboard interrupt")
 
     def precmd(self, statement: Statement) -> Statement:
-        """Hook method executed just before the command is processed by ``onecmd()`` and after adding it to the history.
+        """Hook method executed just before the command is executed by
+        :meth:`~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
+        to run hooks before the command is executed. See
+        :ref:`features/hooks:Postparsing Hooks` and
+        :ref:`features/hooks:Precommand Hooks` for more information.
         """
         return statement
 
+    def postcmd(self, stop: bool, statement: Statement) -> bool:
+        """Hook method executed just after a command is executed by
+        :meth:`~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
+        to run hooks after the command is executed. See
+        :ref:`features/hooks:Postcommand Hooks` and
+        :ref:`features/hooks:Command Finalization Hooks` for more information.
+        """
+        return stop
+
+    def preloop(self):
+        """Hook method executed once when the :meth:`~.cmd2.Cmd.cmdloop()`
+        method is called.
+
+        See :meth:`~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.
+        """
+        pass
+
+    def postloop(self):
+        """Hook method executed once when the :meth:`~.cmd2.Cmd.cmdloop()`
+        method is about to return.
+
+        See :meth:`~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.
+        """
+        pass
+
     def parseline(self, line: str) -> Tuple[str, str, str]:
         """Parse the line into a command name and a string containing the arguments.
 

cmd2/cmd2.py

@@ -1,6 +1,10 @@
 #
 # coding=utf-8
-"""Constants and definitions"""
+"""This module contains constants used throughout ``cmd2``."""
+
+# Unless documented in https://cmd2.readthedocs.io/en/latest/api/index.html
+# nothing here should be considered part of the public API of this module
+
 
 # Used for command parsing, output redirection, tab completion and word
 # breaks. Do not change.
@@ -32,9 +36,9 @@
 # All command completer functions start with this
 COMPLETER_FUNC_PREFIX = 'complete_'
 
-############################################################################################################
+##############################################################################
 # The following are optional attributes added to do_* command functions
-############################################################################################################
+##############################################################################
 
 # The custom help category a command belongs to
 CMD_ATTR_HELP_CATEGORY = 'help_category'

cmd2/constants.py

@@ -8,7 +8,21 @@
 
 
 def with_category(category: str) -> Callable:
-    """A decorator to apply a category to a command function."""
+    """A decorator to apply a category to a ``do_*`` command method.
+
+    :param category: the name of the category in which this command should
+                     be grouped when displaying the list of commands.
+
+    :Example:
+
+    >>> 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`
+    """
     def cat_decorator(func):
         from .utils import categorize
         categorize(func, category)
@@ -17,12 +31,22 @@ def cat_decorator(func):
 
 
 def with_argument_list(*args: List[Callable], preserve_quotes: bool = False) -> Callable[[List], Optional[bool]]:
-    """A decorator to alter the arguments passed to a do_* cmd2 method. Default passes a string of whatever the user
-    typed. With this decorator, the decorated method will receive a list of arguments parsed from user input.
+    """
+    A decorator to alter the arguments passed to a ``do_*`` method. Default
+    passes a string of whatever the user typed. With this decorator, the
+    decorated method will receive a list of arguments parsed from user input.
 
-    :param args: Single-element positional argument list containing do_* method this decorator is wrapping
-    :param preserve_quotes: if True, then argument quotes will not be stripped
+    :param args: Single-element positional argument list containing ``do_*`` method
+                 this decorator is wrapping
+    :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)
     """
     import functools
 
@@ -75,18 +99,19 @@ def with_argparser_and_unknown_args(parser: argparse.ArgumentParser, *,
                                     ns_provider: Optional[Callable[..., argparse.Namespace]] = None,
                                     preserve_quotes: bool = False) -> \
         Callable[[argparse.Namespace, List], Optional[bool]]:
-    """A decorator to alter a cmd2 method to populate its ``args`` argument by parsing arguments with the given
-    instance of argparse.ArgumentParser, but also returning unknown args as a list.
+    """A decorator to alter a cmd2 method to populate its ``args`` argument by parsing
+    arguments with the given instance of argparse.ArgumentParser, but also returning
+    unknown args as a list.
 
     :param parser: unique instance of ArgumentParser
-    :param ns_provider: An optional function that accepts a cmd2.Cmd object as an argument and returns an
-                        argparse.Namespace. This is useful if the Namespace needs to be prepopulated with
-                        state data that affects parsing.
-    :param preserve_quotes: if True, then arguments passed to argparse maintain their quotes
-    :return: function that gets passed argparse-parsed args in a Namespace and a list of unknown argument strings
-             A member called __statement__ is added to the Namespace to provide command functions access to the
-             Statement object. This can be useful if the command function needs to know the command line.
-
+    :param ns_provider: An optional function that accepts a cmd2.Cmd object as an argument
+                        and returns an argparse.Namespace. This is useful if the Namespace
+                        needs to be prepopulated with state data that affects parsing.
+    :param preserve_quotes: if ``True``, then arguments passed to argparse maintain their quotes
+    :return: function that gets passed argparse-parsed args in a ``Namespace`` and a list
+             of unknown argument strings. A member called ``__statement__`` is added to the
+             ``Namespace`` to provide command functions access to the :class:`cmd2.Statement`
+             object. This can be useful if the command function needs to know the command line.
     """
     import functools