cmd2.history

Classes for storing the history of previously entered commands.

class cmd2.history.History(seq=())

A list of HistoryItem objects with additional methods for searching and managing the list.

Cmd instantiates this class into the 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.

append(new: cmd2.parsing.Statement) → None

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

Parameters:new – Statement object which will be composed into a HistoryItem and added to the end of the list
clear() → None

Remove all items from the History list.

get(index: Union[int, str]) → cmd2.history.HistoryItem

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

Parameters:index – optional item to get (index as either integer or string)
Returns:a single HistoryItem

Find history items which match a given regular expression

Parameters:
  • regex – the regular expression to search for.
  • include_persisted – if True, then search full history including persisted history
Returns:

a list of history items, or an empty list if the string was not found

span(span: str, include_persisted: bool = False) → List[cmd2.history.HistoryItem]

Return an index or slice of the History list,

Parameters:
  • span – string containing an index or a slice
  • include_persisted – if True, then retrieve full results including from persisted history
Returns:

a list of HistoryItems

This method can accommodate input in any of these forms:

a -a 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
start_session() → None

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

Find history items which contain a given string

Parameters:
  • search – the string to search for
  • include_persisted – if True, then search full history including persisted history
Returns:

a list of history items, or an empty list if the string was not found

truncate(max_length: int) → None

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

Parameters:max_length – the maximum length of the history, if negative, all history items will be deleted
Returns:nothing
class cmd2.history.HistoryItem(statement=None, idx=None)

Class used to represent one command in the history list

statement

The Statement object parsed from user input

idx

The 1-based index of this statement in the history list

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(script=False, expanded=False, verbose=False) → str

Represent this item in a pretty fashion suitable for printing.

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

Returns:pretty print string version of a HistoryItem
raw

The raw input from the user for this item.

Proxy property for self.statement.raw