cmd2 2.4.2__py3-none-any.whl → 2.5.9__py3-none-any.whl

cmd2/history.py

@@ -8,6 +8,9 @@ import re
 from collections import (
     OrderedDict,
 )
+from dataclasses import (
+    dataclass,
+)
 from typing import (
     Any,
     Callable,
@@ -19,17 +22,54 @@ from typing import (
     overload,
 )
 
-import attr
-
 from . import (
     utils,
 )
 from .parsing import (
     Statement,
+    shlex_split,
 )
 
 
-@attr.s(auto_attribs=True, frozen=True)
+def single_line_format(statement: Statement) -> str:
+    """
+    Format a command line to display on a single line.
+
+    Spaces and newlines in quotes are preserved so those strings will span multiple lines.
+
+    :param statement: Statement being formatted.
+    :return: formatted command line
+    """
+    if not statement.raw:
+        return ""
+
+    lines = statement.raw.splitlines()
+    formatted_command = lines[0]
+
+    # Append any remaining lines to the command.
+    for line in lines[1:]:
+        try:
+            shlex_split(formatted_command)
+        except ValueError:
+            # We are in quotes, so restore the newline.
+            separator = "\n"
+        else:
+            # Don't add a space before line if one already exists or if it begins with the terminator.
+            if (
+                formatted_command.endswith(" ")
+                or line.startswith(" ")
+                or (statement.terminator and line.startswith(statement.terminator))
+            ):
+                separator = ""
+            else:
+                separator = " "
+
+        formatted_command += separator + line
+
+    return formatted_command
+
+
+@dataclass(frozen=True)
 class HistoryItem:
     """Class used to represent one command in the history list"""
 
@@ -39,10 +79,10 @@ class HistoryItem:
     # Used in JSON dictionaries
     _statement_field = 'statement'
 
-    statement: Statement = attr.ib(default=None, validator=attr.validators.instance_of(Statement))
+    statement: Statement
 
     def __str__(self) -> str:
-        """A convenient human readable representation of the history item"""
+        """A convenient human-readable representation of the history item"""
         return self.statement.raw
 
     @property
@@ -84,15 +124,7 @@ class HistoryItem:
             if expanded:
                 ret_str = self.expanded
             else:
-                ret_str = self.raw.rstrip()
-
-                # In non-verbose mode, display raw multiline commands on 1 line
-                if self.statement.multiline_command:
-                    # This is an approximation and not meant to be a perfect piecing together of lines.
-                    # All newlines will be converted to spaces, including the ones in quoted strings that
-                    # are considered literals. Also if the final line starts with a terminator, then the
-                    # terminator will have an extra space before it in the 1 line version.
-                    ret_str = ret_str.replace('\n', ' ')
+                ret_str = single_line_format(self.statement).rstrip()
 
             # Display a numbered list if not writing to a script
             if not script:
@@ -118,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
@@ -144,7 +176,6 @@ class History(List[HistoryItem]):
         """Start a new session, thereby setting the next index as the first index in the new session."""
         self.session_start_index = len(self)
 
-    # noinspection PyMethodMayBeStatic
     def _zero_based_index(self, onebased: Union[int, str]) -> int:
         """Convert a one-based index to a zero-based index."""
         result = int(onebased)
@@ -153,12 +184,10 @@ class History(List[HistoryItem]):
         return result
 
     @overload
-    def append(self, new: HistoryItem) -> None:
-        ...  # pragma: no cover
+    def append(self, new: HistoryItem) -> None: ...  # pragma: no cover
 
     @overload
-    def append(self, new: Statement) -> None:
-        ...  # pragma: no cover
+    def append(self, new: Statement) -> None: ...  # pragma: no cover
 
     def append(self, new: Union[Statement, HistoryItem]) -> None:
         """Append a new statement to the end of the History list.
@@ -178,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

@@ -4,6 +4,10 @@
 
 import re
 import shlex
+from dataclasses import (
+    dataclass,
+    field,
+)
 from typing import (
     Any,
     Dict,
@@ -14,8 +18,6 @@ from typing import (
     Union,
 )
 
-import attr
-
 from . import (
     constants,
     utils,
@@ -36,7 +38,7 @@ def shlex_split(str_to_split: str) -> List[str]:
     return shlex.split(str_to_split, comments=False, posix=False)
 
 
-@attr.s(auto_attribs=True, frozen=True)
+@dataclass(frozen=True)
 class MacroArg:
     """
     Information used to replace or unescape arguments in a macro value when the macro is resolved
@@ -45,15 +47,15 @@ class MacroArg:
     """
 
     # The starting index of this argument in the macro value
-    start_index: int = attr.ib(validator=attr.validators.instance_of(int))
+    start_index: int
 
     # The number string that appears between the braces
     # This is a string instead of an int because we support unicode digits and must be able
     # to reproduce this string later
-    number_str: str = attr.ib(validator=attr.validators.instance_of(str))
+    number_str: str
 
     # Tells if this argument is escaped and therefore needs to be unescaped
-    is_escaped: bool = attr.ib(validator=attr.validators.instance_of(bool))
+    is_escaped: bool
 
     # Pattern used to find normal argument
     # Digits surrounded by exactly 1 brace on a side and 1 or more braces on the opposite side
@@ -69,24 +71,24 @@ class MacroArg:
     digit_pattern = re.compile(r'\d+')
 
 
-@attr.s(auto_attribs=True, frozen=True)
+@dataclass(frozen=True)
 class Macro:
     """Defines a cmd2 macro"""
 
     # Name of the macro
-    name: str = attr.ib(validator=attr.validators.instance_of(str))
+    name: str
 
     # The string the macro resolves to
-    value: str = attr.ib(validator=attr.validators.instance_of(str))
+    value: str
 
     # The minimum number of args the user has to pass to this macro
-    minimum_arg_count: int = attr.ib(validator=attr.validators.instance_of(int))
+    minimum_arg_count: int
 
     # Used to fill in argument placeholders in the macro
-    arg_list: List[MacroArg] = attr.ib(default=attr.Factory(list), validator=attr.validators.instance_of(list))
+    arg_list: List[MacroArg] = field(default_factory=list)
 
 
-@attr.s(auto_attribs=True, frozen=True)
+@dataclass(frozen=True)
 class Statement(str):  # type: ignore[override]
     """String subclass with additional attributes to store the results of parsing.
 
@@ -96,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
@@ -106,46 +108,46 @@ 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.
-    args: str = attr.ib(default='', validator=attr.validators.instance_of(str))
+    args: str = ''
 
     # string containing exactly what we input by the user
-    raw: str = attr.ib(default='', validator=attr.validators.instance_of(str))
+    raw: str = ''
 
     # the command, i.e. the first whitespace delimited word
-    command: str = attr.ib(default='', validator=attr.validators.instance_of(str))
+    command: str = ''
 
     # list of arguments to the command, not including any output redirection or terminators; quoted args remain quoted
-    arg_list: List[str] = attr.ib(default=attr.Factory(list), validator=attr.validators.instance_of(list))
+    arg_list: List[str] = field(default_factory=list)
 
     # if the command is a multiline command, the name of the command, otherwise empty
-    multiline_command: str = attr.ib(default='', validator=attr.validators.instance_of(str))
+    multiline_command: str = ''
 
     # the character which terminated the multiline command, if there was one
-    terminator: str = attr.ib(default='', validator=attr.validators.instance_of(str))
+    terminator: str = ''
 
     # characters appearing after the terminator but before output redirection, if any
-    suffix: str = attr.ib(default='', validator=attr.validators.instance_of(str))
+    suffix: str = ''
 
     # if output was piped to a shell command, the shell command as a string
-    pipe_to: str = attr.ib(default='', validator=attr.validators.instance_of(str))
+    pipe_to: str = ''
 
     # if output was redirected, the redirection token, i.e. '>>'
-    output: str = attr.ib(default='', validator=attr.validators.instance_of(str))
+    output: str = ''
 
     # if output was redirected, the destination file token (quotes preserved)
-    output_to: str = attr.ib(default='', validator=attr.validators.instance_of(str))
+    output_to: str = ''
 
     # Used in JSON dictionaries
     _args_field = 'args'
@@ -156,7 +158,7 @@ class Statement(str):  # type: ignore[override]
         We must override __new__ because we are subclassing `str` which is
         immutable and takes a different number of arguments as Statement.
 
-        NOTE:  attrs takes care of initializing other members in the __init__ it
+        NOTE:  @dataclass takes care of initializing other members in the __init__ it
         generates.
         """
         stmt = super().__new__(cls, value)
@@ -200,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
@@ -348,7 +349,7 @@ class StatementParser:
             return False, 'cannot start with the comment character'
 
         if not is_subcommand:
-            for (shortcut, _) in self.shortcuts:
+            for shortcut, _ in self.shortcuts:
                 if word.startswith(shortcut):
                     # Build an error string with all shortcuts listed
                     errmsg = 'cannot start with a shortcut: '
@@ -397,12 +398,12 @@ 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
+        :return: a new [cmd2.parsing.Statement][] object
         :raises: Cmd2ShlexError if a shlex error occurs (e.g. No closing quotation)
         """
 
@@ -481,7 +482,6 @@ class StatementParser:
 
         # Check if output should be piped to a shell command
         if pipe_index < redir_index and pipe_index < append_index:
-
             # Get the tokens for the pipe command and expand ~ where needed
             pipe_to_tokens = tokens[pipe_index + 1 :]
             utils.expand_user_in_tokens(pipe_to_tokens)
@@ -543,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
@@ -552,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)
@@ -580,8 +580,15 @@ class StatementParser:
 
             # take everything from the end of the first match group to
             # the end of the line as the arguments (stripping leading
-            # and trailing spaces)
-            args = line[match.end(1) :].strip()
+            # and unquoted trailing whitespace)
+            args = line[match.end(1) :].lstrip()
+            try:
+                shlex_split(args)
+            except ValueError:
+                # Unclosed quote. Leave trailing whitespace.
+                pass
+            else:
+                args = args.rstrip()
             # if the command is empty that means the input was either empty
             # or something weird like '>'. args should be empty if we couldn't
             # parse a command
@@ -609,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
@@ -656,7 +663,7 @@ class StatementParser:
                     keep_expanding = bool(remaining_aliases)
 
         # expand shortcuts
-        for (shortcut, expansion) in self.shortcuts:
+        for shortcut, expansion in self.shortcuts:
             if line.startswith(shortcut):
                 # If the next character after the shortcut isn't a space, then insert one
                 shortcut_len = len(shortcut)
@@ -701,7 +708,6 @@ class StatementParser:
         punctuated_tokens = []
 
         for cur_initial_token in tokens:
-
             # Save tokens up to 1 character in length or quoted tokens. No need to parse these.
             if len(cur_initial_token) <= 1 or cur_initial_token[0] in constants.QUOTES:
                 punctuated_tokens.append(cur_initial_token)
@@ -716,7 +722,6 @@ class StatementParser:
 
             while True:
                 if cur_char not in punctuation:
-
                     # Keep appending to new_token until we hit a punctuation char
                     while cur_char not in punctuation:
                         new_token += cur_char

cmd2/plugin.py

@@ -1,18 +1,20 @@
 #
 # coding=utf-8
 """Classes for the cmd2 plugin system"""
+
+from dataclasses import (
+    dataclass,
+)
 from typing import (
     Optional,
 )
 
-import attr
-
 from .parsing import (
     Statement,
 )
 
 
-@attr.s(auto_attribs=True)
+@dataclass
 class PostparsingData:
     """Data class containing information passed to postparsing hook methods"""
 
@@ -20,14 +22,14 @@ class PostparsingData:
     statement: Statement
 
 
-@attr.s(auto_attribs=True)
+@dataclass
 class PrecommandData:
     """Data class containing information passed to precommand hook methods"""
 
     statement: Statement
 
 
-@attr.s(auto_attribs=True)
+@dataclass
 class PostcommandData:
     """Data class containing information passed to postcommand hook methods"""
 
@@ -35,7 +37,7 @@ class PostcommandData:
     statement: Statement
 
 
-@attr.s(auto_attribs=True)
+@dataclass
 class CommandFinalizationData:
     """Data class containing information passed to command finalization hook methods"""
 

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::
 
@@ -83,10 +83,17 @@ class CommandResult(NamedTuple):
 
 
 class PyBridge:
-    """Provides a Python API wrapper for application commands."""
+    """
+    Provides a Python API wrapper for application commands.
+
+    :param cmd2_app: app being controlled by this PyBridge.
+    :param add_to_history: If True, then add all commands run by this PyBridge to history.
+                           Defaults to True.
+    """
 
-    def __init__(self, cmd2_app: 'cmd2.Cmd') -> None:
+    def __init__(self, cmd2_app: 'cmd2.Cmd', *, add_to_history: bool = True) -> None:
         self._cmd2_app = cmd2_app
+        self._add_to_history = add_to_history
         self.cmd_echo = False
 
         # Tells if any of the commands run via __call__ returned True for stop
@@ -126,7 +133,11 @@ class PyBridge:
             self._cmd2_app.stdout = cast(TextIO, copy_cmd_stdout)
             with redirect_stdout(cast(IO[str], copy_cmd_stdout)):
                 with redirect_stderr(cast(IO[str], copy_stderr)):
-                    stop = self._cmd2_app.onecmd_plus_hooks(command, py_bridge_call=True)
+                    stop = self._cmd2_app.onecmd_plus_hooks(
+                        command,
+                        add_to_history=self._add_to_history,
+                        py_bridge_call=True,
+                    )
         finally:
             with self._cmd2_app.sigint_protection:
                 self._cmd2_app.stdout = cast(IO[str], copy_cmd_stdout.inner_stream)