IPython/utils/traitlets.py

#!/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
  traitlets (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 sys
import types
from types import (
    InstanceType, ClassType, FunctionType,
    ListType, TupleType
)

from IPython.utils.importstring import import_item

ClassTypes = (ClassType, type)

SequenceTypes = (ListType, TupleType)

#-----------------------------------------------------------------------------
# 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


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__()


#-----------------------------------------------------------------------------
# Base TraitletType for all traitlets
#-----------------------------------------------------------------------------


class TraitletType(object):
    """A base class for all traitlet descriptors.

    Notes
    -----
    Our implementation of traitlets 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:`HasTraitlets`
    class that does the following:

    1. Sets the :attr:`name` attribute of every :class:`TraitletType`
       instance in the class dict to the name of the attribute.
    2. Sets the :attr:`this_class` attribute of every :class:`TraitletType`
       instance in the class dict to the *class* that declared the traitlet.
       This is used by the :class:`This` traitlet 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 TraitletType.
        """
        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."""
        dv = self.default_value
        return dv

    def instance_init(self, obj):
        """This is called by :meth:`HasTraitlets.__new__` to finish init'ing.

        Some stages of initialization must be delayed until the parent
        :class:`HasTraitlets` instance has been created.  This method is
        called in :meth:`HasTraitlets.__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:`HasTraitlets` instance
            The parent :class:`HasTraitlets` 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:`HasTraitlets`
        class has been instantiated.
        """
        dv = self.get_default_value()
        newdv = self._validate(obj, dv)
        obj._traitlet_values[self.name] = newdv

    def __get__(self, obj, cls=None):
        """Get the value of the traitlet by self.name for the instance.

        Default values are instantiated when :meth:`HasTraitlets.__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:`HasTraitlets` instance.
        """
        if obj is None:
            return self
        else:
            try:
                value = obj._traitlet_values[self.name]
            except:
                # HasTraitlets should call set_default_value to populate
                # this.  So this should never be reached.
                raise TraitletError('Unexpected error in TraitletType: '
                                    '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._traitlet_values[self.name] = new_value
            obj._notify_traitlet(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 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)

    def get_metadata(self, key):
        return getattr(self, '_metadata', {}).get(key, None)

    def set_metadata(self, key, value):
        getattr(self, '_metadata', {})[key] = value


#-----------------------------------------------------------------------------
# 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):
        """Create the HasTraitlets class.
        
        This instantiates all TraitletTypes in the class dict and sets their
        :attr:`name` attribute.
        """
        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)

    def __init__(cls, name, bases, classdict):
        """Finish initializing the HasTraitlets class.
        
        This sets the :attr:`this_class` attribute of each TraitletType in the
        class dict to the newly created class ``cls``.
        """
        for k, v in classdict.iteritems():
            if isinstance(v, TraitletType):
                v.this_class = cls
        super(MetaHasTraitlets, cls).__init__(name, bases, classdict)

class HasTraitlets(object):

    __metaclass__ = MetaHasTraitlets

    def __new__(cls, *args, **kw):
        inst = super(HasTraitlets, cls).__new__(cls, *args, **kw)
        inst._traitlet_values = {}
        inst._traitlet_notifiers = {}
        # Here we tell all the TraitletType instances to set their default
        # values on the instance. 
        for key in dir(cls):
            value = getattr(cls, key)
            if isinstance(value, TraitletType):
                value.instance_init(inst)
        return inst

    # def __init__(self):
    #     self._traitlet_values = {}
    #     self._traitlet_notifiers = {}

    def _notify_traitlet(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 traitlet_names(self, **metadata):
        """Get a list of all the names of this classes traitlets."""
        return self.traitlets(**metadata).keys()

    def traitlets(self, **metadata):
        """Get a list of all the traitlets of this class.

        The TraitletTypes returned don't know anything about the values
        that the various HasTraitlet'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.
        """
        traitlets = dict([memb for memb in inspect.getmembers(self.__class__) if \
                     isinstance(memb[1], TraitletType)])

        if len(metadata) == 0:
            return traitlets

        for meta_name, meta_eval in metadata.items():
            if type(meta_eval) is not FunctionType:
                metadata[meta_name] = _SimpleTest(meta_eval)

        result = {}
        for name, traitlet in traitlets.items():
            for meta_name, meta_eval in metadata.items():
                if not meta_eval(traitlet.get_metadata(meta_name)):
                    break
            else:
                result[name] = traitlet

        return result

    def traitlet_metadata(self, traitletname, key):
        """Get metadata values for traitlet by key."""
        try:
            traitlet = getattr(self.__class__, traitletname)
        except AttributeError:
            raise TraitletError("Class %s does not have a traitlet named %s" %
                                (self.__class__.__name__, traitletname))
        else:
            return traitlet.get_metadata(key)

#-----------------------------------------------------------------------------
# Actual TraitletTypes implementations/subclasses
#-----------------------------------------------------------------------------

#-----------------------------------------------------------------------------
# TraitletTypes subclasses for handling classes and instances of classes
#-----------------------------------------------------------------------------


class ClassBasedTraitletType(TraitletType):
    """A traitlet 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 ) )

        super(ClassBasedTraitletType, self).error(obj, msg)


class Type(ClassBasedTraitletType):
    """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.

        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:`HasTraitlets` class is instantiated.
        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'.
            The string is resolved into real class, when the parent 
            :class:`HasTraitlets` 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 TraitletError("A Type traitlet 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(ClassBasedTraitletType):
    """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 traitlet.

        This traitlet 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 traitlet.  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 TraitletError('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 TraitletError("The 'kw' argument must be a dict or None.")
            if not isinstance(args, tuple):
                raise TraitletError("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 HasTraitlets classes'
        :meth:`__new__` method is called to ensure that a unique instance
        is created for each HasTraitlets instance.
        """
        dv  = self.default_value
        if isinstance(dv, DefaultValueGenerator):
            return dv.generate(self.klass)
        else:
            return dv


class This(ClassBasedTraitletType):
    """A traitlet for instances of the class containing this trait.

    Because how how and when class bodies are executed, the ``This``
    traitlet 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
        # traitlet.
        if isinstance(value, self.this_class) or (value is None):
            return value
        else:
            self.error(obj, value)


#-----------------------------------------------------------------------------
# Basic TraitletTypes implementations/subclasses
#-----------------------------------------------------------------------------


class Any(TraitletType):
    default_value = None
    info_text = 'any value'


class Int(TraitletType):
    """A integer traitlet."""

    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 CInt(Int):
    """A casting version of the int traitlet."""

    def validate(self, obj, value):
        try:
            return int(value)
        except:
            self.error(obj, value)


class Long(TraitletType):
    """A long integer traitlet."""

    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 CLong(Long):
    """A casting version of the long integer traitlet."""

    def validate(self, obj, value):
        try:
            return long(value)
        except:
            self.error(obj, value)


class Float(TraitletType):
    """A float traitlet."""

    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 CFloat(Float):
    """A casting version of the float traitlet."""

    def validate(self, obj, value):
        try:
            return float(value)
        except:
            self.error(obj, value)

class Complex(TraitletType):
    """A traitlet for complex numbers."""

    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 CComplex(Complex):
    """A casting version of the complex number traitlet."""

    def validate (self, obj, value):
        try:
            return complex(value)
        except:
            self.error(obj, value)


class Str(TraitletType):
    """A traitlet for strings."""

    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 CStr(Str):
    """A casting version of the string traitlet."""

    def validate(self, obj, value):
        try:
            return str(value)
        except:
            try:
                return unicode(value)
            except:
                self.error(obj, value)


class Unicode(TraitletType):
    """A traitlet for unicode strings."""

    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 CUnicode(Unicode):
    """A casting version of the unicode traitlet."""

    def validate(self, obj, value):
        try:
            return unicode(value)
        except:
            self.error(obj, value)


class Bool(TraitletType):
    """A boolean (True, False) traitlet."""
    evaluate = bool
    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 traitlet."""

    def validate(self, obj, value):
        try:
            return bool(value)
        except:
            self.error(obj, value)


class Enum(TraitletType):
    """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):
            self.error(obj, value)

        for v in self.values:
            if v.lower() == value.lower():
                return v
        self.error(obj, value)


class List(Instance):
    """An instance of a Python list."""

    def __init__(self, default_value=None, allow_none=True, **metadata):
        """Create a list traitlet type from a list or tuple.

        The default value is created by doing ``list(default_value)``, 
        which creates a copy of the ``default_value``.
        """
        if default_value is None:
            args = ((),)
        elif isinstance(default_value, SequenceTypes):
            args = (default_value,)

        super(List,self).__init__(klass=list, args=args, 
                                  allow_none=allow_none, **metadata)