Source code for traits.trait_list_object
# (C) Copyright 2005-2025 Enthought, Inc., Austin, TX
# All rights reserved.
#
# This software is provided without warranty under the terms of the BSD
# license included in LICENSE.txt and may be redistributed only under
# the conditions described in the aforementioned license. The license
# is also available online at http://www.enthought.com/licenses/BSD.txt
#
# Thanks for using Enthought open source!
import copy
import operator
from weakref import ref
from traits.observation.i_observable import IObservable
from traits.trait_base import class_of, Undefined, _validate_everything
from traits.trait_errors import TraitError
[docs]
class TraitListEvent(object):
""" An object reporting in-place changes to a trait list.
Parameters
----------
index : int or slice, optional
An index or slice indicating the location of the changes to the trait
list. The default is 0.
added : list, optional
The list of values added to the trait list.
removed : list, optional
The list of values removed from the list.
Attributes
----------
index : int or slice
An index or slice indicating the location of the changes to the list.
added : list
The list of values added to the list. If nothing was added this is
an empty list.
removed : list
The list of values removed from the list. If nothing was removed
this is an empty list.
"""
def __init__(self, *, index=0, removed=None, added=None):
self.index = index
if removed is None:
removed = []
self.removed = removed
if added is None:
added = []
self.added = added
def __repr__(self):
return (
f"{self.__class__.__name__}("
f"index={self.index!r}, "
f"removed={self.removed!r}, "
f"added={self.added!r})"
)
def _normalize_slice_or_index(index, length):
""" Normalize a slice or index for use with __delitem__ or __setitem__.
For slices with positive step, returns a slice that's equivalent for the
purposes of __delitem__ and __setitem__ operations. For slices with
negative step, a normalized slice representing the reverse of the given
slice is returned: note that in this case, the matching *added* and
*removed* lists will need to be reversed.
Slices with a step of 1 or -1 are normalized to a single integer index,
referring to the position of the first element referenced by the slice.
Similarly, slices that refer to only a single element of the corresponding
list (for example, a slice of `[1::10]` applied to a list of length 5)
are normalized to the index that refers to that same element.
Empty slices are also normalized to a single index. Note that in the case
of an empty slice, the corresponding __delitem__ or __setitem__ operation
does not cause any list change, so does not issue a notification. So the
normalized index in this case is unused in current code.
A normalized slice will have 0 <= start < stop <= length and a step >= 2.
It should further satisfy start + step < stop. The stop will always be
one larger than the last element referenced by the slice.
For a plain integer index, it's assumed -length <= index < length on input
(but this is not explicitly checked). A normalized output index will
satisfy 0 <= index <= length.
Parameters
----------
index : slice or integer
The slice to normalize
length : int
The length of the list to which the slice will be applied.
Returns
-------
reversed : bool
True if the returned slice is in the opposite direction to the
original, else False.
normalized_index : slice or integer
An equivalent (or reversed equivalent) normalized slice or index.
"""
if not isinstance(index, slice):
index = operator.index(index)
return False, index + length if index < 0 else index
start, stop, step = index.indices(length)
reversed = step < 0
if reversed:
start, stop, step = (
min(stop - step + (start - stop) % step, length),
start + 1,
-step,
)
# Reduce stop so that equivalent slices give identical normalized
# slices (e.g., del x[3:7:2] is equivalent to del x[3:6:2]).
stop -= (stop - start - 1) % step
# For a step of 1, a single item, or an empty slice, return a simple index.
if step == 1 or stop - start <= step:
return reversed, start
else:
return reversed, slice(start, stop, step)
def _removed_items(items, index, return_for_invalid_index):
"""
Return removed items for a given list and index, suppressing IndexError.
This is used by the __setitem__ and __delitem__ implementations to
get the "removed" part of the event.
Note that this deliberately suppresses any IndexError arising from
an out-of-range integer index. A suitable IndexError will be re-raised
when the actual __delitem__ or __setitem__ operation is performed.
Parameters
----------
items : list
The list being operated on.
index : integer or slice
Index of items to remove or replace.
return_for_invalid_index : any
Object to return for an invalid index.
Returns
-------
removed_items : list
List containing the removed items.
"""
if isinstance(index, slice):
return items[index]
else:
try:
return [items[index]]
except IndexError:
return return_for_invalid_index
[docs]
@IObservable.register
class TraitList(list):
""" A subclass of list that validates and notifies listeners of changes.
Parameters
----------
value : iterable
Iterable providing the items for the list
item_validator : callable, optional
Called to validate and/or transform items added to the list. The
callable should accept a single item from the list and return
the transformed item, raising TraitError for invalid items. If
not given, no item validation is performed.
notifiers : list of callable, optional
A list of callables with the signature::
notifier(trait_list, index, removed, added)
If this argument is not given, the list of notifiers is initially
empty.
Attributes
----------
item_validator : callable
Called to validate and/or transform items added to the list. The
callable should accept a single item from the list and return
the transformed item, raising TraitError for invalid items.
notifiers : list of callable
A list of callables with the signature::
notifier(trait_list, index, removed, added)
"""
def __new__(cls, *args, **kwargs):
# We need a __new__ in addition to __init__ in order to properly
# support unpickling: the 'append' or 'extend' methods may be
# called during unpickling, triggering item validation.
self = super().__new__(cls)
self.item_validator = _validate_everything
self.notifiers = []
return self
def __init__(self, iterable=(), *, item_validator=None, notifiers=None):
if item_validator is not None:
self.item_validator = item_validator
super().__init__(self.item_validator(item) for item in iterable)
if notifiers is not None:
self.notifiers = list(notifiers)
[docs]
def notify(self, index, removed, added):
""" Call all notifiers.
This simply calls all notifiers provided by the class, if any.
The notifiers are expected to have the signature::
notifier(trait_list, index, removed, added)
Any return values are ignored.
Parameters
----------
index : int or slice
The indices being modified by the operation.
removed : list
The items to be removed.
added : list
The items being added to the list.
"""
for notifier in self.notifiers:
notifier(self, index, removed, added)
# -- list interface -------------------------------------------------------
def __delitem__(self, key):
""" Delete self[key].
Parameters
----------
key : integer or slice
Index of the element(s) to be deleted.
Raises
------
IndexError
If key is an integer index and is out of range.
"""
original_length = len(self)
removed = _removed_items(self, key, return_for_invalid_index=None)
super().__delitem__(key)
if removed:
reversed, normalized_key = _normalize_slice_or_index(
key, original_length)
if reversed:
removed = removed[::-1]
self.notify(normalized_key, removed, [])
def __iadd__(self, value):
""" Implement self += value.
Parameters
----------
value : iterable
The items to be added.
Returns
-------
self : TraitList
The modified list.
"""
original_length = len(self)
added = [self.item_validator(item) for item in value]
extended = super().__iadd__(added)
if added:
self.notify(original_length, [], added)
return extended
def __imul__(self, value):
""" Implement self *= value.
Parameters
----------
value : integer
The multiplier.
Returns
-------
self : TraitList
The modified list.
"""
if value < 1:
removed = self.copy()
multiplied = super().__imul__(value)
if removed:
self.notify(0, removed, [])
else:
original_length = len(self)
multiplied = super().__imul__(value)
added = self[original_length:]
if added:
self.notify(original_length, [], added)
return multiplied
def __setitem__(self, key, value):
""" Set self[key] to value.
Parameters
----------
key : integer or slice
Index of the element(s) to be replaced.
value : iterable
Replacement values.
Raises
------
IndexError
If key is an integer index and is out of range.
ValueError
If key is an extended slice (that is, it's a slice whose step
is not 1 and not None) and the number of replacement elements
doesn't match the number of removed elements.
"""
original_length = len(self)
removed = _removed_items(self, key, return_for_invalid_index=None)
if isinstance(key, slice):
value = [self.item_validator(item) for item in value]
added = value
else:
value = self.item_validator(value)
added = [value]
super().__setitem__(key, value)
if added or removed:
reversed, normalized_key = _normalize_slice_or_index(
key, original_length)
if reversed:
added = added[::-1]
removed = removed[::-1]
self.notify(normalized_key, removed, added)
[docs]
def append(self, object):
""" Append object to the end of the list.
Parameters
----------
object : any
The object to append.
"""
original_length = len(self)
super().append(self.item_validator(object))
self.notify(original_length, [], self[original_length:])
[docs]
def clear(self):
""" Remove all items from list. """
removed = self.copy()
super().clear()
if removed:
self.notify(0, removed, [])
[docs]
def extend(self, iterable):
""" Extend list by appending elements from the iterable.
Parameters
----------
iterable : iterable
The elements to append.
"""
original_length = len(self)
added = [self.item_validator(item) for item in iterable]
super().extend(added)
if added:
self.notify(original_length, [], added)
[docs]
def insert(self, index, object):
""" Insert object before index.
Parameters
----------
index : integer
The position at which to insert.
object : object
The object to insert.
"""
# For insert, *any* index is valid!
if index < 0:
normalized_index = max(index + len(self), 0)
else:
normalized_index = min(index, len(self))
object = self.item_validator(object)
super().insert(index, object)
self.notify(normalized_index, [], [object])
[docs]
def pop(self, index=-1):
""" Remove and return item at index (default last).
Parameters
----------
index : int, optional
Index at which to remove item. If not given, the
last item of the list is removed.
Returns
-------
item : object
The removed item.
Raises
------
IndexError
If list is empty or index is out of range.
"""
# We don't need to worry about indices < -len(self) or >= len(self):
# for those, the pop call will raise anyway.
normalized_index = index + len(self) if index < 0 else index
item = super().pop(index)
self.notify(normalized_index, [item], [])
return item
[docs]
def remove(self, value):
""" Remove first occurrence of value.
Notes
-----
The value is not validated or converted before removal.
Parameters
----------
value : object
Value to be removed.
Raises
------
ValueError
If the value is not present.
"""
# Suppress ValueError. If the index call fails because the item is not
# in the list, remove should also fail, and we want to allow the remove
# error to propagate.
try:
index = self.index(value)
except ValueError:
pass
else:
removed = [self[index]]
super().remove(value)
self.notify(index, removed, [])
[docs]
def reverse(self):
""" Reverse the items in the list in place. """
removed = self.copy()
super().reverse()
if removed:
self.notify(0, removed, self.copy())
[docs]
def sort(self, *, key=None, reverse=False):
""" Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable
(i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort
them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
Parameters
----------
key : callable
Custom function that accepts a single item from the list and
returns the key to be used in comparisons.
reverse : bool
If true, the resulting list will be sorted in descending order.
"""
removed = self.copy()
super().sort(key=key, reverse=reverse)
if removed:
self.notify(0, removed, self.copy())
# -- pickle and copy support ----------------------------------------------
def __deepcopy__(self, memo):
""" Perform a deepcopy operation.
Notifiers are transient and should not be copied.
"""
return type(self)(
[copy.deepcopy(x, memo) for x in self],
item_validator=copy.deepcopy(self.item_validator, memo),
)
def __getstate__(self):
""" Get the state of the object for serialization.
Notifiers are transient and should not be serialized.
"""
result = self.__dict__.copy()
result.pop("notifiers", None)
return result
def __setstate__(self, state):
""" Restore the state of the object after serialization.
Notifiers are transient and are restored to the empty list.
"""
state["notifiers"] = []
self.__dict__.update(state)
# -- Implement IObservable ------------------------------------------------
def _notifiers(self, force_create):
""" Return a list of callables where each callable is a notifier.
The list is expected to be mutated for contributing or removing
notifiers from the object.
Parameters
----------
force_create: boolean
It is added for compatibility with CTrait. Not used here.
"""
return self.notifiers
[docs]
class TraitListObject(TraitList):
""" A specialization of TraitList with a default validator and notifier
which provide bug-for-bug compatibility with the TraitListObject from
Traits versions before 6.0.
Parameters
----------
trait : CTrait
The trait that the list has been assigned to.
object : HasTraits
The object this list belongs to. Can also be None in cases where the
list has been disconnected from its HasTraits parent.
name : str
The name of the trait on the object.
value : iterable
The initial value of the list.
Attributes
----------
trait : CTrait
The trait that the list has been assigned to.
object : callable
A callable that when called with no arguments returns the HasTraits
object that this list belongs to, or None if there is no such object.
name : str
The name of the trait on the object.
value : iterable
The initial value of the list.
"""
def __init__(self, trait, object, name, value):
self.trait = trait
self.object = (lambda: None) if object is None else ref(object)
self.name = name
self.name_items = None
if trait.has_items:
self.name_items = name + "_items"
# Convert to an explicit list so that we can validate the length.
value = list(value)
self._validate_length(len(value))
super().__init__(
value,
item_validator=self._item_validator,
notifiers=[self.notifier],
)
[docs]
def notifier(self, trait_list, index, removed, added):
""" Converts and consolidates the parameters to a TraitListEvent and
then fires the event.
Parameters
----------
trait_list : list
The list
index : int or slice
Index or slice that was modified
removed : list
Values that were removed
added : list
Values that were added
"""
is_trait_none = self.trait is None
is_name_items_none = self.name_items is None
if not hasattr(self, "trait") or is_trait_none or is_name_items_none:
return
object = self.object()
if object is None:
return
if getattr(object, self.name) is not self:
# Workaround having this list inside another container which
# also uses the name_items trait for notification.
# See enthought/traits#25, enthought/traits#281
return
event = TraitListEvent(index=index, removed=removed, added=added)
items_event = self.trait.items_event()
object.trait_items_event(self.name_items, event, items_event)
# -- list interface -------------------------------------------------------
def __delitem__(self, key):
""" Delete self[key].
Parameters
----------
key : integer or slice
Index of the element(s) to be deleted.
Raises
------
IndexError
If key is an integer index and is out of range.
"""
removed_count = len(self[key]) if isinstance(key, slice) else 1
self._validate_length(max(len(self) - removed_count, 0))
super().__delitem__(key)
def __iadd__(self, value):
""" Implement self += value.
Parameters
----------
value : iterable
The items to be added.
Returns
-------
self : TraitList
The modified list.
"""
# Convert input to a concrete list for length-checking purposes.
value = list(value)
self._validate_length(len(self) + len(value))
return super().__iadd__(value)
def __imul__(self, value):
""" Implement self *= value.
Parameters
----------
value : integer
The multiplier.
Returns
-------
self : TraitList
The modified list.
"""
self._validate_length(max(0, len(self) * value))
return super().__imul__(value)
def __setitem__(self, key, value):
""" Set self[key] to value.
Parameters
----------
key : integer or slice
Index of the element(s) to be replaced.
value : iterable
Replacement values.
Raises
------
IndexError
If key is an integer index and is out of range.
ValueError
If key is an extended slice (that is, it's a slice whose step
is not 1 and not None) and the number of replacement elements
doesn't match the number of removed elements.
"""
if isinstance(key, slice):
value = list(value)
if key.step is None or key.step == 1:
self._validate_length(len(self) - len(self[key]) + len(value))
else:
# No length change possible, so no need to validate length. But
# for backwards compatibility we simulate Python's complaint
# about any length difference before validating items.
if len(value) != len(self[key]):
raise ValueError(
"attempt to assign sequence of size {} "
"to extended slice of size {}".format(
len(value), len(self[key])
)
)
super().__setitem__(key, value)
[docs]
def append(self, object):
""" Append object to the end of the list.
Parameters
----------
object : any
The object to append.
"""
self._validate_length(len(self) + 1)
super().append(object)
[docs]
def clear(self):
""" Remove all items from list. """
self._validate_length(0)
super().clear()
[docs]
def extend(self, iterable):
""" Extend list by appending elements from the iterable.
Parameters
----------
iterable : iterable
The elements to append.
"""
# Convert input to a concrete list for length-checking purposes.
items = list(iterable)
self._validate_length(len(self) + len(items))
super().extend(items)
[docs]
def insert(self, index, object):
""" Insert object before index.
Parameters
----------
index : integer
The position at which to insert.
object : object
The object to insert.
"""
self._validate_length(len(self) + 1)
super().insert(index, object)
[docs]
def pop(self, index=-1):
""" Remove and return item at index (default last).
Parameters
----------
index : int, optional
Index at which to remove item. If not given, the
last item of the list is removed.
Returns
-------
item : object
The removed item.
Raises
------
IndexError
If list is empty or index is out of range.
"""
self._validate_length(max(len(self) - 1, 0))
return super().pop(index)
[docs]
def remove(self, value):
""" Remove first occurrence of value.
Notes
-----
The value is not validated or converted before removal.
Parameters
----------
value : object
Value to be removed.
Raises
------
ValueError
If the value is not present.
"""
self._validate_length(max(len(self) - 1, 0))
super().remove(value)
# -- pickle and copy support ----------------------------------------------
def __deepcopy__(self, memo):
""" Perform a deepcopy operation.
Notifiers are transient and should not be copied.
"""
return TraitListObject(
self.trait,
None,
self.name,
[copy.deepcopy(x, memo) for x in self],
)
def __getstate__(self):
""" Get the state of the object for serialization.
Notifiers are transient and should not be serialized.
"""
result = super().__getstate__()
result.pop("object", None)
result.pop("trait", None)
return result
def __setstate__(self, state):
""" Restore the state of the object after serialization.
Notifiers are transient and are restored to the empty list.
"""
name = state.setdefault("name", "")
state["notifiers"] = [self.notifier]
object = state.pop("object", None)
if object is not None:
state["object"] = ref(object)
trait = self.object()._trait(name, 0)
if trait is not None:
state["trait"] = trait.handler
else:
state["object"] = lambda: None
state["trait"] = None
self.__dict__.update(state)
# -- private methods ------------------------------------------------------
def _item_validator(self, value):
"""
Validate an item that's being added to the list.
"""
object = self.object()
if object is None:
return value
trait_validator = self.trait.item_trait.validate
if trait_validator is None:
return value
try:
return trait_validator(object, self.name, value)
except TraitError as excp:
excp.set_prefix("Each element of the")
raise
def _validate_length(self, new_length):
"""
Validate the new length for a proposed operation.
Parameters
----------
new_length : int
New length of the list.
Raises
------
TraitError
If the proposed new length would violate the length constraints
of the list.
"""
trait = getattr(self, "trait", None)
if trait is None:
return
if not trait.minlen <= new_length <= trait.maxlen:
raise TraitError(
"The '%s' trait of %s instance must be %s, "
"but you attempted to change its length to %d %s."
% (
self.name,
class_of(self.object()),
self.trait.full_info(self.object(), self.name, Undefined),
new_length,
"element" if new_length == 1 else "elements",
)
)
