Merge sconfig branch.

IPython/config/config.py

@@ -0,0 +1,179 b''
+"""Load and store configuration objects.
+
+Test this module using
+
+nosetests -v --with-doctest --doctest-tests IPython.config
+
+"""
+
+from __future__ import with_statement
+from contextlib import contextmanager
+
+import inspect
+import types
+from IPython.config import traitlets
+from traitlets import Traitlet
+from IPython.external.configobj import ConfigObj
+
+def debug(s):
+    import sys
+    sys.stderr.write(str(s) + '\n')
+
+@contextmanager
+def raw(config):
+    """Context manager for accessing traitlets directly.
+
+    """
+    config.__getattribute__('',raw_access=True)
+    yield config
+    config.__getattribute__('',raw_access=False)
+
+class Config(object):
+    """
+    Implementation Notes
+    ====================
+    All instances of the same Config class share properties.  Therefore,
+
+    >>> class Sample(Config):
+    ...     my_float = traitlets.Float(3)
+
+    >>> s0 = Sample()
+    >>> s1 = Sample()
+    >>> s0.my_float = 5
+    >>> s0.my_float == s1.my_float
+    True
+
+    """
+    def __init__(self):
+        # Instantiate subconfigs
+        with raw(self):
+            subconfigs = [(n,v) for n,v in
+                          inspect.getmembers(self, inspect.isclass)
+                          if not n.startswith('__')]
+
+        for n,v in subconfigs:
+            setattr(self, n, v())
+
+    def __getattribute__(self,attr,raw_access=None,
+                         _ns={'raw_access':False}):
+        if raw_access is not None:
+            _ns['raw_access'] = raw_access
+            return
+
+        obj = object.__getattribute__(self,attr)
+        if isinstance(obj,Traitlet) and not _ns['raw_access']:
+            return obj.__call__()
+        else:
+            return obj
+
+    def __setattr__(self,attr,value):
+        obj = object.__getattribute__(self,attr)
+        if isinstance(obj,Traitlet):
+            obj(value)
+        else:
+            self.__dict__[attr] = value
+
+    def __str__(self,level=1,only_modified=True):
+        ci = ConfigInspector(self)
+        out = ''
+        spacer = '  '*(level-1)
+
+        # Add traitlet representations
+        for p,v in ci.properties:
+            if (v.modified and only_modified) or not only_modified:
+                out += spacer + '%s = %s\n' % (p,v)
+
+        # Add subconfig representations
+        for (n,v) in ci.subconfigs:
+            sub_str = v.__str__(level=level+1,only_modified=only_modified)
+            if sub_str:
+                out += '\n' + spacer + '[' * level + ('%s' % n) \
+                       + ']'*level + '\n'
+                out += sub_str
+
+        return out
+
+    def __iadd__(self,source):
+        """Load configuration from filename, and update self.
+
+        """
+        if not isinstance(source,dict):
+            source = ConfigObj(source, unrepr=True)
+        update_from_dict(self,source)
+        return self
+
+
+class ConfigInspector(object):
+    """Allow the inspection of Config objects.
+
+    """
+    def __init__(self,config):
+        self._config = config
+
+    @property
+    def properties(self):
+        "Return all traitlet names."
+        with raw(self._config):
+            return inspect.getmembers(self._config,
+                                      lambda obj: isinstance(obj, Traitlet))
+
+    @property
+    def subconfigs(self):
+        "Return all subconfig names and values."
+        with raw(self._config):
+            return [(n,v) for n,v in
+                    inspect.getmembers(self._config,
+                                       lambda obj: isinstance(obj,Config))
+                    if not n.startswith('__')]
+
+    def reset(self):
+        for (p,v) in self.properties:
+            v.reset()
+
+        for (s,v) in self.subconfigs:
+            ConfigInspector(v).reset()
+
+def update_from_dict(config,d):
+    """Propagate the values of the dictionary to the given configuration.
+
+    Useful to load configobj instances.
+
+    """
+    for k,v in d.items():
+        try:
+            prop_or_subconfig = getattr(config, k)
+        except AttributeError:
+            print "Invalid section/property in config file: %s" % k
+        else:
+            if isinstance(v,dict):
+                update_from_dict(prop_or_subconfig,v)
+            else:
+                setattr(config, k, v)
+
+def dict_from_config(config,only_modified=True):
+    """Create a dictionary from a Config object."""
+    ci = ConfigInspector(config)
+    out = {}
+
+    for p,v in ci.properties:
+        if (v.modified and only_modified) or not only_modified:
+            out[p] = v
+
+    for s,v in ci.subconfigs:
+        d = dict_from_config(v,only_modified)
+        if d != {}:
+            out[s] = d
+
+    return out
+
+def write(config, target):
+    """Write a configuration to file.
+
+    """
+    if isinstance(target, str):
+        target = open(target, 'w+')
+    target.flush()
+    target.seek(0)
+
+    confobj = ConfigObj(dict_from_config(config), unrepr=True)
+    confobj.write(target)

IPython/config/tests/sample_config.py

@@ -0,0 +1,19 b''
+from IPython.config.api import *
+
+class SubSubSample(Config):
+    my_int = Int(3)
+
+
+class Sample(Config):
+    my_float = Float(3)
+    my_choice = Enum('a','b','c')
+
+    class MiddleSection(Config):
+        left_alone = Enum('1','2','c')
+        unknown_mod = Module('asd')
+
+    class SubSample(Config):
+        subsample_uri = URI('http://localhost:8080')
+
+        # Example of how to include external config
+        SubSubSample = SubSubSample()

IPython/config/tests/test_config.py

@@ -0,0 +1,135 b''
+"""
+# Test utilities
+
+>>> import os
+
+>>> def dict_as_sorted_list(d):
+...     for k in d:
+...         if isinstance(d[k],dict):
+...             d[k] = dict_as_sorted_list(d[k])
+...     return sorted(d.items())
+
+>>> def pprint(d,level=0):
+...     if isinstance(d,dict):
+...         d = dict_as_sorted_list(d)
+...     for item,value in d:
+...         if isinstance(value,list):
+...             print "%s%s" % (' '*level, item)
+...             pprint(value,level+2)
+...         else:
+...             print "%s%s: %s" % (' '*level, item, value)
+
+
+# Tests
+
+>>> from IPython.config.api import *
+>>> from sample_config import *
+
+>>> s = Sample()
+>>> print s.my_float
+3.0
+>>> s.my_float = 4
+>>> print s.my_float
+4.0
+>>> print type(s.my_float)
+<type 'float'>
+>>> s.SubSample.SubSubSample.my_int = 5.0
+>>> print s.SubSample.SubSubSample.my_int
+5
+
+>>> i = ConfigInspector(s)
+>>> print i.properties
+[('my_choice', 'a'), ('my_float', 4.0)]
+>>> print tuple(s for s,v in i.subconfigs)
+('MiddleSection', 'SubSample')
+
+>>> print s
+my_float = 4.0
+<BLANKLINE>
+[SubSample]
+<BLANKLINE>
+  [[SubSubSample]]
+    my_int = 5
+<BLANKLINE>
+
+>>> import tempfile
+>>> fn = tempfile.mktemp()
+>>> f = open(fn,'w')
+>>> f.write(str(s))
+>>> f.close()
+
+>>> s += fn
+
+>>> from IPython.external.configobj import ConfigObj
+>>> c = ConfigObj(fn)
+>>> c['SubSample']['subsample_uri'] = 'http://ipython.scipy.org'
+
+>>> s += c
+>>> print s
+my_float = 4.0
+<BLANKLINE>
+[SubSample]
+  subsample_uri = 'http://ipython.scipy.org'
+<BLANKLINE>
+  [[SubSubSample]]
+    my_int = 5
+<BLANKLINE>
+
+>>> pprint(dict_from_config(s,only_modified=False))
+MiddleSection
+  left_alone: '1'
+  unknown_mod: 'asd'
+SubSample
+  SubSubSample
+    my_int: 5
+  subsample_uri: 'http://ipython.scipy.org'
+my_choice: 'a'
+my_float: 4.0
+
+>>> pprint(dict_from_config(s))
+SubSample
+  SubSubSample
+    my_int: 5
+  subsample_uri: 'http://ipython.scipy.org'
+my_float: 4.0
+
+Test roundtripping:
+
+>>> fn = tempfile.mktemp()
+>>> f = open(fn, 'w')
+>>> f.write('''
+... [MiddleSection]
+... # some comment here
+... left_alone = 'c'
+... ''')
+>>> f.close()
+
+>>> s += fn
+
+>>> pprint(dict_from_config(s))
+MiddleSection
+  left_alone: 'c'
+SubSample
+  SubSubSample
+    my_int: 5
+  subsample_uri: 'http://ipython.scipy.org'
+my_float: 4.0
+
+>>> write(s, fn)
+>>> f = file(fn,'r')
+>>> ConfigInspector(s).reset()
+>>> pprint(dict_from_config(s))
+
+>>> s += fn
+>>> os.unlink(fn)
+>>> pprint(dict_from_config(s))
+MiddleSection
+  left_alone: 'c'
+SubSample
+  SubSubSample
+    my_int: 5
+  subsample_uri: 'http://ipython.scipy.org'
+my_float: 4.0
+
+
+"""

IPython/config/traitlets.py

@@ -0,0 +1,322 b''
+"""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

IPython/config/api.py

@@ -19,6 +19,11 b' import os'
 from IPython.config.cutils import get_home_dir, get_ipython_dir
 from IPython.external.configobj import ConfigObj
 
+# Traitlets config imports
+from IPython.config import traitlets
+from IPython.config.config import *
+from traitlets import *
+
 class ConfigObjManager(object):
     
     def __init__(self, configObj, filename):