napari.utils.events.NestableEventedList#

class napari.utils.events.NestableEventedList(data: Iterable[_T] = (), *, basetype: type[_T] | Sequence[type[_T]] = (), lookup: dict[type[_L], Callable[[_T], _T | _L]] | None = None)[source]#

Bases: EventedList[_T]

Nestable Mutable Sequence that emits recursive events when altered.

NestableEventedList instances can be indexed with a tuple of int (e.g. mylist[0, 2, 1]) to retrieve nested child objects.

A key property of this class is that when new mutable sequences are added to the list, they are themselves converted to a NestableEventedList, and all of the EventEmitter objects in the child are connect to the parent object’s _reemit_child_event method (assuming the child has an attribute called events that is an instance of EmitterGroup). When _reemit_child_event receives an event from a child object, it remits the event, but changes any index keys in the event to a NestedIndex (a tuple of int) such that indices emitted by any given NestableEventedList are always relative to itself.

Parameters:

  • data (iterable, optional) – Elements to initialize the list with. by default None.

  • basetype (type or sequence of types, optional) – Type of the elements in the list.

  • lookup (dict of Type[L] : function(object) -> L) – Mapping between a type, and a function that converts items in the list to that type.

Events:

  • types used – Index = Union[int, Tuple[int, …]]

  • inserting (index (Index)) – emitted before an item is inserted at index

  • inserted (index (Index, value: T)) – emitted after value is inserted at index

  • removing (index (Index)) – emitted before an item is removed at index

  • removed (index (Index, value: T)) – emitted after value is removed at index

  • moving (index (Index, new_index: Index)) – emitted before an item is moved from index to new_index

  • moved (index (Index, new_index: Index, value: T)) – emitted after value is moved from index to new_index

  • changed (index (Index, old_value: T, value: T)) – emitted when item at index is changed from old_value to value

  • changed <OVERLOAD> (index (slice, old_value: list[_T], value: list[_T])) – emitted when slice at index is changed from old_value to value

  • reordered (value (self)) – emitted when the list is reordered (eg. moved/reversed).

Methods

append(value)

S.append(value) -- append value to the end of the sequence

clear()

copy()

Return a shallow copy of the list.

count(value)

extend(values)

S.extend(iterable) -- extend sequence by appending elements from the iterable

has_index(index)

Return true if index is valid for this nestable list.

index(value[, start, stop])

Return first index of value.

insert(index, value)

Insert object before index.

move(src_index[, dest_index])

Move a single item from src_index to dest_index.

move_multiple(sources[, dest_index])

Move a batch of sources indices, to a single destination.

pop([index])

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) -- remove first occurrence of value.

reverse()

Reverse list IN PLACE.

Attributes

Details

append(value)#

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S#
copy() → TypedMutableSequence[_T]#

Return a shallow copy of the list.

count(value) → integer -- return number of occurrences of value#
extend(values)#

S.extend(iterable) – extend sequence by appending elements from the iterable

has_index(index: int | tuple[int, ...]) → bool[source]#

Return true if index is valid for this nestable list.

index(value: _L, start: int = 0, stop: int | None = None) → int#

Return first index of value.

Parameters:

  • value (Any) – A value to lookup. If type(value) is in the lookups functions provided for this class, then values in the list will be searched using the corresponding lookup converter function.

  • start (int, optional) – The starting index to search, by default 0

  • stop (int, optional) – The ending index to search, by default None

Returns:

The index of the value

Return type:

int

Raises:

ValueError – If the value is not present

insert(index: int, value: _T) → None[source]#

Insert object before index.

move(src_index: int | tuple[int | slice, ...], dest_index: int | tuple[int | slice, ...] = (0,)) → bool[source]#

Move a single item from src_index to dest_index.

Parameters:

  • src_index (Union[int, NestedIndex]) – The index of the object to move

  • dest_index (Union[int, NestedIndex], optional) – The destination. Object will be inserted before dest_index., by default, will insert at the front of the root list.

Returns:

Whether the operation completed successfully

Return type:

bool

Raises:

ValueError – If the terminal source is a slice, or if the source is this root object

move_multiple(sources: Iterable[int | slice], dest_index: int = 0) → int#

Move a batch of sources indices, to a single destination.

Note, if dest_index is higher than any of the sources, then the resulting position of the moved objects after the move operation is complete will be lower than dest_index.

Parameters:

  • sources (Sequence[int or slice]) – A sequence of indices

  • dest_index (int, optional) – The destination index. All sources will be inserted before this index (in pre-move space), by default 0… which has the effect of “bringing to front” everything in sources, or acting as a “reorder” method if sources contains all indices.

Returns:

The number of successful move operations completed.

Return type:

int

Raises:

TypeError – If the destination index is a slice, or any of the source indices are not int or slice.

pop([index]) → item -- remove and return item at index (default last).#

Raise IndexError if list is empty or index is out of range.

remove(value)#

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse() → None#

Reverse list IN PLACE.