cmd2 2.5.11__py3-none-any.whl → 2.6.0__py3-none-any.whl

cmd2/history.py

@@ -1,22 +1,16 @@
-# coding=utf-8
-"""
-History management classes
-"""
+"""History management classes."""
 
 import json
 import re
 from collections import (
     OrderedDict,
 )
+from collections.abc import Callable, Iterable
 from dataclasses import (
     dataclass,
 )
 from typing import (
     Any,
-    Callable,
-    Dict,
-    Iterable,
-    List,
     Optional,
     Union,
     overload,
@@ -32,8 +26,7 @@ from .parsing import (
 
 
 def single_line_format(statement: Statement) -> str:
-    """
-    Format a command line to display on a single line.
+    """Format a command line to display on a single line.
 
     Spaces and newlines in quotes are preserved so those strings will span multiple lines.
 
@@ -71,7 +64,7 @@ def single_line_format(statement: Statement) -> str:
 
 @dataclass(frozen=True)
 class HistoryItem:
-    """Class used to represent one command in the history list"""
+    """Class used to represent one command in the history list."""
 
     _listformat = ' {:>4}  {}'
     _ex_listformat = ' {:>4}x {}'
@@ -82,7 +75,7 @@ class HistoryItem:
     statement: Statement
 
     def __str__(self) -> str:
-        """A convenient human-readable representation of the history item"""
+        """Human-readable representation of the history item."""
         return self.statement.raw
 
     @property
@@ -95,8 +88,7 @@ class HistoryItem:
 
     @property
     def expanded(self) -> str:
-        """Return the command as run which includes shortcuts and aliases resolved
-        plus any changes made in hooks
+        """Return the command as run which includes shortcuts and aliases resolved plus any changes made in hooks.
 
         Proxy property for ``self.statement.expanded_command_line``
         """
@@ -121,10 +113,7 @@ class HistoryItem:
             if raw != expanded_command:
                 ret_str += '\n' + self._ex_listformat.format(idx, expanded_command)
         else:
-            if expanded:
-                ret_str = self.expanded
-            else:
-                ret_str = single_line_format(self.statement).rstrip()
+            ret_str = self.expanded if expanded else single_line_format(self.statement).rstrip()
 
             # Display a numbered list if not writing to a script
             if not script:
@@ -132,14 +121,13 @@ class HistoryItem:
 
         return ret_str
 
-    def to_dict(self) -> Dict[str, Any]:
-        """Utility method to convert this HistoryItem into a dictionary for use in persistent JSON history files"""
+    def to_dict(self) -> dict[str, Any]:
+        """Convert this HistoryItem into a dictionary for use in persistent JSON history files."""
         return {HistoryItem._statement_field: self.statement.to_dict()}
 
     @staticmethod
-    def from_dict(source_dict: Dict[str, Any]) -> 'HistoryItem':
-        """
-        Utility method to restore a HistoryItem from a dictionary
+    def from_dict(source_dict: dict[str, Any]) -> 'HistoryItem':
+        """Restore a HistoryItem from a dictionary.
 
         :param source_dict: source data dictionary (generated using to_dict())
         :return: HistoryItem object
@@ -149,9 +137,8 @@ class HistoryItem:
         return HistoryItem(Statement.from_dict(statement_dict))
 
 
-class History(List[HistoryItem]):
-    """A list of [HistoryItem][cmd2.history.HistoryItem] objects with additional methods
-    for searching and managing the list.
+class History(list[HistoryItem]):
+    """A list of [HistoryItem][cmd2.history.HistoryItem] objects with additional methods for searching and managing the list.
 
     [cmd2.Cmd][] instantiates this class into the `cmd2.Cmd.history`
     attribute, and adds commands to it as a user enters them.
@@ -169,7 +156,8 @@ class History(List[HistoryItem]):
     _history_items_field = 'history_items'
 
     def __init__(self, seq: Iterable[HistoryItem] = ()) -> None:
-        super(History, self).__init__(seq)
+        """Initialize History instances."""
+        super().__init__(seq)
         self.session_start_index = 0
 
     def start_session(self) -> None:
@@ -196,7 +184,7 @@ class History(List[HistoryItem]):
                     and added to the end of the list
         """
         history_item = HistoryItem(new) if isinstance(new, Statement) else new
-        super(History, self).append(history_item)
+        super().append(history_item)
 
     def clear(self) -> None:
         """Remove all items from the History list."""
@@ -211,10 +199,9 @@ class History(List[HistoryItem]):
         """
         if index == 0:
             raise IndexError('The first command in history is command 1.')
-        elif index < 0:
+        if index < 0:
             return self[index]
-        else:
-            return self[index - 1]
+        return self[index - 1]
 
     # This regular expression parses input for the span() method. There are five parts:
     #
@@ -243,7 +230,7 @@ class History(List[HistoryItem]):
     spanpattern = re.compile(r'^\s*(?P<start>-?[1-9]\d*)?(?P<separator>:|(\.{2,}))(?P<end>-?[1-9]\d*)?\s*$')
 
     def span(self, span: str, include_persisted: bool = False) -> 'OrderedDict[int, HistoryItem]':
-        """Return a slice of the History list
+        """Return a slice of the History list.
 
         :param span: string containing an index or a slice
         :param include_persisted: if True, then retrieve full results including from persisted history
@@ -292,7 +279,7 @@ class History(List[HistoryItem]):
         return self._build_result_dictionary(start, end)
 
     def str_search(self, search: str, include_persisted: bool = False) -> 'OrderedDict[int, HistoryItem]':
-        """Find history items which contain a given string
+        """Find history items which contain a given string.
 
         :param search: the string to search for
         :param include_persisted: if True, then search full history including persisted history
@@ -301,7 +288,7 @@ class History(List[HistoryItem]):
         """
 
         def isin(history_item: HistoryItem) -> bool:
-            """filter function for string search of history"""
+            """Filter function for string search of history."""
             sloppy = utils.norm_fold(search)
             inraw = sloppy in utils.norm_fold(history_item.raw)
             inexpanded = sloppy in utils.norm_fold(history_item.expanded)
@@ -311,7 +298,7 @@ class History(List[HistoryItem]):
         return self._build_result_dictionary(start, len(self), isin)
 
     def regex_search(self, regex: str, include_persisted: bool = False) -> 'OrderedDict[int, HistoryItem]':
-        """Find history items which match a given regular expression
+        """Find history items which match a given regular expression.
 
         :param regex: the regular expression to search for.
         :param include_persisted: if True, then search full history including persisted history
@@ -324,14 +311,14 @@ class History(List[HistoryItem]):
         finder = re.compile(regex, re.DOTALL | re.MULTILINE)
 
         def isin(hi: HistoryItem) -> bool:
-            """filter function for doing a regular expression search of history"""
+            """Filter function for doing a regular expression search of history."""
             return bool(finder.search(hi.raw) or finder.search(hi.expanded))
 
         start = 0 if include_persisted else self.session_start_index
         return self._build_result_dictionary(start, len(self), isin)
 
     def truncate(self, max_length: int) -> None:
-        """Truncate the length of the history, dropping the oldest items if necessary
+        """Truncate the length of the history, dropping the oldest items if necessary.
 
         :param max_length: the maximum length of the history, if negative, all history
                            items will be deleted
@@ -347,10 +334,10 @@ class History(List[HistoryItem]):
     def _build_result_dictionary(
         self, start: int, end: int, filter_func: Optional[Callable[[HistoryItem], bool]] = None
     ) -> 'OrderedDict[int, HistoryItem]':
-        """
-        Build history search results
+        """Build history search results.
+
         :param start: start index to search from
-        :param end: end index to stop searching (exclusive)
+        :param end: end index to stop searching (exclusive).
         """
         results: OrderedDict[int, HistoryItem] = OrderedDict()
         for index in range(start, end):
@@ -359,7 +346,7 @@ class History(List[HistoryItem]):
         return results
 
     def to_json(self) -> str:
-        """Utility method to convert this History into a JSON string for use in persistent history files"""
+        """Convert this History into a JSON string for use in persistent history files."""
         json_dict = {
             History._history_version_field: History._history_version,
             History._history_items_field: [hi.to_dict() for hi in self],
@@ -368,8 +355,7 @@ class History(List[HistoryItem]):
 
     @staticmethod
     def from_json(history_json: str) -> 'History':
-        """
-        Utility method to restore History from a JSON string
+        """Restore History from a JSON string.
 
         :param history_json: history data as JSON string (generated using to_json())
         :return: History object

cmd2/parsing.py

@@ -1,20 +1,15 @@
-#
-# -*- coding: utf-8 -*-
-"""Statement parsing classes for cmd2"""
+"""Statement parsing classes for cmd2."""
 
 import re
 import shlex
+from collections.abc import Iterable
 from dataclasses import (
     dataclass,
     field,
 )
 from typing import (
     Any,
-    Dict,
-    Iterable,
-    List,
     Optional,
-    Tuple,
     Union,
 )
 
@@ -27,9 +22,11 @@ from .exceptions import (
 )
 
 
-def shlex_split(str_to_split: str) -> List[str]:
-    """
+def shlex_split(str_to_split: str) -> list[str]:
+    """Split the string *str_to_split* using shell-like syntax.
+
     A wrapper around shlex.split() that uses cmd2's preferred arguments.
+
     This allows other classes to easily call split() the same way StatementParser does.
 
     :param str_to_split: the string being split
@@ -40,10 +37,10 @@ def shlex_split(str_to_split: str) -> List[str]:
 
 @dataclass(frozen=True)
 class MacroArg:
-    """
-    Information used to replace or unescape arguments in a macro value when the macro is resolved
+    """Information used to replace or unescape arguments in a macro value when the macro is resolved.
+
     Normal argument syntax:    {5}
-    Escaped argument syntax:  {{5}}
+    Escaped argument syntax:  {{5}}.
     """
 
     # The starting index of this argument in the macro value
@@ -73,7 +70,7 @@ class MacroArg:
 
 @dataclass(frozen=True)
 class Macro:
-    """Defines a cmd2 macro"""
+    """Defines a cmd2 macro."""
 
     # Name of the macro
     name: str
@@ -85,11 +82,11 @@ class Macro:
     minimum_arg_count: int
 
     # Used to fill in argument placeholders in the macro
-    arg_list: List[MacroArg] = field(default_factory=list)
+    arg_list: list[MacroArg] = field(default_factory=list)
 
 
 @dataclass(frozen=True)
-class Statement(str):  # type: ignore[override]
+class Statement(str):  # type: ignore[override]  # noqa: SLOT000
     """String subclass with additional attributes to store the results of parsing.
 
     The ``cmd`` module in the standard library passes commands around as a
@@ -129,7 +126,7 @@ class Statement(str):  # type: ignore[override]
     command: str = ''
 
     # list of arguments to the command, not including any output redirection or terminators; quoted args remain quoted
-    arg_list: List[str] = field(default_factory=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 = ''
@@ -152,7 +149,7 @@ class Statement(str):  # type: ignore[override]
     # Used in JSON dictionaries
     _args_field = 'args'
 
-    def __new__(cls, value: object, *pos_args: Any, **kw_args: Any) -> 'Statement':
+    def __new__(cls, value: object, *_pos_args: Any, **_kw_args: Any) -> 'Statement':
         """Create a new instance of Statement.
 
         We must override __new__ because we are subclassing `str` which is
@@ -161,8 +158,7 @@ class Statement(str):  # type: ignore[override]
         NOTE:  @dataclass takes care of initializing other members in the __init__ it
         generates.
         """
-        stmt = super().__new__(cls, value)
-        return stmt
+        return super().__new__(cls, value)
 
     @property
     def command_and_args(self) -> str:
@@ -182,7 +178,7 @@ class Statement(str):  # type: ignore[override]
 
     @property
     def post_command(self) -> str:
-        """A string containing any ending terminator, suffix, and redirection chars"""
+        """A string containing any ending terminator, suffix, and redirection chars."""
         rtn = ''
         if self.terminator:
             rtn += self.terminator
@@ -202,12 +198,12 @@ class Statement(str):  # type: ignore[override]
 
     @property
     def expanded_command_line(self) -> str:
-        """Concatenate [command_and_args][cmd2.Statement.command_and_args] and [post_command][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
-    def argv(self) -> List[str]:
-        """a list of arguments a-la ``sys.argv``.
+    def argv(self) -> list[str]:
+        """A list of arguments a-la ``sys.argv``.
 
         The first element of the list is the command after shortcut and macro
         expansion. Subsequent elements of the list contain any additional
@@ -218,21 +214,19 @@ class Statement(str):  # type: ignore[override]
         """
         if self.command:
             rtn = [utils.strip_quotes(self.command)]
-            for cur_token in self.arg_list:
-                rtn.append(utils.strip_quotes(cur_token))
+            rtn.extend(utils.strip_quotes(cur_token) for cur_token in self.arg_list)
         else:
             rtn = []
 
         return rtn
 
-    def to_dict(self) -> Dict[str, Any]:
-        """Utility method to convert this Statement into a dictionary for use in persistent JSON history files"""
+    def to_dict(self) -> dict[str, Any]:
+        """Convert this Statement into a dictionary for use in persistent JSON history files."""
         return self.__dict__.copy()
 
     @staticmethod
-    def from_dict(source_dict: Dict[str, Any]) -> 'Statement':
-        """
-        Utility method to restore a Statement from a dictionary
+    def from_dict(source_dict: dict[str, Any]) -> 'Statement':
+        """Restore a Statement from a dictionary.
 
         :param source_dict: source data dictionary (generated using to_dict())
         :return: Statement object
@@ -242,7 +236,7 @@ class Statement(str):  # type: ignore[override]
         try:
             value = source_dict[Statement._args_field]
         except KeyError as ex:
-            raise KeyError(f"Statement dictionary is missing {ex} field")
+            raise KeyError(f"Statement dictionary is missing {ex} field") from None
 
         # Pass the rest at kwargs (minus args)
         kwargs = source_dict.copy()
@@ -258,8 +252,8 @@ class StatementParser:
         self,
         terminators: Optional[Iterable[str]] = None,
         multiline_commands: Optional[Iterable[str]] = None,
-        aliases: Optional[Dict[str, str]] = None,
-        shortcuts: Optional[Dict[str, str]] = None,
+        aliases: Optional[dict[str, str]] = None,
+        shortcuts: Optional[dict[str, str]] = None,
     ) -> None:
         """Initialize an instance of StatementParser.
 
@@ -271,13 +265,13 @@ class StatementParser:
         :param aliases: dictionary containing aliases
         :param shortcuts: dictionary containing shortcuts
         """
-        self.terminators: Tuple[str, ...]
+        self.terminators: tuple[str, ...]
         if terminators is None:
             self.terminators = (constants.MULTILINE_TERMINATOR,)
         else:
             self.terminators = tuple(terminators)
-        self.multiline_commands: Tuple[str, ...] = tuple(multiline_commands) if multiline_commands is not None else ()
-        self.aliases: Dict[str, str] = aliases if aliases is not None else {}
+        self.multiline_commands: tuple[str, ...] = tuple(multiline_commands) if multiline_commands is not None else ()
+        self.aliases: dict[str, str] = aliases if aliases is not None else {}
 
         if shortcuts is None:
             shortcuts = constants.DEFAULT_SHORTCUTS
@@ -318,7 +312,7 @@ class StatementParser:
         expr = rf'\A\s*(\S*?)({second_group})'
         self._command_pattern = re.compile(expr)
 
-    def is_valid_command(self, word: str, *, is_subcommand: bool = False) -> Tuple[bool, str]:
+    def is_valid_command(self, word: str, *, is_subcommand: bool = False) -> tuple[bool, str]:
         """Determine whether a word is a valid name for a command.
 
         Commands cannot include redirection characters, whitespace,
@@ -340,7 +334,7 @@ class StatementParser:
         valid = False
 
         if not isinstance(word, str):
-            return False, f'must be a string. Received {str(type(word))} instead'  # type: ignore[unreachable]
+            return False, f'must be a string. Received {type(word)!s} instead'  # type: ignore[unreachable]
 
         if not word:
             return False, 'cannot be an empty string'
@@ -363,22 +357,18 @@ class StatementParser:
         errmsg += ', '.join([shlex.quote(x) for x in errchars])
 
         match = self._command_pattern.search(word)
-        if match:
-            if word == match.group(1):
-                valid = True
-                errmsg = ''
+        if match and word == match.group(1):
+            valid = True
+            errmsg = ''
         return valid, errmsg
 
-    def tokenize(self, line: str) -> List[str]:
-        """
-        Lex a string into a list of tokens. Shortcuts and aliases are expanded and
-        comments are removed.
+    def tokenize(self, line: str) -> list[str]:
+        """Lex a string into a list of tokens. Shortcuts and aliases are expanded and comments are removed.
 
         :param line: the command line being lexed
         :return: A list of tokens
         :raises Cmd2ShlexError: if a shlex error occurs (e.g. No closing quotation)
         """
-
         # expand shortcuts and aliases
         line = self._expand(line)
 
@@ -390,23 +380,20 @@ class StatementParser:
         try:
             tokens = shlex_split(line)
         except ValueError as ex:
-            raise Cmd2ShlexError(ex)
+            raise Cmd2ShlexError(ex) from None
 
         # custom lexing
-        tokens = self.split_on_punctuation(tokens)
-        return tokens
+        return self.split_on_punctuation(tokens)
 
     def parse(self, line: str) -> Statement:
-        """
-        Tokenize the input and parse it into a [cmd2.parsing.Statement][] object,
-        stripping comments, expanding aliases and shortcuts, and extracting output
-        redirection directives.
+        """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 [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
         # we have to do this before we tokenize because tokenizing
         # destroys all unquoted whitespace in the input
@@ -522,13 +509,10 @@ class StatementParser:
                 arg_list = tokens[1:]
 
         # set multiline
-        if command in self.multiline_commands:
-            multiline_command = command
-        else:
-            multiline_command = ''
+        multiline_command = command if command in self.multiline_commands else ''
 
         # build the statement
-        statement = Statement(
+        return Statement(
             args,
             raw=line,
             command=command,
@@ -540,10 +524,9 @@ class StatementParser:
             output=output,
             output_to=output_to,
         )
-        return statement
 
     def parse_command_only(self, rawinput: str) -> Statement:
-        """Partially parse input into a [cmd2.Statement][] object.
+        """Parse input into a [cmd2.Statement][] object (partially).
 
         The command is identified, and shortcuts and aliases are expanded.
         Multiline commands are identified, but terminators and output
@@ -596,22 +579,17 @@ class StatementParser:
                 args = ''
 
         # set multiline
-        if command in self.multiline_commands:
-            multiline_command = command
-        else:
-            multiline_command = ''
+        multiline_command = command if command in self.multiline_commands else ''
 
         # build the statement
-        statement = Statement(args, raw=rawinput, command=command, multiline_command=multiline_command)
-        return statement
+        return Statement(args, raw=rawinput, command=command, multiline_command=multiline_command)
 
     def get_command_arg_list(
         self, command_name: str, to_parse: Union[Statement, str], preserve_quotes: bool
-    ) -> Tuple[Statement, List[str]]:
-        """
-        Convenience method used by the argument parsing decorators.
+    ) -> tuple[Statement, list[str]]:
+        """Retrieve just the arguments being passed to their ``do_*`` methods as a list.
 
-        Retrieves just the arguments being passed to their ``do_*`` methods as a list.
+        Convenience method used by the argument parsing decorators.
 
         :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:
@@ -636,12 +614,10 @@ class StatementParser:
 
         if preserve_quotes:
             return to_parse, to_parse.arg_list
-        else:
-            return to_parse, to_parse.argv[1:]
+        return to_parse, to_parse.argv[1:]
 
     def _expand(self, line: str) -> str:
-        """Expand aliases and shortcuts"""
-
+        """Expand aliases and shortcuts."""
         # Make a copy of aliases so we can keep track of what aliases have been resolved to avoid an infinite loop
         remaining_aliases = list(self.aliases.keys())
         keep_expanding = bool(remaining_aliases)
@@ -667,19 +643,18 @@ class StatementParser:
             if line.startswith(shortcut):
                 # If the next character after the shortcut isn't a space, then insert one
                 shortcut_len = len(shortcut)
+                effective_expansion = expansion
                 if len(line) == shortcut_len or line[shortcut_len] != ' ':
-                    expansion += ' '
+                    effective_expansion += ' '
 
                 # Expand the shortcut
-                line = line.replace(shortcut, expansion, 1)
+                line = line.replace(shortcut, effective_expansion, 1)
                 break
         return line
 
     @staticmethod
-    def _command_and_args(tokens: List[str]) -> Tuple[str, str]:
-        """Given a list of tokens, return a tuple of the command
-        and the args as a string.
-        """
+    def _command_and_args(tokens: list[str]) -> tuple[str, str]:
+        """Given a list of tokens, return a tuple of the command and the args as a string."""
         command = ''
         args = ''
 
@@ -691,7 +666,7 @@ class StatementParser:
 
         return command, args
 
-    def split_on_punctuation(self, tokens: List[str]) -> List[str]:
+    def split_on_punctuation(self, tokens: list[str]) -> list[str]:
         """Further splits tokens from a command line using punctuation characters.
 
         Punctuation characters are treated as word breaks when they are in
@@ -701,7 +676,7 @@ class StatementParser:
         :param tokens: the tokens as parsed by shlex
         :return: a new list of tokens, further split using punctuation
         """
-        punctuation: List[str] = []
+        punctuation: list[str] = []
         punctuation.extend(self.terminators)
         punctuation.extend(constants.REDIRECTION_CHARS)
 

cmd2/plugin.py

@@ -1,13 +1,9 @@
-#
-# coding=utf-8
-"""Classes for the cmd2 plugin system"""
+"""Classes for the cmd2 plugin system."""
 
 from dataclasses import (
     dataclass,
 )
-from typing import (
-    Optional,
-)
+from typing import Optional
 
 from .parsing import (
     Statement,
@@ -16,7 +12,7 @@ from .parsing import (
 
 @dataclass
 class PostparsingData:
-    """Data class containing information passed to postparsing hook methods"""
+    """Data class containing information passed to postparsing hook methods."""
 
     stop: bool
     statement: Statement
@@ -24,14 +20,14 @@ class PostparsingData:
 
 @dataclass
 class PrecommandData:
-    """Data class containing information passed to precommand hook methods"""
+    """Data class containing information passed to precommand hook methods."""
 
     statement: Statement
 
 
 @dataclass
 class PostcommandData:
-    """Data class containing information passed to postcommand hook methods"""
+    """Data class containing information passed to postcommand hook methods."""
 
     stop: bool
     statement: Statement
@@ -39,7 +35,7 @@ class PostcommandData:
 
 @dataclass
 class CommandFinalizationData:
-    """Data class containing information passed to command finalization hook methods"""
+    """Data class containing information passed to command finalization hook methods."""
 
     stop: bool
     statement: Optional[Statement]