bagofstuff.history

Provides classes for handling different types of history.

NavigableHistory

NavigableHistory(
    history: Iterable[T] | None = None,
    max_length: int = _DEFAULT_MAX_LENGTH,
)

Bases: SimpleHistory[T]

A history class that implements a linear navigation history.

When adding an item to the history, everything after the current location is removed from the history, and the new item is placed at the end.

add

add(item: T) -> Self

Add an item to the history.

Parameters:

Name	Type	Description	Default
item	T	The item to add.	required

Returns:

Type	Description
Self	Self.

Note

When adding an item to the history, everything after the current location is removed from the history, and the new item is placed at the end.

RecencyHistory

RecencyHistory(
    history: Iterable[T] | None = None,
    max_length: int = _DEFAULT_MAX_LENGTH,
)

Bases: SimpleHistory[T]

A history that keeps track of the most recent items.

The history attempts to stay unique, so if an item is added that already exists in the history, it is moved to the end of the history. Already existing is defined by an item that has equality to an item that already exists in the history.

add

add(item: T) -> Self

Add an item to the history.

Parameters:

Name	Type	Description	Default
item	T	The item to add.	required

Returns:

Type	Description
Self	Self.

Note

When adding an item to the history, if the item already exists in the history, it is removed and added to the end of the history.

SimpleHistory

SimpleHistory(
    history: Iterable[T] | None = None,
    max_length: int = _DEFAULT_MAX_LENGTH,
)

Bases: MutableSequence[T]

A history class that implements a simple linear history.

Adding items to the list simple grows the list until the maximum length is reached, at which point the oldest items are removed.

Parameters:

Name	Type	Description	Default
history	Iterable[T] | None	Optional starting point for the history.	None
max_length	int	Optional maximum length for the history.	_DEFAULT_MAX_LENGTH

can_go_backward property

can_go_backward: bool

Can history go backward?

can_go_forward property

can_go_forward: bool

Can history go forward?

current_item property

current_item: T | None

The current item in the history.

If there is no current item in the history the value is None.

current_location property

current_location: int | None

The current integer location in the history.

If there is no valid location the value is None.

__bool__

__bool__() -> bool

Test if the history is empty.

__contains__

__contains__(value: object) -> bool

Test if the given item is in the history.

__delitem__

__delitem__(index: int | slice[int | None]) -> None

Delete an item from the history.

__getitem__

__getitem__(index: int) -> T

__getitem__(index: slice) -> list[T]

__getitem__(index: int | slice) -> T | list[T]

Get an item from the history.

__iter__

__iter__() -> Iterator[T]

Support iterating through the history.

__len__

__len__() -> int

The length of the history.

__reversed__

__reversed__() -> Iterator[T]

Return a reversed list of the contents of the history.

__setitem__

__setitem__(index: int, value: T) -> None

__setitem__(
    index: slice[int | None], value: Iterable[T]
) -> None

__setitem__(
    index: int | slice[int | None],
    value: T | Iterable[T],
) -> None

Set an item in the history.

add

add(item: T) -> Self

Add an item to the history.

Parameters:

Name	Type	Description	Default
item	T	The item to add.	required

Returns:

Type	Description
Self	Self.

Note

When adding an item to the history, everything after the current location is removed from the history, and the new item is placed at the end.

add_or_replace

add_or_replace(item: T) -> Self

Add an item to the history, or replace the current item.

Parameters:

Name	Type	Description	Default
item	T	The item to add or replace.	required

Returns:

Type	Description
Self	Self.

Note

If we have no current item, or the current item's equality test with the new item fails, we add the new item to the history. Otherwise, we replace the current item with the new item.

This method is especially useful when working with values whose equality test is not based on some primary property.

backward

backward() -> bool

Go backward through the history.

Returns:

Type	Description
bool	True if we moved through history, False if not.

clear

clear() -> None

Clear the history.

clone

clone() -> Self

Clone the history.

Returns:

Type	Description
Self	A clone of the history.

Note

The clone is a new instance of the history with the same items and current location.

count

count(item: T) -> int

Return the number of occurrences of the given value in the history.

Parameters:

Name	Type	Description	Default
item	T	The value to count in the history.	required

Returns:

Type	Description
int	The number of occurrences of the value in the history.

forward

forward() -> bool

Go forward through the history.

Returns:

Type	Description
bool	True if we moved through history, False if not.

goto

goto(location: int) -> Self

Jump to a specific location within history.

goto_end

goto_end() -> Self

Go to the end of the history.

index

index(
    item: T, start: int = 0, stop: int = maxsize
) -> int

Return the index of the given history item.

Parameters:

Name	Type	Description	Default
item	T	The item to find in the history.	required
start	int	Optional start location.	0
stop	int	Optional stop location.	maxsize

Returns:

Type	Description
int	The index of the item in the history.

Raises:

Type	Description
ValueError	If the item is not in the history.

insert

insert(index: int, item: T) -> None

Insert an item into the history.

Parameters:

Name	Type	Description	Default
index	int	The index to insert the item at.	required
item	T	The item to insert.	required

Note

This method is not supported for this history class.

truncate

truncate() -> Self

Truncate the history at the current location.

Returns:

Type	Description
Self	Self.