bagofstuff.history

Provides classes for handling different types of history.

NavigableHistory

NavigableHistory(
    history: Sequence[T] | None = None,
    max_length: int = 500,
)

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: Sequence[T] | None = None,
    max_length: int = 500,
)

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: Sequence[T] | None = None,
    max_length: int = 500,
)

Bases: Sequence[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	Sequence[T] | None	Set to the given history.	None
max_length	int	Optional maximum length for the history.	500

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) -> 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.

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.

backward

backward() -> bool

Go backward through the history.

Returns:

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

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.