cmd2.history
cmd2.history
History management classes.
FIRST_HISTORY_INDEX
module-attribute
INVALID_HISTORY_RANGE
module-attribute
INVALID_HISTORY_RANGE = "History indices must be positive or negative integers, and may not be zero."
HistoryItem
dataclass
Class used to represent one command in the history list.
expanded
property
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
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:
|
script
|
True if formatting for a script (No item numbers)
TYPE:
|
expanded
|
True if expanded command line should be printed
TYPE:
|
verbose
|
True if expanded and raw should both appear when they are different
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
str
|
pretty print string version of a HistoryItem |
Source code in cmd2/history.py
to_dict
Convert this HistoryItem into a dictionary for use in persistent JSON history files.
from_dict
staticmethod
Restore a HistoryItem from a dictionary.
| PARAMETER | DESCRIPTION |
|---|---|
source_dict
|
source data dictionary (generated using to_dict())
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
HistoryItem
|
HistoryItem object |
| RAISES | DESCRIPTION |
|---|---|
KeyError
|
if source_dict is missing required elements |
Source code in cmd2/history.py
HistoryIndexError
Bases: IndexError
Raised when a history index is invalid or a bounded range selects no items.
HistoryFormatError
Bases: ValueError
Raised when a history range has invalid syntax or a zero endpoint.
History
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
session_start_index
property
writable
Index just past the last persisted entry.
Every entry from this index on belongs to the current session. Unless the list has been
reordered, every entry before it is persisted. Assigning n marks the first n entries
as persisted and the rest as current.
spanpattern
class-attribute
instance-attribute
spanpattern = re.compile(
"\\s*(?P<start>-?[0-9]+)?(?P<separator>:|\\.{2,})(?P<end>-?[0-9]+)?\\s*"
)
is_persisted
Return whether an entry was in the history when the current session started.
Membership belongs to the entry object rather than its position, so a persisted entry stays persisted when the list is reordered, filtered, or repeated, and new entries belong to the current session wherever they are placed. Equal commands from different sessions are separate entries. To record a persisted command again in the current session, append its statement.
| PARAMETER | DESCRIPTION |
|---|---|
item
|
the history entry to check
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the entry is from a previous session |
Source code in cmd2/history.py
start_session
append
append(new: HistoryItem) -> None
append(new: Statement) -> None
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:
|
Source code in cmd2/history.py
clear
get
Get item from the History list using 1-based indexing.
| PARAMETER | DESCRIPTION |
|---|---|
index
|
optional item to get
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
HistoryItem
|
a single cmd2.history.HistoryItem |
| RAISES | DESCRIPTION |
|---|---|
HistoryIndexError
|
if index is zero or outside the history |
Source code in cmd2/history.py
span
Return a slice of the History list.
| PARAMETER | DESCRIPTION |
|---|---|
span
|
string containing an index or a slice
TYPE:
|
include_persisted
|
if True, include persisted history for unbounded ranges. Ranges with either endpoint always use the full history.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[int, HistoryItem]
|
a dictionary of history items keyed by their 1-based index in ascending order,
or an empty dictionary if an unbounded range ( |
| RAISES | DESCRIPTION |
|---|---|
HistoryFormatError
|
if the range format is invalid or an index is zero |
HistoryIndexError
|
if the start is out of bounds or a bounded range selects no history items This method can accommodate input in any of these forms: 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:
|
Source code in cmd2/history.py
str_search
Find history items which contain a given string.
| PARAMETER | DESCRIPTION |
|---|---|
search
|
the string to search for
TYPE:
|
include_persisted
|
if True, then search full history including persisted history
TYPE:
|
| 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
regex_search
Find history items which match a given regular expression.
| PARAMETER | DESCRIPTION |
|---|---|
regex
|
the regular expression to search for.
TYPE:
|
include_persisted
|
if True, then search full history including persisted history
TYPE:
|
| 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
truncate
Truncate the length of the history, dropping the oldest items if necessary.
Retained items keep their session membership, so retained current-session items still appear in unbounded ranges and searches.
| PARAMETER | DESCRIPTION |
|---|---|
max_length
|
the maximum length of the history, if zero or negative, all history items will be deleted
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
nothing |
Source code in cmd2/history.py
to_json
Convert this History into a JSON string for use in persistent history files.
Source code in cmd2/history.py
from_json
staticmethod
Restore History from a JSON string.
| PARAMETER | DESCRIPTION |
|---|---|
history_json
|
history data as JSON string (generated using to_json())
TYPE:
|
| 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
single_line_format
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:
|
| RETURNS | DESCRIPTION |
|---|---|
str
|
formatted command line |