bronx.stdtypes.history

Some types to manage history of commands, actions, etc.

Classes

class bronx.stdtypes.history.History(*args, **kw)

Bases: PrivateHistory, GetByTag

Shared Multi-purpose history like object.

It is managed by bronx.patterns.getbytag.GetByTag consequently a tag parameter needs to be added to the constructor.

Parameters:

• queue – Pre-existing history items

• maxlen – The maximum size of the history object (see the comment above)

• timer – Add a timestamp when showing history entries

class bronx.stdtypes.history.PrivateHistory(queue=(), maxlen=9999, timer=False)

Bases: object

Multi-purpose history like object.

Items added to an History object are recorded along with a number (starting from 1 and incremented each time an item is added) and a timestamp.

Available history items can be listed searched and printed.

Thanks to the maxlen parameter, the history object retains only a limited number of items (only the maxlen latest ones). This mechanism prevent from an excessive memory consumption.

Example:

# Initalise an History object that will retain at most 3 entries
# (if not specified, default for maxlen is 9999)
>>> hst = PrivateHistory(maxlen=3)
>>> hst.size
3

# Simply add four entries...
>>> hst.append("Entry 1") # doctest: +ELLIPSIS
(1, datetime.datetime(...))
>>> len(hst)
1
>>> hst.append("Entry 2") # doctest: +ELLIPSIS
(2, datetime.datetime(...))
>>> hst.append("Entry 3") # doctest: +ELLIPSIS
(3, datetime.datetime(...))
>>> hst.append("Entry 4", "as a tuple") # doctest: +ELLIPSIS
(4, datetime.datetime(...))

# This objects, auto-limits itself to self.size/maxlen
>>> len(hst)
3
>>> hst.lower_bound
2
>>> hst.upper_bound
4

# It is iterable and individual elements can be accessed
>>> list(hst) # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
[(2, datetime.datetime(...), (...'Entry 2',)),
 (3, datetime.datetime(...), (...'Entry 3',)),
 (4, datetime.datetime(...), (...'Entry 4', ...'as a tuple'))]
>>> hst[3] # doctest: +ELLIPSIS
(3, datetime.datetime(...), (...'Entry 3',))

# Simple searches are possible
>>> hst.grep('a tup') # doctest: +ELLIPSIS
[(4, datetime.datetime(...), (...'Entry 4', ...'as a tuple'))]
>>> hst.match(r'En\w+\s+[24]') # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
[(2, datetime.datetime(...), (...'Entry 2',)),
 (4, datetime.datetime(...), (...'Entry 4', ...'as a tuple'))]

# Formatted output are do-able
>>> hst.show()
[2] : Entry 2
[3] : Entry 3
[4] : Entry 4 as a tuple
>>> hst.show(2, 3)
[2] : Entry 2
[3] : Entry 3
>>> hst.showgrep('a tup')
[4] : Entry 4 as a tuple

# With the timestamp
>>> hst.timer = True
>>> hst.showlast() # doctest: +ELLIPSIS
[4][...] : Entry 4 as a tuple

Parameters:

• queue – Pre-existing history items

• maxlen – The maximum size of the history object (see the comment above)

• timer – Add a timestamp when showing history entries

append(*items)

Add the specified items as a new history entry.

around(focus=None, delta=60)

Display a numbered list of history items with a stamp value contained in the exclusive interval [focus - delta, focus + delta].

property count

The current value of the history entry counter.

get(start=1, end=None)

Extract history entries with a count value contained in the inclusive interval start - end.

getaround(focus, delta=60)

Extract history entries with a stamp value contained in the exclusive interval [focus - delta, focus + delta].

getbynumber(num)

Get an history entry knowing its internal number.

grep(key)

Lookup for key in the string representation of history items.

property last

Return the last history entry.

property lower_bound

The number of oldest history entry retained in the object

match(regex)

Match the regex in the string representation of history items.

merge(*others)

Merge current history with other history objects.

nice(item)

Try to build some nice string of the item.

reset()

Clear the current history.

resize(maxlen=None)

Resize the internal history log to the specified length.

show(start=1, end=None)

Display a numbered list of history items with a count value contained in the inclusive interval start - end.

showgrep(key)

Display a selection of history items containing the key.

showlast()

Display the last entry of the current history.

showmatch(regex)

Display a selection of history items matching argument regex.

property size

The maximum number of entries retained in the preent object.

stamp()

Return a time stamp.

property timer

Add a timestamp when showing history entries.

property upper_bound

The number of latest history entry in the object