Added support for Type and Instance traitlets with testing.

IPython/utils/tests/test_traitlets.py

@@ -1,437 +1,558
 #!/usr/bin/env python
 # encoding: utf-8
 """
 Tests for IPython.utils.traitlets.
 
 Authors:
 
 * Brian Granger
 * Enthought, Inc.  Some of the code in this file comes from enthought.traits
   and is licensed under the BSD license.  Also, many of the ideas also come
   from enthought.traits even though our implementation is very different.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import sys
 import os
 
 
 from unittest import TestCase
 
 from IPython.utils.traitlets import (
     HasTraitlets, MetaHasTraitlets, TraitletType, Any,
-    Int, Long, Float, Complex, Str, Unicode, Bool, TraitletError
+    Int, Long, Float, Complex, Str, Unicode, Bool, TraitletError,
+    Undefined, Type, Instance
 )
 
 
 #-----------------------------------------------------------------------------
 # Helper classes for testing
 #-----------------------------------------------------------------------------
 
 
 class HasTraitletsStub(object):
 
     def __init__(self):
         self._traitlet_values = {}
         self._traitlet_notifiers = {}
 
     def _notify(self, name, old, new):
         self._notify_name = name
         self._notify_old = old
         self._notify_new = new
 
 
 #-----------------------------------------------------------------------------
 # Test classes
 #-----------------------------------------------------------------------------
 
 
 class TestTraitletType(TestCase):
 
     name = 'a'
 
     def setUp(self):
         self.tt = TraitletType()
         self.tt.name = self.name
         self.hast = HasTraitletsStub() 
 
-    def test_get(self):
+    def test_get_undefined(self):
         value = self.tt.__get__(self.hast)
-        self.assertEquals(value, None)
+        self.assertEquals(value, Undefined)
 
     def test_set(self):
         self.tt.__set__(self.hast, 10)
         self.assertEquals(self.hast._traitlet_values[self.name],10)
         self.assertEquals(self.hast._notify_name,self.name)
-        self.assertEquals(self.hast._notify_old,None)
+        self.assertEquals(self.hast._notify_old,Undefined)
         self.assertEquals(self.hast._notify_new,10)
 
     def test_validate(self):
         class MyTT(TraitletType):
             def validate(self, inst, value):
                 return -1
         tt = MyTT()
         tt.name = self.name
         tt.__set__(self.hast, 10)
         self.assertEquals(tt.__get__(self.hast),-1)
 
+    def test_default_validate(self):
+        class MyIntTT(TraitletType):
+            def validate(self, obj, value):
+                if isinstance(value, int):
+                    return value
+                self.error(obj, value)
+        tt = MyIntTT(10)
+        tt.name = 'a'
+        self.assertEquals(tt.__get__(self.hast), 10)
+        tt = MyIntTT('bad default')
+        tt.name = 'b' # different name from 'a' as we want an unset dv
+        self.assertRaises(TraitletError, tt.__get__, self.hast)
+            
+
     def test_is_valid_for(self):
         class MyTT(TraitletType):
             def is_valid_for(self, value):
                 return True
         tt = MyTT()
         tt.name = self.name
         tt.__set__(self.hast, 10)
         self.assertEquals(tt.__get__(self.hast),10)
 
     def test_value_for(self):
         class MyTT(TraitletType):
             def value_for(self, value):
                 return 20
         tt = MyTT()
         tt.name = self.name
         tt.__set__(self.hast, 10)
         self.assertEquals(tt.__get__(self.hast),20)
 
     def test_info(self):
         self.assertEquals(self.tt.info(),'any value')
 
     def test_error(self):
         self.assertRaises(TraitletError, self.tt.error, self.hast, 10)
 
 
 class TestHasTraitletsMeta(TestCase):
 
     def test_metaclass(self):
         self.assertEquals(type(HasTraitlets), MetaHasTraitlets)
 
         class A(HasTraitlets):
             a = Int
 
         a = A()
         self.assertEquals(type(a.__class__), MetaHasTraitlets)
         self.assertEquals(a.a,0)
         a.a = 10
         self.assertEquals(a.a,10)
 
         class B(HasTraitlets):
             b = Int()
 
         b = B()
         self.assertEquals(b.b,0)
         b.b = 10
         self.assertEquals(b.b,10)
 
         class C(HasTraitlets):
             c = Int(30)
 
         c = C()
         self.assertEquals(c.c,30)
         c.c = 10
         self.assertEquals(c.c,10)
 
 
 class TestHasTraitletsNotify(TestCase):
 
     def setUp(self):
         self._notify1 = []
         self._notify2 = []
 
     def notify1(self, name, old, new):
         self._notify1.append((name, old, new))
 
     def notify2(self, name, old, new):
         self._notify2.append((name, old, new))
 
     def test_notify_all(self):
 
         class A(HasTraitlets):
             a = Int
             b = Float
 
         a = A()
         a.on_traitlet_change(self.notify1)
         a.a = 0
         self.assertEquals(len(self._notify1),0)
         a.b = 0.0
         self.assertEquals(len(self._notify1),0)
         a.a = 10
         self.assert_(('a',0,10) in self._notify1)
         a.b = 10.0
         self.assert_(('b',0.0,10.0) in self._notify1)
         self.assertRaises(TraitletError,setattr,a,'a','bad string')
         self.assertRaises(TraitletError,setattr,a,'b','bad string')
         self._notify1 = []
         a.on_traitlet_change(self.notify1,remove=True)
         a.a = 20
         a.b = 20.0
         self.assertEquals(len(self._notify1),0)
 
     def test_notify_one(self):
 
         class A(HasTraitlets):
             a = Int
             b = Float
 
         a = A()
         a.on_traitlet_change(self.notify1, 'a')
         a.a = 0
         self.assertEquals(len(self._notify1),0)
         a.a = 10
         self.assert_(('a',0,10) in self._notify1)
         self.assertRaises(TraitletError,setattr,a,'a','bad string')
 
     def test_subclass(self):
 
         class A(HasTraitlets):
             a = Int
 
         class B(A):
             b = Float
 
         b = B()
         self.assertEquals(b.a,0)
         self.assertEquals(b.b,0.0)
         b.a = 100
         b.b = 100.0
         self.assertEquals(b.a,100)
         self.assertEquals(b.b,100.0)
 
     def test_notify_subclass(self):
 
         class A(HasTraitlets):
             a = Int
 
         class B(A):
             b = Float
 
         b = B()
         b.on_traitlet_change(self.notify1, 'a')
         b.on_traitlet_change(self.notify2, 'b')
         b.a = 0
         b.b = 0.0
         self.assertEquals(len(self._notify1),0)
         self.assertEquals(len(self._notify2),0)
         b.a = 10
         b.b = 10.0
         self.assert_(('a',0,10) in self._notify1)
         self.assert_(('b',0.0,10.0) in self._notify2)
 
     def test_static_notify(self):
 
         class A(HasTraitlets):
             a = Int
             _notify1 = []
             def _a_changed(self, name, old, new):
                 self._notify1.append((name, old, new))
 
         a = A()
         a.a = 0
         self.assertEquals(len(a._notify1),0)
         a.a = 10
         self.assert_(('a',0,10) in a._notify1)
 
         class B(A):
             b = Float
             _notify2 = []
             def _b_changed(self, name, old, new):
                 self._notify2.append((name, old, new))
 
         b = B()
         b.a = 10
         b.b = 10.0
         self.assert_(('a',0,10) in b._notify1)
         self.assert_(('b',0.0,10.0) in b._notify2)
 
     def test_notify_args(self):
 
         def callback0():
             self.cb = ()
         def callback1(name):
             self.cb = (name,)
         def callback2(name, new):
             self.cb = (name, new)
         def callback3(name, old, new):
             self.cb = (name, old, new)
 
         class A(HasTraitlets):
             a = Int
 
         a = A()
         a.on_traitlet_change(callback0, 'a')
         a.a = 10
         self.assertEquals(self.cb,())
         a.on_traitlet_change(callback0, 'a', remove=True)
 
         a.on_traitlet_change(callback1, 'a')
         a.a = 100
         self.assertEquals(self.cb,('a',))
         a.on_traitlet_change(callback1, 'a', remove=True)
 
         a.on_traitlet_change(callback2, 'a')
         a.a = 1000
         self.assertEquals(self.cb,('a',1000))
         a.on_traitlet_change(callback2, 'a', remove=True)
 
         a.on_traitlet_change(callback3, 'a')
         a.a = 10000
         self.assertEquals(self.cb,('a',1000,10000))
         a.on_traitlet_change(callback3, 'a', remove=True)
 
         self.assertEquals(len(a._traitlet_notifiers['a']),0)
 
 
 class TestAddTraitlet(TestCase):
 
     def test_add_float(self):
 
         class A(HasTraitlets):
             a = Int
         
         a = A()
         a.a = 10
         a._add_class_traitlet('b',Float)
         self.assertEquals(a.b,0.0)
         a.b = 10.0
         self.assertEquals(a.b,10.0)
         self.assertRaises(TraitletError, setattr, a, 'b', 'bad value')
 
 
 #-----------------------------------------------------------------------------
 # Tests for specific traitlet types
 #-----------------------------------------------------------------------------
 
+
+class TestType(TestCase):
+
+    def test_default(self):
+
+        class B(object): pass
+        class A(HasTraitlets):
+            klass = Type
+
+        a = A()
+        self.assertEquals(a.klass, None)
+        a.klass = B
+        self.assertEquals(a.klass, B)
+        self.assertRaises(TraitletError, setattr, a, 'klass', 10)
+
+    def test_value(self):
+
+        class B(object): pass
+        class C(object): pass
+        class A(HasTraitlets):
+            klass = Type(B)
+        
+        a = A()
+        self.assertEquals(a.klass, B)
+        self.assertRaises(TraitletError, setattr, a, 'klass', C)
+        self.assertRaises(TraitletError, setattr, a, 'klass', object)
+        a.klass = B
+
+    def test_allow_none(self):
+
+        class B(object): pass
+        class C(B): pass
+        class A(HasTraitlets):
+            klass = Type(B, allow_none=False)
+
+        a = A()
+        self.assertEquals(a.klass, B)
+        self.assertRaises(TraitletError, setattr, a, 'klass', None)
+        a.klass = C
+        self.assertEquals(a.klass, C)
+
+
+class TestInstance(TestCase):
+
+    def test_basic(self):
+        class Foo(object): pass
+        class Bar(Foo): pass
+        class Bah(object): pass
+        
+        class A(HasTraitlets):
+            inst = Instance(Foo)
+
+        a = A()
+        self.assert_(isinstance(a.inst, Foo))
+        a.inst = Foo()
+        self.assert_(isinstance(a.inst, Foo))
+        a.inst = Bar()
+        self.assert_(isinstance(a.inst, Foo))
+        self.assertRaises(TraitletError, setattr, a, 'inst', Foo)
+        self.assertRaises(TraitletError, setattr, a, 'inst', Bar)
+        self.assertRaises(TraitletError, setattr, a, 'inst', Bah())
+
+    def test_unique_default_value(self):
+        class Foo(object): pass        
+        class A(HasTraitlets):
+            inst = Instance(Foo)
+
+        a = A()
+        b = A()
+        self.assert_(a.inst is not b.inst)
+
+    def test_args_kw(self):
+        class Foo(object):
+            def __init__(self, c): self.c = c
+
+        class A(HasTraitlets):
+            inst = Instance(Foo, args=(10,))
+
+        a = A()
+        self.assertEquals(a.inst.c, 10)
+
+        class Bar(object):
+            def __init__(self, c, d):
+                self.c = c; self.d = d
+
+        class B(HasTraitlets):
+            inst = Instance(Bar, args=(10,),kw=dict(d=20))
+        b = B()
+        self.assertEquals(b.inst.c, 10)
+        self.assertEquals(b.inst.d, 20)
+
+    def test_instance(self):
+        # Does passing an instance yield a default value of None?
+        class Foo(object): pass
+
+        class A(HasTraitlets):
+            inst = Instance(Foo())
+        a = A()
+        self.assertEquals(a.inst, None)
+        
+        class B(HasTraitlets):
+            inst = Instance(Foo(), allow_none=False)
+        b = B()
+        self.assertRaises(TraitletError, getattr, b, 'inst')
+
 class TraitletTestBase(TestCase):
+    """A best testing class for basic traitlet types."""
 
     def assign(self, value):
         self.obj.value = value
 
     def coerce(self, value):
         return value
 
     def test_good_values(self):
         if hasattr(self, '_good_values'):
             for value in self._good_values:
                 self.assign(value)
                 self.assertEquals(self.obj.value, self.coerce(value))
 
     def test_bad_values(self):
         if hasattr(self, '_bad_values'):
             for value in self._bad_values:
                 self.assertRaises(TraitletError, self.assign, value)
 
     def test_default_value(self):
         if hasattr(self, '_default_value'):
             self.assertEquals(self._default_value, self.obj.value)
 
 
 class AnyTraitlet(HasTraitlets):
 
     value = Any
 
 class AnyTraitTest(TraitletTestBase):
 
     obj = AnyTraitlet()
 
     _default_value = None
     _good_values   = [10.0, 'ten', u'ten', [10], {'ten': 10},(10,), None, 1j]
     _bad_values    = []
 
 
 class IntTraitlet(HasTraitlets):
 
     value = Int(99)
 
 class TestInt(TraitletTestBase):
 
     obj = IntTraitlet()
     _default_value = 99
     _good_values   = [10, -10]
     _bad_values    = ['ten', u'ten', [10], {'ten': 10},(10,), None, 1j, 10L,
                       -10L, 10.1, -10.1, '10L', '-10L', '10.1', '-10.1', u'10L',
                       u'-10L', u'10.1', u'-10.1',  '10', '-10', u'10', u'-10']
 
 
 class LongTraitlet(HasTraitlets):
 
     value = Long(99L)
 
 class TestLong(TraitletTestBase):
 
     obj = LongTraitlet()
 
     _default_value = 99L
     _good_values   = [10, -10, 10L, -10L]
     _bad_values    = ['ten', u'ten', [10], [10l], {'ten': 10},(10,),(10L,),
                       None, 1j, 10.1, -10.1, '10', '-10', '10L', '-10L', '10.1',
                       '-10.1', u'10', u'-10', u'10L', u'-10L', u'10.1',
                       u'-10.1']
 
 
 class FloatTraitlet(HasTraitlets):
 
     value = Float(99.0)
 
 class TestFloat(TraitletTestBase):
 
     obj = FloatTraitlet()
 
     _default_value = 99.0
     _good_values   = [10, -10, 10.1, -10.1]
     _bad_values    = [10L, -10L, 'ten', u'ten', [10], {'ten': 10},(10,), None,
                       1j, '10', '-10', '10L', '-10L', '10.1', '-10.1', u'10',
                       u'-10', u'10L', u'-10L', u'10.1', u'-10.1']
 
 
 class ComplexTraitlet(HasTraitlets):
 
     value = Complex(99.0-99.0j)
 
 class TestComplex(TraitletTestBase):
 
     obj = ComplexTraitlet()
 
     _default_value = 99.0-99.0j
     _good_values   = [10, -10, 10.1, -10.1, 10j, 10+10j, 10-10j, 
                       10.1j, 10.1+10.1j, 10.1-10.1j]
     _bad_values    = [10L, -10L, u'10L', u'-10L', 'ten', [10], {'ten': 10},(10,), None]
 
 
 class StringTraitlet(HasTraitlets):
 
     value = Str('string')
 
 class TestString(TraitletTestBase):
 
     obj = StringTraitlet()
 
     _default_value = 'string'
     _good_values   = ['10', '-10', '10L',
                       '-10L', '10.1', '-10.1', 'string']
     _bad_values    = [10, -10, 10L, -10L, 10.1, -10.1, 1j, [10],
                       ['ten'],{'ten': 10},(10,), None,  u'string']
 
 
 class UnicodeTraitlet(HasTraitlets):
 
     value = Unicode(u'unicode')
 
 class TestUnicode(TraitletTestBase):
 
     obj = UnicodeTraitlet()
 
     _default_value = u'unicode'
     _good_values   = ['10', '-10', '10L', '-10L', '10.1', 
                       '-10.1', '', u'', 'string', u'string', ]
     _bad_values    = [10, -10, 10L, -10L, 10.1, -10.1, 1j,
                       [10], ['ten'], [u'ten'], {'ten': 10},(10,), None]

IPython/utils/traitlets.py

@@ -1,436 +1,752
 #!/usr/bin/env python
 # encoding: utf-8
 """
 A lightweight Traits like module.
 
 This is designed to provide a lightweight, simple, pure Python version of
 many of the capabilities of enthought.traits.  This includes:
 
 * Validation
 * Type specification with defaults
 * Static and dynamic notification
 * Basic predefined types
 * An API that is similar to enthought.traits
 
 We don't support:
 
 * Delegation
 * Automatic GUI generation
 * A full set of trait types
 * API compatibility with enthought.traits
 
 We choose to create this module because we need these capabilities, but
 we need them to be pure Python so they work in all Python implementations,
 including Jython and IronPython.
 
 Authors:
 
 * Brian Granger
 * Enthought, Inc.  Some of the code in this file comes from enthought.traits
   and is licensed under the BSD license.  Also, many of the ideas also come
   from enthought.traits even though our implementation is very different.
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
+
 import inspect
+import sys
 import types
-from types import InstanceType
+from types import InstanceType, ClassType
+
+ClassTypes = (ClassType, type)
 
 #-----------------------------------------------------------------------------
 # Basic classes
 #-----------------------------------------------------------------------------
 
 
 class NoDefaultSpecified ( object ): pass
 NoDefaultSpecified = NoDefaultSpecified()
 
 
 class Undefined ( object ): pass
 Undefined = Undefined()
 
 
 class TraitletError(Exception):
     pass
 
 
 #-----------------------------------------------------------------------------
 # Utilities
 #-----------------------------------------------------------------------------
 
 
 def class_of ( object ):
     """ Returns a string containing the class name of an object with the
     correct indefinite article ('a' or 'an') preceding it (e.g., 'an Image',
     'a PlotValue').
     """
     if isinstance( object, basestring ):
         return add_article( object )
 
     return add_article( object.__class__.__name__ )
 
 
 def add_article ( name ):
     """ Returns a string containing the correct indefinite article ('a' or 'an')
     prefixed to the specified string.
     """
     if name[:1].lower() in 'aeiou':
        return 'an ' + name
 
     return 'a ' + name
 
 
 def repr_type(obj):
     """ Return a string representation of a value and its type for readable
     error messages.
     """
     the_type = type(obj)
     if the_type is InstanceType:
         # Old-style class.
         the_type = obj.__class__
     msg = '%r %r' % (obj, the_type)
     return msg
 
 
 def parse_notifier_name(name):
     """Convert the name argument to a list of names.
     
     Examples
     --------
     
     >>> parse_notifier_name('a')
     ['a']
     >>> parse_notifier_name(['a','b'])
     ['a', 'b']
     >>> parse_notifier_name(None)
     ['anytraitlet']
     """
     if isinstance(name, str):
         return [name]
     elif name is None:
         return ['anytraitlet']
     elif isinstance(name, (list, tuple)):
         for n in name:
             assert isinstance(n, str), "names must be strings"
         return name
 
 
+def get_module_name ( level = 2 ):
+    """ Returns the name of the module that the caller's caller is located in.
+    """
+    return sys._getframe( level ).f_globals.get( '__name__', '__main__' )
+
+
 #-----------------------------------------------------------------------------
 # Base TraitletType for all traitlets
 #-----------------------------------------------------------------------------
 
 
 class TraitletType(object):
 
     metadata = {}
-    default_value = None
+    default_value = Undefined
     info_text = 'any value'
 
     def __init__(self, default_value=NoDefaultSpecified, **metadata):
+        """Create a TraitletType.
+        """
         if default_value is not NoDefaultSpecified:
             self.default_value = default_value
         self.metadata.update(metadata)
+        self.init()
 
-    def __get__(self, inst, cls=None):
-        if inst is None:
+    def init(self):
+        pass
+
+    def get_default_value(self):
+        """Create a new instance of the default value."""
+        dv = self.default_value
+        return dv
+
+    def __get__(self, obj, cls=None):
+        """Get the value of the traitlet by self.name for the instance.
+        
+        The creation of default values is deferred until this is called the
+        first time.  This is done so instances of the parent HasTraitlets
+        will have their own default value instances.
+        """
+        if obj is None:
             return self
         else:
-            return inst._traitlet_values.get(self.name, self.default_value)
+            if not obj._traitlet_values.has_key(self.name):
+                dv = self.get_default_value()
+                self.__set__(obj, dv, first=True)
+                return dv
+            else:
+                return obj._traitlet_values[self.name]
 
-    def __set__(self, inst, value):
-        new_value = self._validate(inst, value)
-        old_value = self.__get__(inst)
+    def __set__(self, obj, value, first=False):
+        new_value = self._validate(obj, value)
+        if not first:
+            old_value = self.__get__(obj)
         if old_value != new_value:
-            inst._traitlet_values[self.name] = new_value
-            inst._notify(self.name, old_value, new_value)
+                obj._traitlet_values[self.name] = new_value
+                obj._notify(self.name, old_value, new_value)
+        else:
+            obj._traitlet_values[self.name] = new_value
 
-    def _validate(self, inst, value):
+    def _validate(self, obj, value):
         if hasattr(self, 'validate'):
-            return self.validate(inst, value)
+            return self.validate(obj, value)
         elif hasattr(self, 'is_valid_for'):
             valid = self.is_valid_for(value)
             if valid:
                 return value
             else:
                 raise TraitletError('invalid value for type: %r' % value)
         elif hasattr(self, 'value_for'):
             return self.value_for(value)
         else:
             return value
 
     def info(self):
         return self.info_text
 
     def error(self, obj, value):
         if obj is not None:
             e = "The '%s' traitlet of %s instance must be %s, but a value of %s was specified." \
                 % (self.name, class_of(obj),
                    self.info(), repr_type(value))
         else:
             e = "The '%s' traitlet must be %s, but a value of %r was specified." \
                 % (self.name, self.info(), repr_type(value))            
         raise TraitletError(e)
 
 
 #-----------------------------------------------------------------------------
 # The HasTraitlets implementation
 #-----------------------------------------------------------------------------
 
 
 class MetaHasTraitlets(type):
     """A metaclass for HasTraitlets.
     
     This metaclass makes sure that any TraitletType class attributes are
     instantiated and sets their name attribute.
     """
     
     def __new__(mcls, name, bases, classdict):
         for k,v in classdict.iteritems():
             if isinstance(v, TraitletType):
                 v.name = k
             elif inspect.isclass(v):
                 if issubclass(v, TraitletType):
                     vinst = v()
                     vinst.name = k
                     classdict[k] = vinst
         return super(MetaHasTraitlets, mcls).__new__(mcls, name, bases, classdict)
 
 
 class HasTraitlets(object):
 
     __metaclass__ = MetaHasTraitlets
 
     def __init__(self):
         self._traitlet_values = {}
         self._traitlet_notifiers = {}
 
     def _notify(self, name, old_value, new_value):
 
         # First dynamic ones
         callables = self._traitlet_notifiers.get(name,[])
         more_callables = self._traitlet_notifiers.get('anytraitlet',[])
         callables.extend(more_callables)
 
         # Now static ones
         try:
             cb = getattr(self, '_%s_changed' % name)
         except:
             pass
         else:
             callables.append(cb)
 
         # Call them all now
         for c in callables:
             # Traits catches and logs errors here.  I allow them to raise
             if callable(c):
                 argspec = inspect.getargspec(c)
                 nargs = len(argspec[0])
                 # Bound methods have an additional 'self' argument
                 # I don't know how to treat unbound methods, but they
                 # can't really be used for callbacks.
                 if isinstance(c, types.MethodType):
                     offset = -1
                 else:
                     offset = 0
                 if nargs + offset == 0:
                     c()
                 elif nargs + offset == 1:
                     c(name)
                 elif nargs + offset == 2:
                     c(name, new_value)
                 elif nargs + offset == 3:
                     c(name, old_value, new_value)
                 else:
                     raise TraitletError('a traitlet changed callback '
                                         'must have 0-3 arguments.')
             else:
                 raise TraitletError('a traitlet changed callback '
                                     'must be callable.')
                 
 
     def _add_notifiers(self, handler, name):
         if not self._traitlet_notifiers.has_key(name):
             nlist = []
             self._traitlet_notifiers[name] = nlist
         else:
             nlist = self._traitlet_notifiers[name]
         if handler not in nlist:
             nlist.append(handler)
 
     def _remove_notifiers(self, handler, name):
         if self._traitlet_notifiers.has_key(name):
             nlist = self._traitlet_notifiers[name]
             try:
                 index = nlist.index(handler)
             except ValueError:
                 pass
             else:
                 del nlist[index]
 
     def on_traitlet_change(self, handler, name=None, remove=False):
         """Setup a handler to be called when a traitlet changes.
 
         This is used to setup dynamic notifications of traitlet changes.
         
         Static handlers can be created by creating methods on a HasTraitlets
         subclass with the naming convention '_[traitletname]_changed'.  Thus,
         to create static handler for the traitlet 'a', create the method
         _a_changed(self, name, old, new) (fewer arguments can be used, see
         below).
         
         Parameters
         ----------
             handler : callable
                 A callable that is called when a traitlet changes.  Its 
                 signature can be handler(), handler(name), handler(name, new)
                 or handler(name, old, new).
             name : list, str, None
                 If None, the handler will apply to all traitlets.  If a list
                 of str, handler will apply to all names in the list.  If a
                 str, the handler will apply just to that name.
             remove : bool
                 If False (the default), then install the handler.  If True
                 then unintall it.
         """
         if remove:
             names = parse_notifier_name(name)
             for n in names:
                 self._remove_notifiers(handler, n)
         else:
             names = parse_notifier_name(name)
             for n in names:
                 self._add_notifiers(handler, n)
 
     def _add_class_traitlet(self, name, traitlet):
         """Add a class-level traitlet.
 
         This create a new traitlet attached to all instances of this class.
         But, the value can be different on each instance.  But, this behavior
         is likely to trip up many folks as they would expect the traitlet
         type to be different on each instance.
 
         Parameters
         ----------
         name : str
             The name of the traitlet.
         traitlet : TraitletType or an instance of one
             The traitlet to assign to the name.
         """
         if inspect.isclass(traitlet):
             inst = traitlet()
         else:
             inst = traitlet
         assert isinstance(inst, TraitletType)
         inst.name = name
         setattr(self.__class__, name, inst)
 
+
 #-----------------------------------------------------------------------------
 # Actual TraitletTypes implementations/subclasses
 #-----------------------------------------------------------------------------
 
+#-----------------------------------------------------------------------------
+# TraitletTypes subclasses for handling classes and instances of classes
+#-----------------------------------------------------------------------------
+
+
+class BaseClassResolver(TraitletType):
+    """Mixin class for traitlets that need to resolve classes by strings.
+    
+    This class provides is a mixin that provides its subclasses with the 
+    ability to resolve classes by specifying a string name (for example,
+    'foo.bar.MyClass').  An actual class can also be resolved.
+
+    Any subclass must define instances with 'klass' and 'module' attributes
+    that contain the string name of the class (or actual class object) and
+    the module name that contained the original trait definition (used for
+    resolving local class names (e.g. 'LocalClass')).
+    """
+
+    def resolve_class(self, obj, value):
+        klass = self.validate_class(self.find_class(self.klass))
+        if klass is None:
+            self.validate_failed(obj, value)
+
+        self.klass = klass
+
+    def validate_class(self, klass):
+        return klass
+
+    def find_class(self, klass):
+        module = self.module
+        col    = klass.rfind('.')
+        if col >= 0:
+            module = klass[ : col ]
+            klass = klass[ col + 1: ]
+
+        theClass = getattr(sys.modules.get(module), klass, None)
+        if (theClass is None) and (col >= 0):
+            try:
+                mod = __import__(module)
+                for component in module.split( '.' )[1:]:
+                    mod = getattr(mod, component)
+
+                theClass = getattr(mod, klass, None)
+            except:
+                pass
+
+        return theClass
+
+    def validate_failed (self, obj, value):
+        kind = type(value)
+        if kind is InstanceType:
+            msg = 'class %s' % value.__class__.__name__
+        else:
+            msg = '%s (i.e. %s)' % ( str( kind )[1:-1], repr( value ) )
+
+        self.error(obj, msg)
+
+
+class Type(BaseClassResolver):
+    """A traitlet whose value must be a subclass of a specified class."""
+
+    def __init__ (self, default_value=None, klass=None, allow_none=True, **metadata ):
+        """Construct a Type traitlet
+
+        A Type traitlet specifies that its values must be subclasses of
+        a particular class.
+
+        Parameters
+        ----------
+        default_value : class or None
+            The default value must be a subclass of klass.
+        klass : class, str, None
+            Values of this traitlet must be a subclass of klass.  The klass
+            may be specified in a string like: 'foo.bar.MyClass'.
+        allow_none : boolean
+            Indicates whether None is allowed as an assignable value. Even if
+            ``False``, the default value may be ``None``.
+        """
+        if default_value is None:
+            if klass is None:
+                klass = object
+        elif klass is None:
+            klass = default_value
+
+        if isinstance(klass, basestring):
+            self.validate = self.resolve
+        elif not isinstance(klass, ClassTypes):
+            raise TraitletError("A Type traitlet must specify a class.")
+
+        self.klass       = klass
+        self._allow_none = allow_none
+        self.module      = get_module_name()
+
+        super(Type, self).__init__(default_value, **metadata)
+
+    def validate(self, obj, value):
+        """Validates that the value is a valid object instance."""
+        try:
+            if issubclass(value, self.klass):
+                return value
+        except:
+            if (value is None) and (self._allow_none):
+                return value
+
+        self.error(obj, value)
+
+    def resolve(self, obj, name, value):
+        """ Resolves a class originally specified as a string into an actual
+            class, then resets the trait so that future calls will be handled by
+            the normal validate method.
+        """
+        if isinstance(self.klass, basestring):
+            self.resolve_class(obj, value)
+            del self.validate
+
+        return self.validate(obj, value)
+
+    def info(self):
+        """ Returns a description of the trait."""
+        klass = self.klass
+        if not isinstance(klass, basestring):
+            klass = klass.__name__
+
+        result = 'a subclass of ' + klass
+
+        if self._allow_none:
+            return result + ' or None'
+
+        return result
+
+    def get_default_value(self):
+        """ Returns a tuple of the form: ( default_value_type, default_value )
+            which describes the default value for this trait.
+        """
+        if not isinstance(self.default_value, basestring):
+            return super(Type, self).get_default_value()
+
+        dv = self.resolve_default_value()
+        dvt = type(dv)
+        return (dvt, dv)
+
+    def resolve_default_value(self):
+        """ Resolves a class name into a class so that it can be used to
+            return the class as the default value of the trait.
+        """
+        if isinstance(self.klass, basestring):
+            try:
+                self.resolve_class(None, None)
+                del self.validate
+            except:
+                raise TraitletError('Could not resolve %s into a valid class' %
+                                    self.klass )
+
+        return self.klass
+
+
+class DefaultValueGenerator(object):
+    """A class for generating new default value instances."""
+
+    def __init__(self, klass, *args, **kw):
+        self.klass = klass
+        self.args = args
+        self.kw = kw
+
+
+class Instance(BaseClassResolver):
+    """A trait whose value must be an instance of a specified class.
+    
+    The value can also be an instance of a subclass of the specified class.
+    """
+
+    def __init__(self, klass=None, args=None, kw=None, allow_none=True, 
+                 module = None, **metadata ):
+        """Construct an Instance traitlet.
+
+        Parameters
+        ----------
+        klass : class or instance
+            The object that forms the basis for the traitlet.  If an instance
+            values must have isinstance(value, type(instance)).
+        args : tuple
+            Positional arguments for generating the default value.
+        kw : dict
+            Keyword arguments for generating the default value.
+        allow_none : bool
+            Indicates whether None is allowed as a value.
+
+        Default Value
+        -------------
+        If klass is an instance, default value is None.  If klass is a class
+        then the default value is obtained by calling ``klass(*args, **kw)``.
+        If klass is a str, it is first resolved to an actual class and then
+        instantiated with ``klass(*args, **kw)``.
+        """
+
+        self._allow_none = allow_none
+        self.module      = module or get_module_name()
+
+        if klass is None:
+            raise TraitletError('A %s traitlet must have a class specified.' %
+                                self.__class__.__name__ )
+        elif not isinstance(klass, (basestring,) + ClassTypes ):
+            # klass is an instance so default value will be None
+            self.klass = klass.__class__
+            default_value = None
+        else:
+            # klass is a str or class so we handle args, kw
+            if args is None:
+                args = ()
+            if kw is None:
+                if isinstance(args, dict):
+                    kw = args
+                    args = ()
+                else:
+                    kw = {}
+            if not isinstance(kw, dict):
+                raise TraitletError("The 'kw' argument must be a dict.")
+            if not isinstance(args, tuple):
+                raise TraitletError("The 'args' argument must be a tuple.")
+            self.klass = klass
+            # This tells my get_default_value that the default value
+            # instance needs to be generated when it is called.  This 
+            # is usually when TraitletType.__get__ is called for the 1st time.
+            
+            default_value = DefaultValueGenerator(klass, *args, **kw)
+
+        super(Instance, self).__init__(default_value, **metadata)
+
+    def validate(self, obj, value):
+        if value is None:
+            if self._allow_none:
+                return value
+            self.validate_failed(obj, value)
+
+        # This is where self.klass is turned into a real class if it was
+        # a str initially.  This happens the first time TraitletType.__set__
+        # is called.  This does happen if a default value is generated by
+        # TraitletType.__get__.
+        if isinstance(self.klass, basestring):
+            self.resolve_class(obj, value)
+
+        if isinstance(value, self.klass):
+            return value
+        else:
+            self.validate_failed(obj, value)
+
+    def info ( self ):
+        klass = self.klass
+        if not isinstance( klass, basestring ):
+            klass = klass.__name__
+        result = class_of(klass)
+        if self._allow_none:
+            return result + ' or None'
+
+        return result
+
+    def get_default_value ( self ):
+        """Instantiate a default value instance.
+        
+        When TraitletType.__get__ is called the first time, this is called
+        (if no value has been assigned) to get a default value instance.
+        """
+        dv  = self.default_value
+        if isinstance(dv, DefaultValueGenerator):
+            klass = dv.klass
+            args = dv.args
+            kw = dv.kw
+            if isinstance(klass, basestring):
+                klass = self.validate_class(self.find_class(klass))
+                if klass is None:
+                    raise TraitletError('Unable to locate class: ' + dv.klass)
+            return klass(*args, **kw)
+        else:
+            return dv
+
+
+#-----------------------------------------------------------------------------
+# Basic TraitletTypes implementations/subclasses
+#-----------------------------------------------------------------------------
+
 
 class Any(TraitletType):
     default_value = None
     info_text = 'any value'
 
 
 class Int(TraitletType):
 
     evaluate = int
     default_value = 0
     info_text = 'an integer'
 
     def validate(self, obj, value):
         if isinstance(value, int):
             return value
         self.error(obj, value)
 
 
 class Long(TraitletType):
 
     evaluate = long
     default_value = 0L
     info_text = 'a long'
 
     def validate(self, obj, value):
         if isinstance(value, long):
             return value
         if isinstance(value, int):
             return long(value)
         self.error(obj, value)
 
 
 class Float(TraitletType):
 
     evaluate = float
     default_value = 0.0
     info_text = 'a float'
 
     def validate(self, obj, value):
         if isinstance(value, float):
             return value
         if isinstance(value, int):
             return float(value)
         self.error(obj, value)
 
 
 class Complex(TraitletType):
 
     evaluate = complex
     default_value = 0.0 + 0.0j
     info_text = 'a complex number'
 
     def validate(self, obj, value):
         if isinstance(value, complex):
             return value
         if isinstance(value, (float, int)):
             return complex(value)
         self.error(obj, value)
 
 
 class Str(TraitletType):
 
     evaluate = lambda x: x
     default_value = ''
     info_text = 'a string'
 
     def validate(self, obj, value):
         if isinstance(value, str):
             return value
         self.error(obj, value)
 
 
 class Unicode(TraitletType):
 
     evaluate = unicode
     default_value = u''
     info_text = 'a unicode string'
 
     def validate(self, obj, value):
         if isinstance(value, unicode):
             return value
         if isinstance(value, str):
             return unicode(value)
         self.error(obj, value)
 
 
 class Bool(TraitletType):
 
     evaluate = bool
     default_value = False
     info_text = 'a boolean'
 
     def validate(self, obj, value):
         if isinstance(value, bool):
             return value
         self.error(obj, value)