How can I fire a Traits static event notification on a List?

Question

I am working through the traits presentation from PyCon 2010. At about 2:30:45 the presenter starts covering trait event notifications, which allow (among other things) the ability to automatically call a subroutine any time a trait has changed.

I am running a modified copy of the example he gave... In this trial, I am trying to see whether I can fire a static event whenever I make a change to volume or volume_inputs.

# Filename: spinaltap.py
from traits.api import HasTraits, Range, List, Float
import traits

class Amplifier(HasTraits):
    """
    Define an Amplifier (ref -> Spinal Tap) with Enthought's traits.  Use traits
    to enforce values boundaries on the Amplifier's attributes.  Use events to
    notify via the console when the volume trait is changed and when new volume
    traits are added to inputs.
    """

    # Define a volume trait as a Float between 0.0 and 11.0 (inclusive)
    # see self._volume_changed()
    volume = Range(value=5.0, trait=Float, low=0.0, high=11.0)

    # Define an inputs trait as a List() containing volume traits
    volume_inputs = List(volume) # <-- fire a static trait notification
                             # when another volume element is added
                             # see self._volume_inputs_changed()

    def __init__(self, volume=5.0):
        super(Amplifier, self).__init__()
        self.volume = volume
        self.volume_inputs.append(volume)

    def _volume_changed(self, old, new):
        # This is a static event listener for self.volume
        #                                     ^^^^^^^^^^^
        if not (new in self.inputs):
            self.inputs.append(self.volume)
        if new == 11.0:
            print("This one goes to eleven... so far, we have seen", self.inputs)

    def _volume_inputs_changed(self, old, new):
        # This is a static event listener for self.volume_inputs
        #                                     ^^^^^^^^^^^^^^^^^^
        print("Check it out!!")

if __name__=='__main__':
    spinal_tap = Amplifier()
    candidate_volume = 4.0
    spinal_tap.event_fired = False
    print("- INITIAL_VALUE var volume_inputs = {}".format(spinal_tap.volume_inputs))
    print("- APPEND a new volume of 4.0")
    print("    - volume_inputs = {} # BEGIN".format(spinal_tap.volume_inputs))
    print("    - volume_inputs.append({})".format(candidate_volume))
    spinal_tap.volume_inputs.append(candidate_volume)
    print("    - volume_inputs: {} # END".format(spinal_tap.volume_inputs))
    if spinal_tap.event_fired is False:
        print("    - Test FAILED: Traits did not fire _volume_inputs_changed()")
    else:
        print("    - Test PASSED: Traits fired _volume_inputs_changed()")
    try:
        spinal_tap.event_fired = False
        print("- NEGATIVE Test... try to append 12.0.  This should fail; 12.0 is out of bounds")
        print("    - volume_inputs: {} # BEGIN".format(spinal_tap.volume_inputs))
        candidate_volume = 12.0
        print("    - volume_inputs.append({})".format(candidate_volume))
        spinal_tap.volume_inputs.append(candidate_volume)
        print("    - volume_inputs: {} # END".format(spinal_tap.volume_inputs))
        if spinal_tap.event_fired is False:
            print("    - Test FAILED: Traits did not fire _volume_inputs_changed()")
    except  traits.trait_errors.TraitError:
        print("    - TraitError raised --> HERE <--")
        print("    - volume_inputs: {} # END".format(spinal_tap.volume_inputs))
        print("    - Test PASSED: traits correctly raised TraitError instead of appending {}.".format(candidate_volume))

Problem -> I never see any events from _volume_inputs_changed(). No matter what example I cook up, I can't get a List to fire an event.

In the output below, there is no evidence that _volume_inputs_changed() ever fires.

[mpenning@Bucksnort ~]$ python spinaltap.py
- INITIAL_VALUE var volume_inputs = [5.0]
- APPEND a new volume of 4.0
    - volume_inputs = [5.0] # BEGIN
    - volume_inputs.append(4.0)
    - volume_inputs: [5.0, 4.0] # END
    - Test FAILED: Traits did not fire _volume_inputs_changed()
- NEGATIVE Test... try to append 12.0.  This should fail; 12.0 is out of bounds
    - volume_inputs: [5.0, 4.0] # BEGIN
    - volume_inputs.append(12.0)
    - TraitError raised --> HERE <--
    - volume_inputs: [5.0, 4.0] # END
    - Test PASSED: traits correctly raised TraitError instead of appending 12.0.
[mpenning@Bucksnort ~]$

Should a List() be able to fire a static List() event (such as _inputs_changed()) when using traits? If so, am I doing something wrong?

Ferrochromium

Answer 1

After browsing their unit tests, I found a test for Dict traits in enthought's event unittest coverage...

When you have a traits container like a traits.api.List() or traits.api.Dict(), you need to set up the magic event listener method name like this:

# Magic event listener for the `traits.api.List()` called self.volume_inputs
def _volume_inputs_items_changed(self, old, new):

def _volume_inputs_items_changed(self, old, new):
    # This is a static event listener for --> self.volume_inputs <--
    if len(new.added) > 0:
        print "Check it out, we added %s to self.items" % new.added
    elif len(new.removed) > 0:
        print "Check it out, we removed %s from self.items" % new.removed

Likewise, I also discovered that the on_trait_change decorator (used for dynamic traits event notification) requires similar nomenclature if you are calling it with a traits.api.List or traits.api.Dict... so I could also write the code above as:

from traits.api import on_trait_change
# ...
@on_trait_change('volume_inputs_items')
def something_changed(self, name, new):
    # This is a static event listener for --> self.volume_inputs <--
    if len(new.added) > 0:
        print "Check it out, we added %s to self.items" % new.added
    elif len(new.removed) > 0:
        print "Check it out, we removed %s from self.items" % new.removed

Either way, when I run the code, I get expected output:

[mpenning@Bucksnort ~]$ python spinaltap.py
    - --> Firing _volume_inputs_items_changed() <-- check it out!!
- INITIAL_VALUE var volume_inputs = [5.0]
- APPEND a new volume of 4.0
    - volume_inputs = [5.0] # BEGIN
    - volume_inputs.append(4.0)
    - --> Firing _volume_inputs_items_changed() <-- check it out!!
    - volume_inputs: [5.0, 4.0] # END
    - Test PASSED: Traits fired _volume_inputs_changed()
- NEGATIVE Test... try to append 12.0.  This should fail; 12.0 is out of bounds
    - volume_inputs: [5.0, 4.0] # BEGIN
    - volume_inputs.append(12.0)
    - TraitError raised --> HERE <--
    - volume_inputs: [5.0, 4.0] # END
    - Test PASSED: traits correctly raised TraitError instead of appending 12.0.
[mpenning@Bucksnort ~]$

Ferrochromium

Answer 2

As this also caught me out recently, I've just verified Mike Pennington's answer with Traits 4.2.1. There does seem to be a distinction between changes to the List trait itself (such as assigning a new list to it), and changes to the membership of the List (such as appending or setting by index). The former uses the same name as the trait (e.g. inputs), whereas the latter uses the "_items" suffix. This example seems to demonstrate this:

from traits.api import Float, HasTraits, Instance, List

class Part(HasTraits):
    costs = List(Float)

    # called when the actual List trait changes:
    def _costs_changed(self, old, new):
        print("Part::_costs_changed %s -> %s" % (str(old), str(new)))

    # called when the contents of the List trait changes:
    def _costs_items_changed(self, old, new):
        print("Part::_costs_changed %s -> %s" % (str(old), str(new)))

class Widget(HasTraits):
    part = Instance(Part)

    def __init__(self):
        self.part = Part()
        self.part.on_trait_change(self.update_costs, 'costs')
        self.part.on_trait_change(self.update_costs_items, 'costs_items')

    def update_costs(self, name, new):
        print("update_costs: %s = %s" % (name, str(new),))

    def update_costs_items(self, name, new):
        print("update_costs_items: %s = %s" % (name, str(new),))

w = Widget()

w.part.costs = [ 1.0, 2.0, 3.0 ]
# Part::_costs_changed [] -> [1.0, 2.0, 3.0]
# update_costs: costs = [1.0, 2.0, 3.0]

w.part.costs = [ 1.0, 2.0, 3.1 ]
# Part::_costs_changed [1.0, 2.0, 3.0] -> [1.0, 2.0, 3.1]
# update_costs: costs = [1.0, 2.0, 3.1]

w.part.costs[0] = 5.0
# Part::_costs_changed <undefined> -> <traits.trait_handlers.TraitListEvent object at 0x1007bd810>
# update_costs_items: costs_items = <traits.trait_handlers.TraitListEvent object at 0x1007bd810>

w.part.costs.append(4.0)
# Part::_costs_changed <undefined> -> <traits.trait_handlers.TraitListEvent object at 0x1007bd810>
# update_costs_items: costs_items = <traits.trait_handlers.TraitListEvent object at 0x1007bd810>

This behaviour is hinted at in the documentation here.

However if an extended name is used it does seem possible to have the same handler called when the entire list or membership is changed:

from traits.api import Float, HasTraits, Instance, List

class Part(HasTraits):
    costs = List(Float)

def _costs_changed(self, old, new):
    print("_costs_changed %s -> %s" % (str(old), str(new)))

def _costs_items_changed(self, old, new):
    print("_costs_items_changed %s -> %s" % (str(old), str(new)))

class Widget(HasTraits):
    part = Instance(Part)

    def __init__(self):
        self.part = Part()
        self.part.on_trait_change(self.update_costs, 'costs[]')  # <-- extended name

    def update_costs(self, name, new):
        print("update_costs: %s = %s" % (name, str(new),))

w = Widget()

w.part.costs = [ 1.0, 2.0, 3.0 ]
# _costs_changed [] -> [1.0, 2.0, 3.0]
# update_costs: costs = [1.0, 2.0, 3.0]

w.part.costs = [ 1.0, 2.0, 3.1 ]
# _costs_changed [1.0, 2.0, 3.0] -> [1.0, 2.0, 3.1]
# update_costs: costs = [1.0, 2.0, 3.1]

w.part.costs[0] = 5.0
# _costs_items_changed <undefined> -> <traits.trait_handlers.TraitListEvent object at 0x1007c6f90>
# update_costs: costs_items = [5.0]

w.part.costs.append(4.0)
# _costs_items_changed <undefined> -> <traits.trait_handlers.TraitListEvent object at 0x1007c6f90>
# update_costs: costs_items = [4.0]

In this case, the name parameter of the update_costs handler can be used to differentiate between the container itself changing, or a single item within the container changing.

Godric