Note

This documentation is for a development version of IPython. There may be significant differences from the latest stable release.

Module: utils.eventful

Contains eventful dict and list implementations.

2 Classes

class IPython.utils.eventful.EventfulDict(*args, **kwargs)

Bases: 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.

__init__(*args, **kwargs)

Public constructor

clear()

Clear the dictionary.

on_add(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.

on_del(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.

on_events(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]

on_set(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.

pop(key)

Returns the value of an item in the dictionary and then deletes the item from the dictionary.

popitem()

Pop the next key/value pair from the dictionary.

update(other_dict)

Copy the key/value pairs from another dictionary into this dictionary, overwriting any conflicting keys in this dictionary.

class IPython.utils.eventful.EventfulList(*pargs, **kwargs)

Bases: 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

__init__(*pargs, **kwargs)

Public constructor

append(x)

Add an item to the end of the list.

extend(L)

Extend the list by appending all the items in the given list.

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

on_del(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.

on_events(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]

on_insert(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.

on_reverse(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.

on_set(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.

on_sort(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.

pop(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.

remove(x)

Remove the first item from the list whose value is x. It is an error if there is no such item.

reverse()

Reverse the elements of the list, in place.

sort(*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).