IPython/utils/eventful.py

"""Contains eventful dict and list implementations."""

# void function used as a callback placeholder.
def _void(*p, **k): return None

class EventfulDict(dict):
    """Eventful dictionary.

    This class inherits from the Python intrinsic dictionary class, dict.  It
    adds events to the get, set, and del actions and optionally allows you to
    intercept and cancel these actions.  The eventfulness isn't recursive.  In
    other words, if you add a dict as a child, the events of that dict won't be
    listened to.  If you find you need something recursive, listen to the `add`
    and `set` methods, and then cancel `dict` values from being set, and instead
    set EventfulDicts that wrap those dicts.  Then you can wire the events
    to the same handlers if necessary.

    See the on_events, on_add, on_set, and on_del methods for registering 
    event handlers."""

    def __init__(self, *args, **kwargs):
        """Public constructor"""
        self._add_callback = _void
        self._del_callback = _void
        self._set_callback = _void
        dict.__init__(self, *args, **kwargs)

    def on_events(self, add_callback=None, set_callback=None, del_callback=None):
        """Register callbacks for add, set, and del actions.

        See the doctstrings for on_(add/set/del) for details about each 
        callback.

        add_callback: [callback = None]
        set_callback: [callback = None]
        del_callback: [callback = None]"""
        self.on_add(add_callback)
        self.on_set(set_callback)
        self.on_del(del_callback)

    def on_add(self, callback):
        """Register a callback for when an item is added to the dict.

        Allows the listener to detect when items are added to the dictionary and
        optionally cancel the addition.

        callback: callable or None
            If you want to ignore the addition event, pass None as the callback.
            The callback should have a signature of callback(key, value).  The
            callback should return a boolean True if the additon should be
            canceled, False or None otherwise."""
        self._add_callback = callback if callable(callback) else _void

    def on_del(self, callback):
        """Register a callback for when an item is deleted from the dict.

        Allows the listener to detect when items are deleted from the dictionary
        and optionally cancel the deletion.

        callback: callable or None
            If you want to ignore the deletion event, pass None as the callback.
            The callback should have a signature of callback(key).  The
            callback should return a boolean True if the deletion should be
            canceled, False or None otherwise."""
        self._del_callback = callback if callable(callback) else _void
        
    def on_set(self, callback):
        """Register a callback for when an item is changed in the dict.

        Allows the listener to detect when items are changed in the dictionary
        and optionally cancel the change.

        callback: callable or None
            If you want to ignore the change event, pass None as the callback.
            The callback should have a signature of callback(key, value).  The
            callback should return a boolean True if the change should be
            canceled, False or None otherwise."""
        self._set_callback = callback if callable(callback) else _void
        
    def pop(self, key):
        """Returns the value of an item in the dictionary and then deletes the
        item from the dictionary."""
        if self._can_del(key):
            return dict.pop(self, key)
        else:
            raise Exception('Cannot `pop`, deletion of key "{}" failed.'.format(key))

    def popitem(self):
        """Pop the next key/value pair from the dictionary."""
        key = next(iter(self))
        return key, self.pop(key)

    def update(self, other_dict):
        """Copy the key/value pairs from another dictionary into this dictionary,
        overwriting any conflicting keys in this dictionary."""
        for (key, value) in other_dict.items():
            self[key] = value
            
    def clear(self):
        """Clear the dictionary."""
        for key in list(self.keys()):
            del self[key]

    def __setitem__(self, key, value):
        if (key in self and self._can_set(key, value)) or \
        (key not in self and self._can_add(key, value)):
            return dict.__setitem__(self, key, value)
        
    def __delitem__(self, key):
        if self._can_del(key):
            return dict.__delitem__(self, key)

    def _can_add(self, key, value):
        """Check if the item can be added to the dict."""
        return not bool(self._add_callback(key, value))

    def _can_del(self, key):
        """Check if the item can be deleted from the dict."""
        return not bool(self._del_callback(key))

    def _can_set(self, key, value):
        """Check if the item can be changed in the dict."""
        return not bool(self._set_callback(key, value))


class EventfulList(list):
    """Eventful list.

    This class inherits from the Python intrinsic `list` class.  It adds events 
    that allow you to listen for actions that modify the list.  You can 
    optionally cancel the actions.

    See the on_del, on_set, on_insert, on_sort, and on_reverse methods for
    registering an event handler.

    Some of the method docstrings were taken from the Python documentation at
    https://docs.python.org/2/tutorial/datastructures.html"""

    def __init__(self, *pargs, **kwargs):
        """Public constructor"""
        self._insert_callback = _void
        self._set_callback = _void
        self._del_callback = _void
        self._sort_callback = _void
        self._reverse_callback = _void
        list.__init__(self, *pargs, **kwargs)

    def on_events(self, insert_callback=None, set_callback=None, 
        del_callback=None, reverse_callback=None, sort_callback=None):
        """Register callbacks for add, set, and del actions.

        See the doctstrings for on_(insert/set/del/reverse/sort) for details 
        about each callback.

        insert_callback: [callback = None]
        set_callback: [callback = None]
        del_callback: [callback = None]
        reverse_callback: [callback = None]
        sort_callback: [callback = None]"""
        self.on_insert(insert_callback)
        self.on_set(set_callback)
        self.on_del(del_callback)
        self.on_reverse(reverse_callback)
        self.on_sort(sort_callback)

    def on_insert(self, callback):
        """Register a callback for when an item is inserted into the list.

        Allows the listener to detect when items are inserted into the list and
        optionally cancel the insertion.

        callback: callable or None
            If you want to ignore the insertion event, pass None as the callback.
            The callback should have a signature of callback(index, value).  The
            callback should return a boolean True if the insertion should be
            canceled, False or None otherwise."""
        self._insert_callback = callback if callable(callback) else _void
        
    def on_del(self, callback):
        """Register a callback for item deletion.

        Allows the listener to detect when items are deleted from the list and
        optionally cancel the deletion.

        callback: callable or None
            If you want to ignore the deletion event, pass None as the callback.
            The callback should have a signature of callback(index).  The
            callback should return a boolean True if the deletion should be
            canceled, False or None otherwise."""
        self._del_callback = callback if callable(callback) else _void
        
    def on_set(self, callback):
        """Register a callback for items are set.

        Allows the listener to detect when items are set and optionally cancel 
        the setting.  Note, `set` is also called when one or more items are
        added to the end of the list.

        callback: callable or None
            If you want to ignore the set event, pass None as the callback.
            The callback should have a signature of callback(index, value).  The
            callback should return a boolean True if the set should be
            canceled, False or None otherwise."""
        self._set_callback = callback if callable(callback) else _void
        
    def on_reverse(self, callback):
        """Register a callback for list reversal.

        callback: callable or None
            If you want to ignore the reverse event, pass None as the callback.
            The callback should have a signature of callback().  The
            callback should return a boolean True if the reverse should be
            canceled, False or None otherwise."""
        self._reverse_callback = callback if callable(callback) else _void
        
    def on_sort(self, callback):
        """Register a callback for sortting of the list.

        callback: callable or None
            If you want to ignore the sort event, pass None as the callback.
            The callback signature should match that of Python list's `.sort` 
            method or `callback(*pargs, **kwargs)` as a catch all. The callback 
            should return a boolean True if the reverse should be canceled, 
            False or None otherwise."""
        self._sort_callback = callback if callable(callback) else _void
        
    def append(self, x):
        """Add an item to the end of the list."""
        self[len(self):] = [x]

    def extend(self, L):
        """Extend the list by appending all the items in the given list."""
        self[len(self):] = L

    def remove(self, x):
        """Remove the first item from the list whose value is x. It is an error 
        if there is no such item."""
        del self[self.index(x)]
        
    def pop(self, i=None):
        """Remove the item at the given position in the list, and return it. If 
        no index is specified, a.pop() removes and returns the last item in the 
        list."""
        if i is None:
            i = len(self) - 1
        val = self[i]
        del self[i]
        return val

    def reverse(self):
        """Reverse the elements of the list, in place."""
        if self._can_reverse():
            list.reverse(self)
    
    def insert(self, index, value):
        """Insert an item at a given position. The first argument is the index 
        of the element before which to insert, so a.insert(0, x) inserts at the 
        front of the list, and a.insert(len(a), x) is equivalent to 
        a.append(x)."""
        if self._can_insert(index, value):
            list.insert(self, index, value)

    def sort(self, *pargs, **kwargs):
        """Sort the items of the list in place (the arguments can be used for 
        sort customization, see Python's sorted() for their explanation)."""
        if self._can_sort(*pargs, **kwargs):
            list.sort(self, *pargs, **kwargs)

    def __delitem__(self, index):
        if self._can_del(index):
            list.__delitem__(self, index)

    def __setitem__(self, index, value):
        if self._can_set(index, value):
            list.__setitem__(self, index, value)

    def __setslice__(self, start, end, value):
        if self._can_set(slice(start, end), value):
            list.__setslice__(self, start, end, value)
    
    def _can_insert(self, index, value):
        """Check if the item can be inserted."""
        return not bool(self._insert_callback(index, value))

    def _can_del(self, index):
        """Check if the item can be deleted."""
        return not bool(self._del_callback(index))

    def _can_set(self, index, value):
        """Check if the item can be set."""
        return not bool(self._set_callback(index, value))

    def _can_reverse(self):
        """Check if the list can be reversed."""
        return not bool(self._reverse_callback())

    def _can_sort(self, *pargs, **kwargs):
        """Check if the list can be sorted."""
        return not bool(self._sort_callback(*pargs, **kwargs))