fix handling of unicode in KV loader

CaselessStrEnum had to be updated to typecheck basestring instead of str

tests included

IPython/config/loader.py

@@ -1,541 +1,555 b''
 """A simple configuration system.
 
 Authors
 -------
 * Brian Granger
 * Fernando Perez
 * Min RK
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  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 __builtin__
 import re
 import sys
 
 from IPython.external import argparse
 from IPython.utils.path import filefind, get_ipython_dir
 
 #-----------------------------------------------------------------------------
 # Exceptions
 #-----------------------------------------------------------------------------
 
 
 class ConfigError(Exception):
     pass
 
 
 class ConfigLoaderError(ConfigError):
     pass
 
 class ArgumentError(ConfigLoaderError):
     pass
 
 #-----------------------------------------------------------------------------
 # Argparse fix
 #-----------------------------------------------------------------------------
 
 # Unfortunately argparse by default prints help messages to stderr instead of
 # stdout.  This makes it annoying to capture long help screens at the command
 # line, since one must know how to pipe stderr, which many users don't know how
 # to do.  So we override the print_help method with one that defaults to
 # stdout and use our class instead.
 
 class ArgumentParser(argparse.ArgumentParser):
     """Simple argparse subclass that prints help to stdout by default."""
     
     def print_help(self, file=None):
         if file is None:
             file = sys.stdout
         return super(ArgumentParser, self).print_help(file)
     
     print_help.__doc__ = argparse.ArgumentParser.print_help.__doc__
     
 #-----------------------------------------------------------------------------
 # Config class for holding config information
 #-----------------------------------------------------------------------------
 
 
 class Config(dict):
     """An attribute based dict that can do smart merges."""
 
     def __init__(self, *args, **kwds):
         dict.__init__(self, *args, **kwds)
         # This sets self.__dict__ = self, but it has to be done this way
         # because we are also overriding __setattr__.
         dict.__setattr__(self, '__dict__', self)
 
     def _merge(self, other):
         to_update = {}
         for k, v in other.iteritems():
             if not self.has_key(k):
                 to_update[k] = v
             else: # I have this key
                 if isinstance(v, Config):
                     # Recursively merge common sub Configs
                     self[k]._merge(v)
                 else:
                     # Plain updates for non-Configs
                     to_update[k] = v
 
         self.update(to_update)
 
     def _is_section_key(self, key):
         if key[0].upper()==key[0] and not key.startswith('_'):
             return True
         else:
             return False
 
     def __contains__(self, key):
         if self._is_section_key(key):
             return True
         else:
             return super(Config, self).__contains__(key)
     # .has_key is deprecated for dictionaries.
     has_key = __contains__
 
     def _has_section(self, key):
         if self._is_section_key(key):
             if super(Config, self).__contains__(key):
                 return True
         return False
 
     def copy(self):
         return type(self)(dict.copy(self))
 
     def __copy__(self):
         return self.copy()
 
     def __deepcopy__(self, memo):
         import copy
         return type(self)(copy.deepcopy(self.items()))
 
     def __getitem__(self, key):
         # We cannot use directly self._is_section_key, because it triggers
         # infinite recursion on top of PyPy. Instead, we manually fish the
         # bound method.
         is_section_key = self.__class__._is_section_key.__get__(self)
         
         # Because we use this for an exec namespace, we need to delegate
         # the lookup of names in __builtin__ to itself.  This means
         # that you can't have section or attribute names that are 
         # builtins.
         try:
             return getattr(__builtin__, key)
         except AttributeError:
             pass
         if is_section_key(key):
             try:
                 return dict.__getitem__(self, key)
             except KeyError:
                 c = Config()
                 dict.__setitem__(self, key, c)
                 return c
         else:
             return dict.__getitem__(self, key)
 
     def __setitem__(self, key, value):
         # Don't allow names in __builtin__ to be modified.
         if hasattr(__builtin__, key):
             raise ConfigError('Config variable names cannot have the same name '
                               'as a Python builtin: %s' % key)
         if self._is_section_key(key):
             if not isinstance(value, Config):
                 raise ValueError('values whose keys begin with an uppercase '
                                  'char must be Config instances: %r, %r' % (key, value))
         else:
             dict.__setitem__(self, key, value)
 
     def __getattr__(self, key):
         try:
             return self.__getitem__(key)
         except KeyError, e:
             raise AttributeError(e)
 
     def __setattr__(self, key, value):
         try:
             self.__setitem__(key, value)
         except KeyError, e:
             raise AttributeError(e)
 
     def __delattr__(self, key):
         try:
             dict.__delitem__(self, key)
         except KeyError, e:
             raise AttributeError(e)
 
 
 #-----------------------------------------------------------------------------
 # Config loading classes
 #-----------------------------------------------------------------------------
 
 
 class ConfigLoader(object):
     """A object for loading configurations from just about anywhere.
     
     The resulting configuration is packaged as a :class:`Struct`.
     
     Notes
     -----
     A :class:`ConfigLoader` does one thing: load a config from a source 
     (file, command line arguments) and returns the data as a :class:`Struct`.
     There are lots of things that :class:`ConfigLoader` does not do.  It does
     not implement complex logic for finding config files.  It does not handle
     default values or merge multiple configs.  These things need to be 
     handled elsewhere.
     """
 
     def __init__(self):
         """A base class for config loaders.
         
         Examples
         --------
         
         >>> cl = ConfigLoader()
         >>> config = cl.load_config()
         >>> config
         {}
         """
         self.clear()
 
     def clear(self):
         self.config = Config()
 
     def load_config(self):
         """Load a config from somewhere, return a :class:`Config` instance.
         
         Usually, this will cause self.config to be set and then returned.
         However, in most cases, :meth:`ConfigLoader.clear` should be called
         to erase any previous state.
         """
         self.clear()
         return self.config
 
 
 class FileConfigLoader(ConfigLoader):
     """A base class for file based configurations.
 
     As we add more file based config loaders, the common logic should go
     here.
     """
     pass
 
 
 class PyFileConfigLoader(FileConfigLoader):
     """A config loader for pure python files.
     
     This calls execfile on a plain python file and looks for attributes
     that are all caps.  These attribute are added to the config Struct.
     """
 
     def __init__(self, filename, path=None):
         """Build a config loader for a filename and path.
 
         Parameters
         ----------
         filename : str
             The file name of the config file.
         path : str, list, tuple
             The path to search for the config file on, or a sequence of
             paths to try in order.
         """
         super(PyFileConfigLoader, self).__init__()
         self.filename = filename
         self.path = path
         self.full_filename = ''
         self.data = None
 
     def load_config(self):
         """Load the config from a file and return it as a Struct."""
         self.clear()
         self._find_file()
         self._read_file_as_dict()
         self._convert_to_config()
         return self.config
 
     def _find_file(self):
         """Try to find the file by searching the paths."""
         self.full_filename = filefind(self.filename, self.path)
 
     def _read_file_as_dict(self):
         """Load the config file into self.config, with recursive loading."""
         # This closure is made available in the namespace that is used
         # to exec the config file.  It allows users to call
         # load_subconfig('myconfig.py') to load config files recursively.
         # It needs to be a closure because it has references to self.path
         # and self.config.  The sub-config is loaded with the same path
         # as the parent, but it uses an empty config which is then merged
         # with the parents.
         
         # If a profile is specified, the config file will be loaded
         # from that profile
         
         def load_subconfig(fname, profile=None):
             # import here to prevent circular imports
             from IPython.core.profiledir import ProfileDir, ProfileDirError
             if profile is not None:
                 try:
                     profile_dir = ProfileDir.find_profile_dir_by_name(
                             get_ipython_dir(),
                             profile,
                     )
                 except ProfileDirError:
                     return
                 path = profile_dir.location
             else:
                 path = self.path
             loader = PyFileConfigLoader(fname, path)
             try:
                 sub_config = loader.load_config()
             except IOError:
                 # Pass silently if the sub config is not there. This happens
                 # when a user s using a profile, but not the default config.
                 pass
             else:
                 self.config._merge(sub_config)
         
         # Again, this needs to be a closure and should be used in config
         # files to get the config being loaded.
         def get_config():
             return self.config
 
         namespace = dict(load_subconfig=load_subconfig, get_config=get_config)
         fs_encoding = sys.getfilesystemencoding() or 'ascii'
         conf_filename = self.full_filename.encode(fs_encoding)
         execfile(conf_filename, namespace)
 
     def _convert_to_config(self):
         if self.data is None:
             ConfigLoaderError('self.data does not exist')
 
 
 class CommandLineConfigLoader(ConfigLoader):
     """A config loader for command line arguments.
 
     As we add more command line based loaders, the common logic should go
     here.
     """
 
 kv_pattern = re.compile(r'[A-Za-z]\w*(\.\w+)*\=.*')
 flag_pattern = re.compile(r'\-\-\w+(\-\w)*')
 
 class KeyValueConfigLoader(CommandLineConfigLoader):
     """A config loader that loads key value pairs from the command line.
 
     This allows command line options to be gives in the following form::
     
         ipython Global.profile="foo" InteractiveShell.autocall=False
     """
 
     def __init__(self, argv=None, aliases=None, flags=None):
         """Create a key value pair config loader.
 
         Parameters
         ----------
         argv : list
             A list that has the form of sys.argv[1:] which has unicode
             elements of the form u"key=value". If this is None (default),
             then sys.argv[1:] will be used.
         aliases : dict
             A dict of aliases for configurable traits.
             Keys are the short aliases, Values are the resolved trait.
             Of the form: `{'alias' : 'Configurable.trait'}`
         flags : dict
             A dict of flags, keyed by str name. Vaues can be Config objects,
             dicts, or "key=value" strings.  If Config or dict, when the flag
             is triggered, The flag is loaded as `self.config.update(m)`.
 
         Returns
         -------
         config : Config
             The resulting Config object.
 
         Examples
         --------
 
             >>> from IPython.config.loader import KeyValueConfigLoader
             >>> cl = KeyValueConfigLoader()
             >>> cl.load_config(["foo='bar'","A.name='brian'","B.number=0"])
             {'A': {'name': 'brian'}, 'B': {'number': 0}, 'foo': 'bar'}
         """
         self.clear()
         if argv is None:
             argv = sys.argv[1:]
         self.argv = argv
         self.aliases = aliases or {}
         self.flags = flags or {}
         
     
     def clear(self):
         super(KeyValueConfigLoader, self).clear()
         self.extra_args = []
         
-
+    
+    def _decode_argv(self, argv, enc=None):
+        """decode argv if bytes, using stin.encoding, falling back on default enc"""
+        uargv = []
+        if enc is None:
+            enc = sys.stdin.encoding or sys.getdefaultencoding()
+        for arg in argv:
+            if not isinstance(arg, unicode):
+                # only decode if not already decoded
+                arg = arg.decode(enc)
+            uargv.append(arg)
+        return uargv
+                
+                
     def load_config(self, argv=None, aliases=None, flags=None):
         """Parse the configuration and generate the Config object.
         
         After loading, any arguments that are not key-value or
         flags will be stored in self.extra_args - a list of
         unparsed command-line arguments.  This is used for
         arguments such as input files or subcommands.
         
         Parameters
         ----------
         argv : list, optional
             A list that has the form of sys.argv[1:] which has unicode
             elements of the form u"key=value". If this is None (default),
             then self.argv will be used.
         aliases : dict
             A dict of aliases for configurable traits.
             Keys are the short aliases, Values are the resolved trait.
             Of the form: `{'alias' : 'Configurable.trait'}`
         flags : dict
             A dict of flags, keyed by str name. Values can be Config objects
             or dicts.  When the flag is triggered, The config is loaded as 
             `self.config.update(cfg)`.
         """
         from IPython.config.configurable import Configurable
 
         self.clear()
         if argv is None:
             argv = self.argv
         if aliases is None:
             aliases = self.aliases
         if flags is None:
             flags = self.flags
         
-        for item in argv:
+        for item in self._decode_argv(argv):
             if kv_pattern.match(item):
                 lhs,rhs = item.split('=',1)
                 # Substitute longnames for aliases.
                 if lhs in aliases:
                     lhs = aliases[lhs]
                 exec_str = 'self.config.' + lhs + '=' + rhs
                 try:
                     # Try to see if regular Python syntax will work. This
                     # won't handle strings as the quote marks are removed
                     # by the system shell.
                     exec exec_str in locals(), globals()
                 except (NameError, SyntaxError):
                     # This case happens if the rhs is a string but without
-                    # the quote marks.  We add the quote marks and see if
+                    # the quote marks. Use repr, to get quote marks, and
+                    # 'u' prefix and see if
                     # it succeeds. If it still fails, we let it raise.
-                    exec_str = 'self.config.' + lhs + '="' + rhs + '"'
+                    exec_str = u'self.config.' + lhs + '=' + repr(rhs)
                     exec exec_str in locals(), globals()
             elif flag_pattern.match(item):
                 # trim leading '--'
                 m = item[2:]
                 cfg,_ = flags.get(m, (None,None))
                 if cfg is None:
                     raise ArgumentError("Unrecognized flag: %r"%item)
                 elif isinstance(cfg, (dict, Config)):
                     # don't clobber whole config sections, update
                     # each section from config:
                     for sec,c in cfg.iteritems():
                         self.config[sec].update(c)
                 else:
                     raise ValueError("Invalid flag: %r"%flag)
             elif item.startswith('-'):
                 # this shouldn't ever be valid
                 raise ArgumentError("Invalid argument: %r"%item)
             else:
                 # keep all args that aren't valid in a list, 
                 # in case our parent knows what to do with them.
                 self.extra_args.append(item)
         return self.config
 
 class ArgParseConfigLoader(CommandLineConfigLoader):
     """A loader that uses the argparse module to load from the command line."""
 
     def __init__(self, argv=None, *parser_args, **parser_kw):
         """Create a config loader for use with argparse.
 
         Parameters
         ----------
 
         argv : optional, list
           If given, used to read command-line arguments from, otherwise
           sys.argv[1:] is used.
 
         parser_args : tuple
           A tuple of positional arguments that will be passed to the
           constructor of :class:`argparse.ArgumentParser`.
 
         parser_kw : dict
           A tuple of keyword arguments that will be passed to the
           constructor of :class:`argparse.ArgumentParser`.
 
         Returns
         -------
         config : Config
             The resulting Config object.
         """
         super(CommandLineConfigLoader, self).__init__()
         if argv == None:
             argv = sys.argv[1:]
         self.argv = argv
         self.parser_args = parser_args
         self.version = parser_kw.pop("version", None)
         kwargs = dict(argument_default=argparse.SUPPRESS)
         kwargs.update(parser_kw)
         self.parser_kw = kwargs
 
     def load_config(self, argv=None):
         """Parse command line arguments and return as a Config object.
 
         Parameters
         ----------
 
         args : optional, list
           If given, a list with the structure of sys.argv[1:] to parse
           arguments from. If not given, the instance's self.argv attribute
           (given at construction time) is used."""
         self.clear()
         if argv is None:
             argv = self.argv
         self._create_parser()
         self._parse_args(argv)
         self._convert_to_config()
         return self.config
 
     def get_extra_args(self):
         if hasattr(self, 'extra_args'):
             return self.extra_args
         else:
             return []
 
     def _create_parser(self):
         self.parser = ArgumentParser(*self.parser_args, **self.parser_kw)
         self._add_arguments()
 
     def _add_arguments(self):
         raise NotImplementedError("subclasses must implement _add_arguments")
 
     def _parse_args(self, args):
         """self.parser->self.parsed_data"""
         # decode sys.argv to support unicode command-line options
         uargs = []
         for a in args:
             if isinstance(a, str):
                 # don't decode if we already got unicode
                 a = a.decode(sys.stdin.encoding or 
                                             sys.getdefaultencoding())
             uargs.append(a)
         self.parsed_data, self.extra_args = self.parser.parse_known_args(uargs)
 
     def _convert_to_config(self):
         """self.parsed_data->self.config"""
         for k, v in vars(self.parsed_data).iteritems():
             exec_str = 'self.config.' + k + '= v'
             exec exec_str in locals(), globals()
 
 

IPython/config/tests/test_loader.py

@@ -1,197 +1,217 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 Tests for IPython.config.loader
 
 Authors:
 
 * Brian Granger
 * Fernando Perez (design help)
 """
 
 #-----------------------------------------------------------------------------
 #  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 os
+import sys
 from tempfile import mkstemp
 from unittest import TestCase
 
+from nose import SkipTest
+
 from IPython.utils.traitlets import Int, Unicode
 from IPython.config.configurable import Configurable
 from IPython.config.loader import (
     Config,
     PyFileConfigLoader,
     KeyValueConfigLoader,
     ArgParseConfigLoader,
     ConfigError
 )
 
 #-----------------------------------------------------------------------------
 # Actual tests
 #-----------------------------------------------------------------------------
 
 
 pyfile = """
 c = get_config()
 c.a=10
 c.b=20
 c.Foo.Bar.value=10
 c.Foo.Bam.value=range(10)
 c.D.C.value='hi there'
 """
 
 class TestPyFileCL(TestCase):
 
     def test_basic(self):
         fd, fname = mkstemp('.py')
         f = os.fdopen(fd, 'w')
         f.write(pyfile)
         f.close()
         # Unlink the file
         cl = PyFileConfigLoader(fname)
         config = cl.load_config()
         self.assertEquals(config.a, 10)
         self.assertEquals(config.b, 20)
         self.assertEquals(config.Foo.Bar.value, 10)
         self.assertEquals(config.Foo.Bam.value, range(10))
         self.assertEquals(config.D.C.value, 'hi there')
 
 class MyLoader1(ArgParseConfigLoader):
     def _add_arguments(self):
         p = self.parser
         p.add_argument('-f', '--foo', dest='Global.foo', type=str)
         p.add_argument('-b', dest='MyClass.bar', type=int)
         p.add_argument('-n', dest='n', action='store_true')
         p.add_argument('Global.bam', type=str)
 
 class MyLoader2(ArgParseConfigLoader):
     def _add_arguments(self):
         subparsers = self.parser.add_subparsers(dest='subparser_name')
         subparser1 = subparsers.add_parser('1')
         subparser1.add_argument('-x',dest='Global.x')
         subparser2 = subparsers.add_parser('2')
         subparser2.add_argument('y')
 
 class TestArgParseCL(TestCase):
 
     def test_basic(self):
         cl = MyLoader1()
         config = cl.load_config('-f hi -b 10 -n wow'.split())
         self.assertEquals(config.Global.foo, 'hi')
         self.assertEquals(config.MyClass.bar, 10)
         self.assertEquals(config.n, True)
         self.assertEquals(config.Global.bam, 'wow')
         config = cl.load_config(['wow'])
         self.assertEquals(config.keys(), ['Global'])
         self.assertEquals(config.Global.keys(), ['bam'])
         self.assertEquals(config.Global.bam, 'wow')
 
     def test_add_arguments(self):
         cl = MyLoader2()
         config = cl.load_config('2 frobble'.split())
         self.assertEquals(config.subparser_name, '2')
         self.assertEquals(config.y, 'frobble')
         config = cl.load_config('1 -x frobble'.split())
         self.assertEquals(config.subparser_name, '1')
         self.assertEquals(config.Global.x, 'frobble')
 
     def test_argv(self):
         cl = MyLoader1(argv='-f hi -b 10 -n wow'.split())
         config = cl.load_config()
         self.assertEquals(config.Global.foo, 'hi')
         self.assertEquals(config.MyClass.bar, 10)
         self.assertEquals(config.n, True)
         self.assertEquals(config.Global.bam, 'wow')
 
 
 class TestKeyValueCL(TestCase):
 
     def test_basic(self):
         cl = KeyValueConfigLoader()
         argv = [s.strip('c.') for s in pyfile.split('\n')[2:-1]]
         config = cl.load_config(argv)
         self.assertEquals(config.a, 10)
         self.assertEquals(config.b, 20)
         self.assertEquals(config.Foo.Bar.value, 10)
         self.assertEquals(config.Foo.Bam.value, range(10))
         self.assertEquals(config.D.C.value, 'hi there')
     
     def test_extra_args(self):
         cl = KeyValueConfigLoader()
         config = cl.load_config(['a=5', 'b', 'c=10', 'd'])
         self.assertEquals(cl.extra_args, ['b', 'd'])
         self.assertEquals(config.a, 5)
         self.assertEquals(config.c, 10)
+    
+    def test_unicode_args(self):
+        cl = KeyValueConfigLoader()
+        argv = [u'a=épsîlön']
+        config = cl.load_config(argv)
+        self.assertEquals(config.a, u'épsîlön')
+    
+    def test_unicode_bytes_args(self):
+        uarg = u'a=é'
+        try:
+            barg = uarg.encode(sys.stdin.encoding)
+        except (TypeError, UnicodeEncodeError):
+            raise SkipTest("sys.stdin.encoding can't handle 'é'")
+        
+        cl = KeyValueConfigLoader()
+        config = cl.load_config([barg])
+        self.assertEquals(config.a, u'é')
 
 
 class TestConfig(TestCase):
 
     def test_setget(self):
         c = Config()
         c.a = 10
         self.assertEquals(c.a, 10)
         self.assertEquals(c.has_key('b'), False)
 
     def test_auto_section(self):
         c = Config()
         self.assertEquals(c.has_key('A'), True)
         self.assertEquals(c._has_section('A'), False)
         A = c.A
         A.foo = 'hi there'
         self.assertEquals(c._has_section('A'), True)
         self.assertEquals(c.A.foo, 'hi there')
         del c.A
         self.assertEquals(len(c.A.keys()),0)
 
     def test_merge_doesnt_exist(self):
         c1 = Config()
         c2 = Config()
         c2.bar = 10
         c2.Foo.bar = 10
         c1._merge(c2)
         self.assertEquals(c1.Foo.bar, 10)
         self.assertEquals(c1.bar, 10)
         c2.Bar.bar = 10
         c1._merge(c2)
         self.assertEquals(c1.Bar.bar, 10)
 
     def test_merge_exists(self):
         c1 = Config()
         c2 = Config()
         c1.Foo.bar = 10
         c1.Foo.bam = 30
         c2.Foo.bar = 20
         c2.Foo.wow = 40
         c1._merge(c2)
         self.assertEquals(c1.Foo.bam, 30)
         self.assertEquals(c1.Foo.bar, 20)
         self.assertEquals(c1.Foo.wow, 40)
         c2.Foo.Bam.bam = 10
         c1._merge(c2)
         self.assertEquals(c1.Foo.Bam.bam, 10)
 
     def test_deepcopy(self):
         c1 = Config()
         c1.Foo.bar = 10
         c1.Foo.bam = 30
         c1.a = 'asdf'
         c1.b = range(10)
         import copy
         c2 = copy.deepcopy(c1)
         self.assertEquals(c1, c2)
         self.assert_(c1 is not c2)
         self.assert_(c1.Foo is not c2.Foo)
 
     def test_builtin(self):
         c1 = Config()
         exec 'foo = True' in c1
         self.assertEquals(c1.foo, True)
         self.assertRaises(ConfigError, setattr, c1, 'ValueError', 10)

IPython/utils/traitlets.py

@@ -1,1397 +1,1397 b''
 #!/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.  Most importantly, we don't provide container
   traits (list, dict, tuple) that can trigger notifications if their
   contents change.
 * API compatibility with enthought.traits
 
 There are also some important difference in our design:
 
 * enthought.traits does not validate default values.  We do.
 
 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 re
 import sys
 import types
 from types import (
     InstanceType, ClassType, FunctionType,
     ListType, TupleType
 )
 from .importstring import import_item
 
 ClassTypes = (ClassType, type)
 
 SequenceTypes = (ListType, TupleType, set, frozenset)
 
 #-----------------------------------------------------------------------------
 # Basic classes
 #-----------------------------------------------------------------------------
 
 
 class NoDefaultSpecified ( object ): pass
 NoDefaultSpecified = NoDefaultSpecified()
 
 
 class Undefined ( object ): pass
 Undefined = Undefined()
 
 class TraitError(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)
     ['anytrait']
     """
     if isinstance(name, str):
         return [name]
     elif name is None:
         return ['anytrait']
     elif isinstance(name, (list, tuple)):
         for n in name:
             assert isinstance(n, str), "names must be strings"
         return name
 
 
 class _SimpleTest:
     def __init__ ( self, value ): self.value = value
     def __call__ ( self, test  ):
         return test == self.value
     def __repr__(self):
         return "<SimpleTest(%r)" % self.value
     def __str__(self):
         return self.__repr__()
 
 
 def getmembers(object, predicate=None):
     """A safe version of inspect.getmembers that handles missing attributes.
 
     This is useful when there are descriptor based attributes that for 
     some reason raise AttributeError even though they exist.  This happens
     in zope.inteface with the __provides__ attribute.
     """
     results = []
     for key in dir(object):
         try:
             value = getattr(object, key)
         except AttributeError:
             pass
         else:
             if not predicate or predicate(value):
                 results.append((key, value))
     results.sort()
     return results
 
 
 #-----------------------------------------------------------------------------
 # Base TraitType for all traits
 #-----------------------------------------------------------------------------
 
 
 class TraitType(object):
     """A base class for all trait descriptors.
 
     Notes
     -----
     Our implementation of traits is based on Python's descriptor
     prototol.  This class is the base class for all such descriptors.  The
     only magic we use is a custom metaclass for the main :class:`HasTraits`
     class that does the following:
 
     1. Sets the :attr:`name` attribute of every :class:`TraitType`
        instance in the class dict to the name of the attribute.
     2. Sets the :attr:`this_class` attribute of every :class:`TraitType`
        instance in the class dict to the *class* that declared the trait.
        This is used by the :class:`This` trait to allow subclasses to
        accept superclasses for :class:`This` values.
     """
     
 
     metadata = {}
     default_value = Undefined
     info_text = 'any value'
 
     def __init__(self, default_value=NoDefaultSpecified, **metadata):
         """Create a TraitType.
         """
         if default_value is not NoDefaultSpecified:
             self.default_value = default_value
 
         if len(metadata) > 0:
             if len(self.metadata) > 0:
                 self._metadata = self.metadata.copy()
                 self._metadata.update(metadata)
             else:
                 self._metadata = metadata
         else:
             self._metadata = self.metadata
 
         self.init()
 
     def init(self):
         pass
 
     def get_default_value(self):
         """Create a new instance of the default value."""
         return self.default_value
 
     def instance_init(self, obj):
         """This is called by :meth:`HasTraits.__new__` to finish init'ing.
 
         Some stages of initialization must be delayed until the parent
         :class:`HasTraits` instance has been created.  This method is
         called in :meth:`HasTraits.__new__` after the instance has been
         created.
 
         This method trigger the creation and validation of default values
         and also things like the resolution of str given class names in 
         :class:`Type` and :class`Instance`.
 
         Parameters
         ----------
         obj : :class:`HasTraits` instance
             The parent :class:`HasTraits` instance that has just been
             created.
         """
         self.set_default_value(obj)
 
     def set_default_value(self, obj):
         """Set the default value on a per instance basis.
 
         This method is called by :meth:`instance_init` to create and
         validate the default value.  The creation and validation of 
         default values must be delayed until the parent :class:`HasTraits`
         class has been instantiated.
         """
         # Check for a deferred initializer defined in the same class as the
         # trait declaration or above.
         mro = type(obj).mro()
         meth_name = '_%s_default' % self.name
         for cls in mro[:mro.index(self.this_class)+1]:
             if meth_name in cls.__dict__:
                 break
         else:
             # We didn't find one. Do static initialization.
             dv = self.get_default_value()
             newdv = self._validate(obj, dv)
             obj._trait_values[self.name] = newdv
             return
         # Complete the dynamic initialization.
         obj._trait_dyn_inits[self.name] = cls.__dict__[meth_name]
 
     def __get__(self, obj, cls=None):
         """Get the value of the trait by self.name for the instance.
 
         Default values are instantiated when :meth:`HasTraits.__new__`
         is called.  Thus by the time this method gets called either the 
         default value or a user defined value (they called :meth:`__set__`)
         is in the :class:`HasTraits` instance.
         """
         if obj is None:
             return self
         else:
             try:
                 value = obj._trait_values[self.name]
             except KeyError:
                 # Check for a dynamic initializer.
                 if self.name in obj._trait_dyn_inits:
                     value = obj._trait_dyn_inits[self.name](obj)
                     # FIXME: Do we really validate here?
                     value = self._validate(obj, value)
                     obj._trait_values[self.name] = value
                     return value
                 else:
                     raise TraitError('Unexpected error in TraitType: '
                         'both default value and dynamic initializer are '
                         'absent.')
             except Exception:
                 # HasTraits should call set_default_value to populate
                 # this.  So this should never be reached.
                 raise TraitError('Unexpected error in TraitType: '
                                     'default value not set properly')
             else:
                 return value
 
     def __set__(self, obj, value):
         new_value = self._validate(obj, value)
         old_value = self.__get__(obj)
         if old_value != new_value:
             obj._trait_values[self.name] = new_value
             obj._notify_trait(self.name, old_value, new_value)
 
     def _validate(self, obj, value):
         if hasattr(self, 'validate'):
             return self.validate(obj, value)
         elif hasattr(self, 'is_valid_for'):
             valid = self.is_valid_for(value)
             if valid:
                 return value
             else:
                 raise TraitError('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' trait 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' trait must be %s, but a value of %r was specified." \
                 % (self.name, self.info(), repr_type(value))
         raise TraitError(e)
 
     def get_metadata(self, key):
         return getattr(self, '_metadata', {}).get(key, None)
 
     def set_metadata(self, key, value):
         getattr(self, '_metadata', {})[key] = value
 
 
 #-----------------------------------------------------------------------------
 # The HasTraits implementation
 #-----------------------------------------------------------------------------
 
 
 class MetaHasTraits(type):
     """A metaclass for HasTraits.
     
     This metaclass makes sure that any TraitType class attributes are
     instantiated and sets their name attribute.
     """
     
     def __new__(mcls, name, bases, classdict):
         """Create the HasTraits class.
         
         This instantiates all TraitTypes in the class dict and sets their
         :attr:`name` attribute.
         """
         # print "MetaHasTraitlets (mcls, name): ", mcls, name
         # print "MetaHasTraitlets (bases): ", bases
         # print "MetaHasTraitlets (classdict): ", classdict
         for k,v in classdict.iteritems():
             if isinstance(v, TraitType):
                 v.name = k
             elif inspect.isclass(v):
                 if issubclass(v, TraitType):
                     vinst = v()
                     vinst.name = k
                     classdict[k] = vinst
         return super(MetaHasTraits, mcls).__new__(mcls, name, bases, classdict)
 
     def __init__(cls, name, bases, classdict):
         """Finish initializing the HasTraits class.
         
         This sets the :attr:`this_class` attribute of each TraitType in the
         class dict to the newly created class ``cls``.
         """
         for k, v in classdict.iteritems():
             if isinstance(v, TraitType):
                 v.this_class = cls
         super(MetaHasTraits, cls).__init__(name, bases, classdict)
 
 class HasTraits(object):
 
     __metaclass__ = MetaHasTraits
 
     def __new__(cls, **kw):
         # This is needed because in Python 2.6 object.__new__ only accepts
         # the cls argument.
         new_meth = super(HasTraits, cls).__new__
         if new_meth is object.__new__:
             inst = new_meth(cls)
         else:
             inst = new_meth(cls, **kw)
         inst._trait_values = {}
         inst._trait_notifiers = {}
         inst._trait_dyn_inits = {}
         # Here we tell all the TraitType instances to set their default
         # values on the instance. 
         for key in dir(cls):
             # Some descriptors raise AttributeError like zope.interface's
             # __provides__ attributes even though they exist.  This causes
             # AttributeErrors even though they are listed in dir(cls).
             try:
                 value = getattr(cls, key)
             except AttributeError:
                 pass
             else:
                 if isinstance(value, TraitType):
                     value.instance_init(inst)
 
         return inst
 
     def __init__(self, **kw):
         # Allow trait values to be set using keyword arguments.
         # We need to use setattr for this to trigger validation and
         # notifications.
         for key, value in kw.iteritems():
             setattr(self, key, value)
 
     def _notify_trait(self, name, old_value, new_value):
 
         # First dynamic ones
         callables = self._trait_notifiers.get(name,[])
         more_callables = self._trait_notifiers.get('anytrait',[])
         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 TraitError('a trait changed callback '
                                         'must have 0-3 arguments.')
             else:
                 raise TraitError('a trait changed callback '
                                     'must be callable.')
                 
 
     def _add_notifiers(self, handler, name):
         if not self._trait_notifiers.has_key(name):
             nlist = []
             self._trait_notifiers[name] = nlist
         else:
             nlist = self._trait_notifiers[name]
         if handler not in nlist:
             nlist.append(handler)
 
     def _remove_notifiers(self, handler, name):
         if self._trait_notifiers.has_key(name):
             nlist = self._trait_notifiers[name]
             try:
                 index = nlist.index(handler)
             except ValueError:
                 pass
             else:
                 del nlist[index]
 
     def on_trait_change(self, handler, name=None, remove=False):
         """Setup a handler to be called when a trait changes.
 
         This is used to setup dynamic notifications of trait changes.
         
         Static handlers can be created by creating methods on a HasTraits
         subclass with the naming convention '_[traitname]_changed'.  Thus,
         to create static handler for the trait '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 trait 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 traits.  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)
 
     @classmethod
     def class_trait_names(cls, **metadata):
         """Get a list of all the names of this classes traits.
 
         This method is just like the :meth:`trait_names` method, but is unbound.
         """
         return cls.class_traits(**metadata).keys()
 
     @classmethod
     def class_traits(cls, **metadata):
         """Get a list of all the traits of this class.
 
         This method is just like the :meth:`traits` method, but is unbound.
 
         The TraitTypes returned don't know anything about the values
         that the various HasTrait's instances are holding.
 
         This follows the same algorithm as traits does and does not allow
         for any simple way of specifying merely that a metadata name
         exists, but has any value.  This is because get_metadata returns
         None if a metadata key doesn't exist.
         """
         traits = dict([memb for memb in getmembers(cls) if \
                      isinstance(memb[1], TraitType)])
 
         if len(metadata) == 0:
             return traits
 
         for meta_name, meta_eval in metadata.items():
             if type(meta_eval) is not FunctionType:
                 metadata[meta_name] = _SimpleTest(meta_eval)
 
         result = {}
         for name, trait in traits.items():
             for meta_name, meta_eval in metadata.items():
                 if not meta_eval(trait.get_metadata(meta_name)):
                     break
             else:
                 result[name] = trait
 
         return result
 
     def trait_names(self, **metadata):
         """Get a list of all the names of this classes traits."""
         return self.traits(**metadata).keys()
 
     def traits(self, **metadata):
         """Get a list of all the traits of this class.
 
         The TraitTypes returned don't know anything about the values
         that the various HasTrait's instances are holding.
 
         This follows the same algorithm as traits does and does not allow
         for any simple way of specifying merely that a metadata name
         exists, but has any value.  This is because get_metadata returns
         None if a metadata key doesn't exist.
         """
         traits = dict([memb for memb in getmembers(self.__class__) if \
                      isinstance(memb[1], TraitType)])
 
         if len(metadata) == 0:
             return traits
 
         for meta_name, meta_eval in metadata.items():
             if type(meta_eval) is not FunctionType:
                 metadata[meta_name] = _SimpleTest(meta_eval)
 
         result = {}
         for name, trait in traits.items():
             for meta_name, meta_eval in metadata.items():
                 if not meta_eval(trait.get_metadata(meta_name)):
                     break
             else:
                 result[name] = trait
 
         return result
 
     def trait_metadata(self, traitname, key):
         """Get metadata values for trait by key."""
         try:
             trait = getattr(self.__class__, traitname)
         except AttributeError:
             raise TraitError("Class %s does not have a trait named %s" %
                                 (self.__class__.__name__, traitname))
         else:
             return trait.get_metadata(key)
 
 #-----------------------------------------------------------------------------
 # Actual TraitTypes implementations/subclasses
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # TraitTypes subclasses for handling classes and instances of classes
 #-----------------------------------------------------------------------------
 
 
 class ClassBasedTraitType(TraitType):
     """A trait with error reporting for Type, Instance and This."""
 
     def error(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 ) )
 
         if obj is not None:
             e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \
                 % (self.name, class_of(obj),
                    self.info(), msg)
         else:
             e = "The '%s' trait must be %s, but a value of %r was specified." \
                 % (self.name, self.info(), msg)
 
         raise TraitError(e)
 
 
 class Type(ClassBasedTraitType):
     """A trait 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 trait
 
         A Type trait specifies that its values must be subclasses of
         a particular class.
 
         If only ``default_value`` is given, it is used for the ``klass`` as
         well.
 
         Parameters
         ----------
         default_value : class, str or None
             The default value must be a subclass of klass.  If an str,
             the str must be a fully specified class name, like 'foo.bar.Bah'.
             The string is resolved into real class, when the parent 
             :class:`HasTraits` class is instantiated.
         klass : class, str, None
             Values of this trait must be a subclass of klass.  The klass
             may be specified in a string like: 'foo.bar.MyClass'.
             The string is resolved into real class, when the parent 
             :class:`HasTraits` class is instantiated.
         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 not (inspect.isclass(klass) or isinstance(klass, basestring)):
             raise TraitError("A Type trait must specify a class.")
 
         self.klass       = klass
         self._allow_none = allow_none
 
         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 info(self):
         """ Returns a description of the trait."""
         if isinstance(self.klass, basestring):
             klass = self.klass
         else:
             klass = self.klass.__name__
         result = 'a subclass of ' + klass
         if self._allow_none:
             return result + ' or None'
         return result
 
     def instance_init(self, obj):
         self._resolve_classes()
         super(Type, self).instance_init(obj)
 
     def _resolve_classes(self):
         if isinstance(self.klass, basestring):
             self.klass = import_item(self.klass)
         if isinstance(self.default_value, basestring):
             self.default_value = import_item(self.default_value)
 
     def get_default_value(self):
         return self.default_value
 
 
 class DefaultValueGenerator(object):
     """A class for generating new default value instances."""
 
     def __init__(self, *args, **kw):
         self.args = args
         self.kw = kw
 
     def generate(self, klass):
         return klass(*self.args, **self.kw)
 
 
 class Instance(ClassBasedTraitType):
     """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, **metadata ):
         """Construct an Instance trait.
 
         This trait allows values that are instances of a particular
         class or its sublclasses.  Our implementation is quite different
         from that of enthough.traits as we don't allow instances to be used
         for klass and we handle the ``args`` and ``kw`` arguments differently.
 
         Parameters
         ----------
         klass : class, str
             The class that forms the basis for the trait.  Class names
             can also be specified as strings, like 'foo.bar.Bar'.
         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 both ``args`` and ``kw`` are None, then the default value is None.
         If ``args`` is a tuple and ``kw`` is a dict, then the default is
         created as ``klass(*args, **kw)``.  If either ``args`` or ``kw`` is 
         not (but not both), None is replace by ``()`` or ``{}``.
         """
 
         self._allow_none = allow_none
 
         if (klass is None) or (not (inspect.isclass(klass) or isinstance(klass, basestring))):
             raise TraitError('The klass argument must be a class'
                                 ' you gave: %r' % klass)
         self.klass = klass
         
         # self.klass is a class, so handle default_value
         if args is None and kw is None:
             default_value = None
         else:
             if args is None:
                 # kw is not None
                 args = ()
             elif kw is None:
                 # args is not None
                 kw = {}
         
             if not isinstance(kw, dict):
                 raise TraitError("The 'kw' argument must be a dict or None.")
             if not isinstance(args, tuple):
                 raise TraitError("The 'args' argument must be a tuple or None.")
             
             default_value = DefaultValueGenerator(*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.error(obj, value)
 
         if isinstance(value, self.klass):
             return value
         else:
             self.error(obj, value)
 
     def info(self):
         if isinstance(self.klass, basestring):
             klass = self.klass
         else:
             klass = self.klass.__name__
         result = class_of(klass)
         if self._allow_none:
             return result + ' or None'
 
         return result
 
     def instance_init(self, obj):
         self._resolve_classes()
         super(Instance, self).instance_init(obj)
 
     def _resolve_classes(self):
         if isinstance(self.klass, basestring):
             self.klass = import_item(self.klass)
 
     def get_default_value(self):
         """Instantiate a default value instance.
         
         This is called when the containing HasTraits classes'
         :meth:`__new__` method is called to ensure that a unique instance
         is created for each HasTraits instance.
         """
         dv  = self.default_value
         if isinstance(dv, DefaultValueGenerator):
             return dv.generate(self.klass)
         else:
             return dv
 
 
 class This(ClassBasedTraitType):
     """A trait for instances of the class containing this trait.
 
     Because how how and when class bodies are executed, the ``This``
     trait can only have a default value of None.  This, and because we 
     always validate default values, ``allow_none`` is *always* true.
     """
 
     info_text = 'an instance of the same type as the receiver or None'
 
     def __init__(self, **metadata):
         super(This, self).__init__(None, **metadata)
 
     def validate(self, obj, value):
         # What if value is a superclass of obj.__class__?  This is
         # complicated if it was the superclass that defined the This
         # trait.
         if isinstance(value, self.this_class) or (value is None):
             return value
         else:
             self.error(obj, value)
 
 
 #-----------------------------------------------------------------------------
 # Basic TraitTypes implementations/subclasses
 #-----------------------------------------------------------------------------
 
 
 class Any(TraitType):
     default_value = None
     info_text = 'any value'
 
 
 class Int(TraitType):
     """A integer trait."""
 
     default_value = 0
     info_text = 'an integer'
 
     def validate(self, obj, value):
         if isinstance(value, int):
             return value
         self.error(obj, value)
 
 class CInt(Int):
     """A casting version of the int trait."""
 
     def validate(self, obj, value):
         try:
             return int(value)
         except:
             self.error(obj, value)
 
 
 class Long(TraitType):
     """A long integer trait."""
 
     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 CLong(Long):
     """A casting version of the long integer trait."""
 
     def validate(self, obj, value):
         try:
             return long(value)
         except:
             self.error(obj, value)
 
 
 class Float(TraitType):
     """A float trait."""
 
     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 CFloat(Float):
     """A casting version of the float trait."""
 
     def validate(self, obj, value):
         try:
             return float(value)
         except:
             self.error(obj, value)
 
 class Complex(TraitType):
     """A trait for complex numbers."""
 
     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 CComplex(Complex):
     """A casting version of the complex number trait."""
 
     def validate (self, obj, value):
         try:
             return complex(value)
         except:
             self.error(obj, value)
 
 # We should always be explicit about whether we're using bytes or unicode, both
 # for Python 3 conversion and for reliable unicode behaviour on Python 2. So
 # we don't have a Str type.
 class Bytes(TraitType):
     """A trait for strings."""
 
     default_value = ''
     info_text = 'a string'
 
     def validate(self, obj, value):
         if isinstance(value, bytes):
             return value
         self.error(obj, value)
 
 
 class CBytes(Bytes):
     """A casting version of the string trait."""
 
     def validate(self, obj, value):
         try:
             return bytes(value)
         except:
             self.error(obj, value)
 
 
 class Unicode(TraitType):
     """A trait for unicode strings."""
 
     default_value = u''
     info_text = 'a unicode string'
 
     def validate(self, obj, value):
         if isinstance(value, unicode):
             return value
         if isinstance(value, bytes):
             return unicode(value)
         self.error(obj, value)
 
 
 class CUnicode(Unicode):
     """A casting version of the unicode trait."""
 
     def validate(self, obj, value):
         try:
             return unicode(value)
         except:
             self.error(obj, value)
   
             
 class ObjectName(TraitType):
     """A string holding a valid object name in this version of Python.
     
     This does not check that the name exists in any scope."""
     info_text = "a valid object identifier in Python"
 
     if sys.version_info[0] < 3:
         # Python 2:
         _name_re = re.compile(r"[a-zA-Z_][a-zA-Z0-9_]*$")
         def isidentifier(self, s):
             return bool(self._name_re.match(s))
         
         def coerce_str(self, obj, value):
             "In Python 2, coerce ascii-only unicode to str"
             if isinstance(value, unicode):
                 try:
                     return str(value)
                 except UnicodeEncodeError:
                     self.error(obj, value)
             return value
     
     else:
         # Python 3:
         isidentifier = staticmethod(lambda s: s.isidentifier())
         coerce_str = staticmethod(lambda _,s: s)
     
     def validate(self, obj, value):
         value = self.coerce_str(obj, value)
         
         if isinstance(value, str) and self.isidentifier(value):
             return value
         self.error(obj, value)
 
 class DottedObjectName(ObjectName):
     """A string holding a valid dotted object name in Python, such as A.b3._c"""
     def validate(self, obj, value):
         value = self.coerce_str(obj, value)
         
         if isinstance(value, str) and all(self.isidentifier(x) \
                                                     for x in value.split('.')):
             return value
         self.error(obj, value)
 
 
 class Bool(TraitType):
     """A boolean (True, False) trait."""
 
     default_value = False
     info_text = 'a boolean'
 
     def validate(self, obj, value):
         if isinstance(value, bool):
             return value
         self.error(obj, value)
 
 
 class CBool(Bool):
     """A casting version of the boolean trait."""
 
     def validate(self, obj, value):
         try:
             return bool(value)
         except:
             self.error(obj, value)
 
 
 class Enum(TraitType):
     """An enum that whose value must be in a given sequence."""
 
     def __init__(self, values, default_value=None, allow_none=True, **metadata):
         self.values = values
         self._allow_none = allow_none
         super(Enum, self).__init__(default_value, **metadata)
 
     def validate(self, obj, value):
         if value is None:
             if self._allow_none:
                 return value
 
         if value in self.values:
                 return value
         self.error(obj, value)
 
     def info(self):
         """ Returns a description of the trait."""
         result = 'any of ' + repr(self.values)
         if self._allow_none:
             return result + ' or None'
         return result
 
 class CaselessStrEnum(Enum):
     """An enum of strings that are caseless in validate."""
 
     def validate(self, obj, value):
         if value is None:
             if self._allow_none:
                 return value
 
-        if not isinstance(value, str):
+        if not isinstance(value, basestring):
             self.error(obj, value)
 
         for v in self.values:
             if v.lower() == value.lower():
                 return v
         self.error(obj, value)
 
 class Container(Instance):
     """An instance of a container (list, set, etc.)
 
     To be subclassed by overriding klass.
     """
     klass = None
     _valid_defaults = SequenceTypes
     _trait = None
 
     def __init__(self, trait=None, default_value=None, allow_none=True,
                 **metadata):
         """Create a container trait type from a list, set, or tuple.
 
         The default value is created by doing ``List(default_value)``,
         which creates a copy of the ``default_value``.
 
         ``trait`` can be specified, which restricts the type of elements
         in the container to that TraitType.
 
         If only one arg is given and it is not a Trait, it is taken as
         ``default_value``:
 
         ``c = List([1,2,3])``
 
         Parameters
         ----------
 
         trait : TraitType [ optional ]
             the type for restricting the contents of the Container.  If unspecified,
             types are not checked.
 
         default_value : SequenceType [ optional ]
             The default value for the Trait.  Must be list/tuple/set, and
             will be cast to the container type.
 
         allow_none : Bool [ default True ]
             Whether to allow the value to be None
 
         **metadata : any
             further keys for extensions to the Trait (e.g. config)
 
         """
         istrait = lambda t: isinstance(t, type) and issubclass(t, TraitType)
 
         # allow List([values]):
         if default_value is None and not istrait(trait):
             default_value = trait
             trait = None
 
         if default_value is None:
             args = ()
         elif isinstance(default_value, self._valid_defaults):
             args = (default_value,)
         else:
             raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value))
 
         if istrait(trait):
             self._trait = trait()
             self._trait.name = 'element'
         elif trait is not None:
             raise TypeError("`trait` must be a Trait or None, got %s"%repr_type(trait))
 
         super(Container,self).__init__(klass=self.klass, args=args,
                                   allow_none=allow_none, **metadata)
 
     def element_error(self, obj, element, validator):
         e = "Element of the '%s' trait of %s instance must be %s, but a value of %s was specified." \
             % (self.name, class_of(obj), validator.info(), repr_type(element))
         raise TraitError(e)
 
     def validate(self, obj, value):
         value = super(Container, self).validate(obj, value)
         if value is None:
             return value
 
         value = self.validate_elements(obj, value)
 
         return value
 
     def validate_elements(self, obj, value):
         validated = []
         if self._trait is None or isinstance(self._trait, Any):
             return value
         for v in value:
             try:
                 v = self._trait.validate(obj, v)
             except TraitError:
                 self.element_error(obj, v, self._trait)
             else:
                 validated.append(v)
         return self.klass(validated)
 
 
 class List(Container):
     """An instance of a Python list."""
     klass = list
 
     def __init__(self, trait=None, default_value=None, minlen=0, maxlen=sys.maxint,
                 allow_none=True, **metadata):
         """Create a List trait type from a list, set, or tuple.
 
         The default value is created by doing ``List(default_value)``,
         which creates a copy of the ``default_value``.
 
         ``trait`` can be specified, which restricts the type of elements
         in the container to that TraitType.
 
         If only one arg is given and it is not a Trait, it is taken as
         ``default_value``:
 
         ``c = List([1,2,3])``
 
         Parameters
         ----------
 
         trait : TraitType [ optional ]
             the type for restricting the contents of the Container.  If unspecified,
             types are not checked.
 
         default_value : SequenceType [ optional ]
             The default value for the Trait.  Must be list/tuple/set, and
             will be cast to the container type.
 
         minlen : Int [ default 0 ]
             The minimum length of the input list
 
         maxlen : Int [ default sys.maxint ]
             The maximum length of the input list
 
         allow_none : Bool [ default True ]
             Whether to allow the value to be None
 
         **metadata : any
             further keys for extensions to the Trait (e.g. config)
 
         """
         self._minlen = minlen
         self._maxlen = maxlen
         super(List, self).__init__(trait=trait, default_value=default_value,
                                 allow_none=allow_none, **metadata)
 
     def length_error(self, obj, value):
         e = "The '%s' trait of %s instance must be of length %i <= L <= %i, but a value of %s was specified." \
             % (self.name, class_of(obj), self._minlen, self._maxlen, value)
         raise TraitError(e)
 
     def validate_elements(self, obj, value):
         length = len(value)
         if length < self._minlen or length > self._maxlen:
             self.length_error(obj, value)
 
         return super(List, self).validate_elements(obj, value)
 
 
 class Set(Container):
     """An instance of a Python set."""
     klass = set
 
 class Tuple(Container):
     """An instance of a Python tuple."""
     klass = tuple
 
     def __init__(self, *traits, **metadata):
         """Tuple(*traits, default_value=None, allow_none=True, **medatata)
 
         Create a tuple from a list, set, or tuple.
 
         Create a fixed-type tuple with Traits:
 
         ``t = Tuple(Int, Str, CStr)``
 
         would be length 3, with Int,Str,CStr for each element.
 
         If only one arg is given and it is not a Trait, it is taken as
         default_value:
 
         ``t = Tuple((1,2,3))``
 
         Otherwise, ``default_value`` *must* be specified by keyword.
 
         Parameters
         ----------
 
         *traits : TraitTypes [ optional ]
             the tsype for restricting the contents of the Tuple.  If unspecified,
             types are not checked. If specified, then each positional argument
             corresponds to an element of the tuple.  Tuples defined with traits
             are of fixed length.
 
         default_value : SequenceType [ optional ]
             The default value for the Tuple.  Must be list/tuple/set, and
             will be cast to a tuple. If `traits` are specified, the
             `default_value` must conform to the shape and type they specify.
 
         allow_none : Bool [ default True ]
             Whether to allow the value to be None
 
         **metadata : any
             further keys for extensions to the Trait (e.g. config)
 
         """
         default_value = metadata.pop('default_value', None)
         allow_none = metadata.pop('allow_none', True)
 
         istrait = lambda t: isinstance(t, type) and issubclass(t, TraitType)
 
         # allow Tuple((values,)):
         if len(traits) == 1 and default_value is None and not istrait(traits[0]):
             default_value = traits[0]
             traits = ()
 
         if default_value is None:
             args = ()
         elif isinstance(default_value, self._valid_defaults):
             args = (default_value,)
         else:
             raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value))
 
         self._traits = []
         for trait in traits:
             t = trait()
             t.name = 'element'
             self._traits.append(t)
 
         if self._traits and default_value is None:
             # don't allow default to be an empty container if length is specified
             args = None
         super(Container,self).__init__(klass=self.klass, args=args,
                                   allow_none=allow_none, **metadata)
 
     def validate_elements(self, obj, value):
         if not self._traits:
             # nothing to validate
             return value
         if len(value) != len(self._traits):
             e = "The '%s' trait of %s instance requires %i elements, but a value of %s was specified." \
                 % (self.name, class_of(obj), len(self._traits), repr_type(value))
             raise TraitError(e)
 
         validated = []
         for t,v in zip(self._traits, value):
             try:
                 v = t.validate(obj, v)
             except TraitError:
                 self.element_error(obj, v, t)
             else:
                 validated.append(v)
         return tuple(validated)
 
 
 class Dict(Instance):
     """An instance of a Python dict."""
 
     def __init__(self, default_value=None, allow_none=True, **metadata):
         """Create a dict trait type from a dict.
 
         The default value is created by doing ``dict(default_value)``, 
         which creates a copy of the ``default_value``.
         """
         if default_value is None:
             args = ((),)
         elif isinstance(default_value, dict):
             args = (default_value,)
         elif isinstance(default_value, SequenceTypes):
             args = (default_value,)
         else:
             raise TypeError('default value of Dict was %s' % default_value)
 
         super(Dict,self).__init__(klass=dict, args=args, 
                                   allow_none=allow_none, **metadata)
 
 class TCPAddress(TraitType):
     """A trait for an (ip, port) tuple.
 
     This allows for both IPv4 IP addresses as well as hostnames.
     """
 
     default_value = ('127.0.0.1', 0)
     info_text = 'an (ip, port) tuple'
 
     def validate(self, obj, value):
         if isinstance(value, tuple):
             if len(value) == 2:
                 if isinstance(value[0], basestring) and isinstance(value[1], int):
                     port = value[1]
                     if port >= 0 and port <= 65535:
                         return value
         self.error(obj, value)