cmd2.history¶
Classes for storing the history of previously entered commands.
-
class
cmd2.history.
History
(seq: Iterable[cmd2.history.HistoryItem] = ())¶ A list of
HistoryItem
objects with additional methods for searching and managing the list.Cmd
instantiates this class into thehistory
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: Union[cmd2.parsing.Statement, cmd2.history.HistoryItem]) → 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.
-
static
from_json
(history_json: str) → cmd2.history.History¶ Utility method to restore History from a JSON string
Parameters: history_json – history data as JSON string (generated using to_json())
Returns: History object
Raises: - json.JSONDecodeError – if passed invalid JSON string
- KeyError – if JSON is missing required elements
- ValueError – if history version in JSON isn’t supported
-
get
(index: int) → cmd2.history.HistoryItem¶ Get item from the History list using 1-based indexing.
Parameters: index – optional item to get Returns: a single HistoryItem
-
regex_search
(regex: str, include_persisted: bool = False) → OrderedDict[int, 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 dictionary of history items keyed by their 1-based index in ascending order, or an empty dictionary if the regex was not matched
-
span
(span: str, include_persisted: bool = False) → OrderedDict[int, HistoryItem]¶ Return a 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 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 :-aDifferent 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.
-
str_search
(search: str, include_persisted: bool = False) → OrderedDict[int, HistoryItem]¶ 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 dictionary of history items keyed by their 1-based index in ascending order, or an empty dictionary if the string was not found
-
to_json
() → str¶ Utility method to convert this History into a JSON string for use in persistent history files
-
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: cmd2.parsing.Statement = None)¶ Class used to represent one command in the history list
-
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
-
static
from_dict
(source_dict: Dict[str, Any]) → cmd2.history.HistoryItem¶ Utility method to restore a HistoryItem from a dictionary
Parameters: source_dict – source data dictionary (generated using to_dict()) Returns: HistoryItem object Raises: KeyError – if source_dict is missing required elements
-
pr
(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
Parameters: - idx – The 1-based index of this item in the history list
- script – True if formatting for a script (No item numbers)
- expanded – True if expanded command line should be printed
- verbose – True if expanded and raw should both appear when they are different
Returns: pretty print string version of a HistoryItem
-
raw
¶ The raw input from the user for this item.
Proxy property for
self.statement.raw
-
to_dict
() → Dict[str, Any]¶ Utility method to convert this HistoryItem into a dictionary for use in persistent JSON history files
-