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.