Class History

cmd2/history.py:134–372

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. See [History](../features/history.md) for in

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.

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

    # Used in JSON dictionaries
    _history_version = "4.0.0"
    _history_version_field = "history_version"
    _history_items_field = "history_items"

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

    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)

    def _zero_based_index(self, onebased: int | str) -> int:
        """Convert a one-based index to a zero-based index."""
        result = int(onebased)
        if result > 0:
            result -= 1
        return result

    @overload
    def append(self, new: HistoryItem) -> None: ...  # pragma: no cover

    @overload
    def append(self, new: Statement) -> None: ...  # pragma: no cover

    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)

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

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

        :param index: optional item to get