radioviz.models.item_store

Module for managing a store of identifiable items with event notifications.

This module provides the ItemStore class that allows storing identifiable items and notifying listeners about changes to the store. It also defines the StoreEvent enum to represent different types of events that can occur in the store.

Classes

IdentifiableItem(*args, **kwargs)	Protocol for identifiable items.
ItemStore()	A generic store for identifiable items with event notifications.
StoreEvent(*values)	Enumeration of possible store events.

class radioviz.models.item_store.IdentifiableItem(*args, **kwargs)

Bases: Protocol

Protocol for identifiable items.

Any item that implements this protocol must have an id attribute of type UUID.

id: UUID

Unique identifier of the item.

class radioviz.models.item_store.ItemStore

Bases: Sequence[T], Generic[T]

A generic store for identifiable items with event notifications.

This class manages a collection of items that implement the IdentifiableItem protocol. It supports adding, removing, and retrieving items, as well as notifying registered listeners about changes to the store through StoreEvent notifications.

Initialize an empty item store.

Creates a new instance with an empty list of items and no listeners.

_notify(event: StoreEvent, item_data: T | None, index: int) → None

Notify all registered listeners about a store event.

Parameters:

• event (StoreEvent) – The type of event that occurred.

• item_data (T | None) – The item data associated with the event, if applicable.

• index (int) – The index of the item in the store, if applicable.

add(item: T) → None

Add an item to the store.

Parameters:

item (T) – The item to add to the store.

add_listener(callback: Callable[[StoreEvent, T | None, int], None]) → None

Add a listener to receive store change notifications.

Parameters:

callback (Callable[[StoreEvent, T | None, int], None]) – A callable that will be invoked when store events occur. The callable should accept three parameters: (event: StoreEvent, item: T | None, index: int)

add_update_listener(callback: Callable[[T, int], None]) → None

Add a listener for update events with a guaranteed item.

Parameters:

callback (Callable[[T, int], None]) – A callable invoked on update events with (item, index).

all() → list[T]

Get all items in the store.

Returns:

A copy of the list of all items in the store.

Return type:

list[T]

get(index: int) → T | None

Safely retrieve an item from the store by index.

Parameters:

index (int) – The index of the item to retrieve.

Returns:

The item at the specified index, or None if index is out of range.

Return type:

T | None

get_by_id(item_id: UUID) → T

Retrieve an item from the store by its ID.

Parameters:

item_id (UUID) – The unique identifier of the item to retrieve.

Returns:

The item with the specified ID.

Return type:

T

index_of(item_id: UUID) → int

Find the index of an item by its ID.

Parameters:

item_id (UUID) – The unique identifier of the item to find.

Returns:

The index of the item in the store.

Return type:

int

Raises:

KeyError – if no item with the specified ID exists.

remove(index: int) → None

Remove an item from the store by index.

Parameters:

index (int) – The index of the item to remove.

Raises:

IndexError – if the index is out of range.

remove_item(item: T) → None

Remove an item from the store by reference.

Parameters:

item (T) – The item to remove from the store.

reset() → None

Clear all items from the store.

This method removes all items from the store and notifies listeners of the StoreEvent.CLEARED event.

class radioviz.models.item_store.StoreEvent(*values)

Bases: StrEnum

Enumeration of possible store events.

This enum defines the different types of events that can be triggered when items are added, removed, updated, or the store is cleared.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

ADDED = 'added'

Item was added to the store.

CLEARED = 'cleared'

Store was cleared of all items.

REMOVED = 'removed'

Item was removed from the store.

UPDATED = 'updated'

Item was updated in the store.