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

inherited-members:

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

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

Return true if index is valid for this nestable list.

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