Skip to content

# cmd2.history

## `` cmd2.history

History management classes.

### `` HistoryItem `dataclass`

    HistoryItem(statement)

Class used to represent one command in the history list.

#### `` statement `instance-attribute`

    statement

#### `` raw `property`

    raw

The raw input from the user for this item.

Proxy property for `self.statement.raw`

#### `` expanded `property`

    expanded

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`

#### `` pr

    pr(idx, script=False, expanded=False, verbose=False)

Represent this item in a pretty fashion suitable for printing.

If you pass verbose=True, script and expanded will be ignored

PARAMETER | DESCRIPTION
--- | ---
`idx` | The 1-based index of this item in the history list TYPE: `int`
`script` | True if formatting for a script (No item numbers) TYPE: `bool` DEFAULT: `False`
`expanded` | True if expanded command line should be printed TYPE: `bool` DEFAULT: `False`
`verbose` | True if expanded and raw should both appear when they are different TYPE: `bool` DEFAULT: `False`

RETURNS | DESCRIPTION
--- | ---
`str` | pretty print string version of a HistoryItem

Source code in `cmd2/history.py`

     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116

    def pr(self, idx: int, script: bool = False, expanded: bool = False, verbose: bool = False) -> str:
        """Represent this item in a pretty fashion suitable for printing.

        If you pass verbose=True, script and expanded will be ignored

        :param idx: The 1-based index of this item in the history list
        :param script: True if formatting for a script (No item numbers)
        :param expanded: True if expanded command line should be printed
        :param verbose: True if expanded and raw should both appear when they are different
        :return: pretty print string version of a HistoryItem
        """
        if verbose:
            raw = self.raw.rstrip()
            expanded_command = self.expanded

            ret_str = self._listformat.format(idx, raw)
            if raw != expanded_command:
                ret_str += "\n" + self._ex_listformat.format(idx, expanded_command)
        else:
            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:
                ret_str = self._listformat.format(idx, ret_str)

        return ret_str

#### `` to_dict

    to_dict()

Convert this HistoryItem into a dictionary for use in persistent JSON history files.

Source code in `cmd2/history.py`

    118
    119
    120

    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()}

#### `` from_dict `staticmethod`

    from_dict(source_dict)

Restore a HistoryItem from a dictionary.

PARAMETER | DESCRIPTION
--- | ---
`source_dict` | source data dictionary (generated using to_dict()) TYPE: `dict[str, Any]`

RETURNS | DESCRIPTION
--- | ---
`HistoryItem` | HistoryItem object

RAISES | DESCRIPTION
--- | ---
`KeyError` | if source_dict is missing required elements

Source code in `cmd2/history.py`

    122
    123
    124
    125
    126
    127
    128
    129
    130
    131

    @staticmethod
    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
        :raises KeyError: if source_dict is missing required elements
        """
        statement_dict = source_dict[HistoryItem._statement_field]
        return HistoryItem(Statement.from_dict(statement_dict))

### `` History

    History(seq=())

Bases: `list[HistoryItem]`

A list of 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.

See History 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 class to gain access to the historical record.

Initialize History instances.

Source code in `cmd2/history.py`

    152
    153
    154
    155

    def __init__(self, seq: Iterable[HistoryItem] = ()) -> None:
        """Initialize History instances."""
        super().__init__(seq)
        self.session_start_index = 0

#### `` session_start_index `instance-attribute`

    session_start_index = 0

#### `` spanpattern `class-attribute` `instance-attribute`

    spanpattern = compile('^\\s*(?P<start>-?[1-9]\\d*)?(?P<separator>:|(\\.{2,}))(?P<end>-?[1-9]\\d*)?\\s*$')

#### `` start_session

    start_session()

Start a new session, thereby setting the next index as the first index in the new session.

Source code in `cmd2/history.py`

    157
    158
    159

    def start_session(self) -> None:
        """Start a new session, thereby setting the next index as the first index in the new session."""
        self.session_start_index = len(self)

#### `` append

    append(new: HistoryItem) -> None

    append(new: Statement) -> None

    append(new)

Append a new statement to the end of the History list.

PARAMETER | DESCRIPTION
--- | ---
`new` | Statement object which will be composed into a HistoryItem and added to the end of the list TYPE: `Statement | HistoryItem`

Source code in `cmd2/history.py`

    174
    175
    176
    177
    178
    179
    180
    181

    def append(self, new: Statement | HistoryItem) -> None:
        """Append a new statement to the end of the History list.

        :param new: Statement object which will be composed into a HistoryItem
                    and added to the end of the list
        """
        history_item = HistoryItem(new) if isinstance(new, Statement) else new
        super().append(history_item)

#### `` clear

    clear()

Remove all items from the History list.

Source code in `cmd2/history.py`

    183
    184
    185
    186

    def clear(self) -> None:
        """Remove all items from the History list."""
        super().clear()
        self.start_session()

#### `` get

    get(index)

Get item from the History list using 1-based indexing.

PARAMETER | DESCRIPTION
--- | ---
`index` | optional item to get TYPE: `int`

RETURNS | DESCRIPTION
--- | ---
`HistoryItem` | a single cmd2.history.HistoryItem

Source code in `cmd2/history.py`

    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198

    def get(self, index: int) -> HistoryItem:
        """Get item from the History list using 1-based indexing.

        :param index: optional item to get
        :return: a single [cmd2.history.HistoryItem][]
        """
        if index == 0:
            raise IndexError("The first command in history is command 1.")
        if index < 0:
            return self[index]
        return self[index - 1]

#### `` span

    span(span, include_persisted=False)

Return a slice of the History list.

PARAMETER | DESCRIPTION
--- | ---
`span` | string containing an index or a slice TYPE: `str`
`include_persisted` | if True, then retrieve full results including from persisted history TYPE: `bool` DEFAULT: `False`

RETURNS | DESCRIPTION
--- | ---

`dict[int, HistoryItem]`

a dictionary of history items keyed by their 1-based index in ascending order, or an empty dictionary if no results were found

This method can accommodate input in any of these forms:

    a..b or a:b
    a.. or a:
    ..a or :a
    -a.. or -a:
    ..-a or :-a

Different from native python indexing and slicing of arrays, this method uses 1-based array numbering. Users who are not programmers can't grok zero based numbering. Programmers can sometimes grok zero based numbering. Which reminds me, there are only two hard problems in programming:

- naming
- cache invalidation
- off by one errors

Source code in `cmd2/history.py`

    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    273

    def span(self, span: str, include_persisted: bool = False) -> dict[int, "HistoryItem"]:
        """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
        :return: a dictionary of history items keyed by their 1-based index in ascending order,
                 or an empty dictionary if no results were found

        This method can accommodate input in any of these forms:

            a..b or a:b
            a.. or a:
            ..a or :a
            -a.. or -a:
            ..-a or :-a

        Different from native python indexing and slicing of arrays, this method
        uses 1-based array numbering. Users who are not programmers can't grok
        zero based numbering. Programmers can sometimes grok zero based numbering.
        Which reminds me, there are only two hard problems in programming:

        - naming
        - cache invalidation
        - off by one errors

        """
        results = self.spanpattern.search(span)
        if not results:
            # our regex doesn't match the input, bail out
            raise ValueError("History indices must be positive or negative integers, and may not be zero.")

        start_token = results.group("start")
        if start_token:
            start = min(self._zero_based_index(start_token), len(self) - 1)
            if start < 0:
                start = max(0, len(self) + start)
        else:
            start = 0 if include_persisted else self.session_start_index

        end_token = results.group("end")
        if end_token:
            end = min(int(end_token), len(self))
            if end < 0:
                end = max(0, len(self) + end + 1)
        else:
            end = len(self)

        return self._build_result_dictionary(start, end)

#### `` str_search

    str_search(search, include_persisted=False)

Find history items which contain a given string.

PARAMETER | DESCRIPTION
--- | ---
`search` | the string to search for TYPE: `str`
`include_persisted` | if True, then search full history including persisted history TYPE: `bool` DEFAULT: `False`

RETURNS | DESCRIPTION
--- | ---
`dict[int, HistoryItem]` | a dictionary of history items keyed by their 1-based index in ascending order, or an empty dictionary if the string was not found

Source code in `cmd2/history.py`

    275
    276
    277
    278
    279
    280
    281
    282
    283
    284
    285
    286
    287
    288
    289
    290
    291
    292

    def str_search(self, search: str, include_persisted: bool = False) -> dict[int, "HistoryItem"]:
        """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
        :return: a dictionary of history items keyed by their 1-based index in ascending order,
                 or an empty dictionary if the string was not found
        """

        def isin(history_item: HistoryItem) -> bool:
            """Filter function for string search of history."""
            sloppy = su.norm_fold(search)
            inraw = sloppy in su.norm_fold(history_item.raw)
            inexpanded = sloppy in su.norm_fold(history_item.expanded)
            return inraw or inexpanded

        start = 0 if include_persisted else self.session_start_index
        return self._build_result_dictionary(start, len(self), isin)

#### `` regex_search

    regex_search(regex, include_persisted=False)

Find history items which match a given regular expression.

PARAMETER | DESCRIPTION
--- | ---
`regex` | the regular expression to search for. TYPE: `str`
`include_persisted` | if True, then search full history including persisted history TYPE: `bool` DEFAULT: `False`

RETURNS | DESCRIPTION
--- | ---
`dict[int, HistoryItem]` | a dictionary of history items keyed by their 1-based index in ascending order, or an empty dictionary if the regex was not matched

Source code in `cmd2/history.py`

    294
    295
    296
    297
    298
    299
    300
    301
    302
    303
    304
    305
    306
    307
    308
    309
    310
    311
    312

    def regex_search(self, regex: str, include_persisted: bool = False) -> dict[int, "HistoryItem"]:
        """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
        :return: a dictionary of history items keyed by their 1-based index in ascending order,
                 or an empty dictionary if the regex was not matched
        """
        regex = regex.strip()
        if regex.startswith(r"/") and regex.endswith(r"/"):
            regex = regex[1:-1]
        finder = re.compile(regex, re.DOTALL | re.MULTILINE)

        def isin(hi: HistoryItem) -> bool:
            """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)

#### `` truncate

    truncate(max_length)

Truncate the length of the history, dropping the oldest items if necessary.

PARAMETER | DESCRIPTION
--- | ---
`max_length` | the maximum length of the history, if negative, all history items will be deleted TYPE: `int`

RETURNS | DESCRIPTION
--- | ---
`None` | nothing

Source code in `cmd2/history.py`

    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326

    def truncate(self, max_length: int) -> None:
        """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
        :return: nothing
        """
        if max_length <= 0:
            # remove all history
            del self[:]
        elif len(self) > max_length:
            last_element = len(self) - max_length
            del self[0:last_element]

#### `` to_json

    to_json()

Convert this History into a JSON string for use in persistent history files.

Source code in `cmd2/history.py`

    342
    343
    344
    345
    346
    347
    348

    def to_json(self) -> str:
        """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],
        }
        return json.dumps(json_dict, ensure_ascii=False, indent=2)

#### `` from_json `staticmethod`

    from_json(history_json)

Restore History from a JSON string.

PARAMETER | DESCRIPTION
--- | ---
`history_json` | history data as JSON string (generated using to_json()) TYPE: `str`

RETURNS | DESCRIPTION
--- | ---
`History` | History object

RAISES | DESCRIPTION
--- | ---
`json.JSONDecodeError` | if passed invalid JSON string
`KeyError` | if JSON is missing required elements
`ValueError` | if history version in JSON isn't supported

Source code in `cmd2/history.py`

    350
    351
    352
    353
    354
    355
    356
    357
    358
    359
    360
    361
    362
    363
    364
    365
    366
    367
    368
    369
    370
    371
    372

    @staticmethod
    def from_json(history_json: str) -> "History":
        """Restore History from a JSON string.

        :param history_json: history data as JSON string (generated using to_json())
        :return: History object
        :raises json.JSONDecodeError: if passed invalid JSON string
        :raises KeyError: if JSON is missing required elements
        :raises ValueError: if history version in JSON isn't supported
        """
        json_dict = json.loads(history_json)
        version = json_dict[History._history_version_field]
        if version != History._history_version:
            raise ValueError(
                f"Unsupported history file version: {version}. This application uses version {History._history_version}."
            )

        items = json_dict[History._history_items_field]
        history = History()
        for hi_dict in items:
            history.append(HistoryItem.from_dict(hi_dict))

        return history

### `` single_line_format

    single_line_format(statement)

Format a command line to display on a single line.

Spaces and newlines in quotes are preserved so those strings will span multiple lines.

PARAMETER | DESCRIPTION
--- | ---
`statement` | Statement being formatted. TYPE: `Statement`

RETURNS | DESCRIPTION
--- | ---
`str` | formatted command line

Source code in `cmd2/history.py`

    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56

    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