IPython/config/traitlets.py

"""Traitlets -- a light-weight meta-class free stand-in for Traits.

Traitlet behaviour
==================
- Automatic casting, equivalent to traits.C* classes, e.g. CFloat, CBool etc.

- By default, validation is done by attempting to cast a given value
  to the underlying type, e.g. bool for Bool, float for Float etc.

- To set or get a Traitlet value, use the ()-operator.  E.g.

  >>> b = Bool(False)
  >>> b(True)
  >>> print b # returns a string representation of the Traitlet
  True
  >>> print b() # returns the underlying bool object
  True

  This makes it possible to change values "in-place", unlike an assigment
  of the form

  >>> c = Bool(False)
  >>> c = True

  which results in

  >>> print type(b), type(c)
  <class 'IPython.config.traitlets.Bool'> <type 'bool'>

- Each Traitlet keeps track of its modification state, e.g.

  >>> c = Bool(False)
  >>> print c.modified
  False
  >>> c(False)
  >>> print c.modified
  False
  >>> c(True)
  >>> print c.modified
  True

How to customize Traitlets
==========================

The easiest way to create a new Traitlet is by wrapping an underlying
Python type.  This is done by setting the "_type" class attribute.  For
example, creating an int-like Traitlet is done as follows:

>>> class MyInt(Traitlet):
...     _type = int

>>> i = MyInt(3)
>>> i(4)
>>> print i
4

>>> try:
...     i('a')
... except ValidationError:
...    pass # this is expected
... else:
...     "This should not be reached."

Furthermore, the following methods are provided for finer grained
control of validation and assignment:

 - validate(self,value)
   Ensure that "value" is valid.  If not, raise an exception of any kind
   with a suitable error message, which is reported to the user.

 - prepare_value(self)
   When using the ()-operator to query the underlying Traitlet value,
   that value is first passed through prepare_value.  For example:

   >>> class Eval(Traitlet):
   ...     _type = str
   ...
   ...     def prepare_value(self):
   ...         return eval(self._value)

   >>> x = Eval('1+1')
   >>> print x
   '1+1'
   >>> print x()
   2

 - __repr__(self)
   By default, repr(self._value) is returned.  This can be customised
   to, for example, first call prepare_value and return the repr of
   the resulting object.

"""

import re
import types

class ValidationError(Exception):
    pass

class Traitlet(object):
    """Traitlet which knows its modification state.

    """
    def __init__(self, value):
        "Validate and store the default value.  State is 'unmodified'."
        self._type = getattr(self,'_type',None)
        value = self._parse_validation(value)
        self._default_value = value
        self.reset()

    def reset(self):
        self._value = self._default_value
        self._changed = False

    def validate(self, value):
        "Validate the given value."
        if self._type is not None:
            self._type(value)

    def _parse_validation(self, value):
        """Run validation and return a descriptive error if needed.

        """
        try:
            self.validate(value)
        except Exception, e:
            err_message = 'Cannot convert "%s" to %s' % \
                          (value, self.__class__.__name__.lower())
            if e.message:
                err_message += ': %s' % e.message
            raise ValidationError(err_message)
        else:
            # Cast to appropriate type before storing
            if self._type is not None:
                value = self._type(value)
            return value

    def prepare_value(self):
        """Run on value before it is ever returned to the user.

        """
        return self._value

    def __call__(self,value=None):
        """Query or set value depending on whether `value` is specified.

        """
        if value is None:
            return self.prepare_value()

        self._value = self._parse_validation(value)
        self._changed = (self._value != self._default_value)

    @property
    def modified(self):
        "Whether value has changed from original definition."
        return self._changed

    def __repr__(self):
        """This class is represented by the underlying repr.  Used when
        dumping value to file.

        """
        return repr(self._value)

class Float(Traitlet):
    """
    >>> f = Float(0)
    >>> print f.modified
    False

    >>> f(3)
    >>> print f()
    3.0
    >>> print f.modified
    True

    >>> f(0)
    >>> print f()
    0.0
    >>> print f.modified
    False

    >>> try:
    ...    f('a')
    ... except ValidationError:
    ...    pass

    """
    _type = float

class Enum(Traitlet):
    """
    >>> c = Enum('a','b','c')
    >>> print c()
    a

    >>> try:
    ...    c('unknown')
    ... except ValidationError:
    ...    pass

    >>> print c.modified
    False

    >>> c('b')
    >>> print c()
    b

    """
    def __init__(self, *options):
        self._options = options
        super(Enum,self).__init__(options[0])

    def validate(self, value):
        if not value in self._options:
            raise ValueError('must be one of %s' % str(self._options))

class Module(Traitlet):
    """
    >>> m = Module('some.unknown.module')
    >>> print m
    'some.unknown.module'

    >>> m = Module('re')
    >>> assert type(m()) is types.ModuleType

    """
    _type = str

    def prepare_value(self):
        try:
            module = eval(self._value)
        except:
            module = None

        if type(module) is not types.ModuleType:
            raise ValueError("Invalid module name: %s" % self._value)
        else:
            return module


class URI(Traitlet):
    """
    >>> u = URI('http://')

    >>> try:
    ...    u = URI('something.else')
    ... except ValidationError:
    ...    pass

    >>> u = URI('http://ipython.scipy.org/')
    >>> print u
    'http://ipython.scipy.org/'

    """
    _regexp = re.compile(r'^[a-zA-Z]+:\/\/')
    _type = str

    def validate(self, uri):
        if not self._regexp.match(uri):
            raise ValueError()

class Int(Traitlet):
    """
    >>> i = Int(3.5)
    >>> print i
    3
    >>> print i()
    3

    >>> i = Int('4')
    >>> print i
    4

    >>> try:
    ...    i = Int('a')
    ... except ValidationError:
    ...    pass
    ... else:
    ...    raise "Should fail"

    """
    _type = int

class Bool(Traitlet):
    """
    >>> b = Bool(2)
    >>> print b
    True
    >>> print b()
    True

    >>> b = Bool('True')
    >>> print b
    True
    >>> b(True)
    >>> print b.modified
    False

    >>> print Bool(0)
    False

    """
    _type = bool

class Unicode(Traitlet):
    """
    >>> u = Unicode(123)
    >>> print u
    u'123'

    >>> u = Unicode('123')
    >>> print u.modified
    False

    >>> u('hello world')
    >>> print u
    u'hello world'

    """
    _type = unicode