allow multi-level Config parentage

now Foo.Bar.Baz can affect a Baz whose parent is Bar whose parent is Foo.

More specificity = higher priority, so Foo.Bar.Baz > Bar.Baz > Baz.

IPython/config/configurable.py

@@ -1,375 +1,382 b''
 # encoding: utf-8
 """
 A base class for objects that are configurable.
 
 Inheritance diagram:
 
 .. inheritance-diagram:: IPython.config.configurable
    :parts: 3
 
 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 datetime
 from copy import deepcopy
 
 from loader import Config
 from IPython.utils.traitlets import HasTraits, Instance
 from IPython.utils.text import indent, wrap_paragraphs
 
 
 #-----------------------------------------------------------------------------
 # Helper classes for Configurables
 #-----------------------------------------------------------------------------
 
 
 class ConfigurableError(Exception):
     pass
 
 
 class MultipleInstanceError(ConfigurableError):
     pass
 
 #-----------------------------------------------------------------------------
 # Configurable implementation
 #-----------------------------------------------------------------------------
 
 class Configurable(HasTraits):
 
     config = Instance(Config, (), {})
     parent = Instance('IPython.config.configurable.Configurable')
     created = None
 
     def __init__(self, **kwargs):
         """Create a configurable given a config config.
 
         Parameters
         ----------
         config : Config
             If this is empty, default values are used. If config is a
             :class:`Config` instance, it will be used to configure the
             instance.
-        parent : Configurable instance
-            The parent
+        parent : Configurable instance, optional
+            The parent Configurable instance of this object.
 
         Notes
         -----
         Subclasses of Configurable must call the :meth:`__init__` method of
         :class:`Configurable` *before* doing anything else and using
         :func:`super`::
 
             class MyConfigurable(Configurable):
                 def __init__(self, config=None):
                     super(MyConfigurable, self).__init__(config=config)
                     # Then any other code you need to finish initialization.
 
         This ensures that instances will be configured properly.
         """
         parent = kwargs.pop('parent', None)
         if parent:
             # config is implied from parent
             if kwargs.get('config', None) is None:
                 kwargs['config'] = parent.config
             self.parent = parent
         
         config = kwargs.pop('config', None)
         if config is not None:
             # We used to deepcopy, but for now we are trying to just save
             # by reference.  This *could* have side effects as all components
             # will share config. In fact, I did find such a side effect in
             # _config_changed below. If a config attribute value was a mutable type
             # all instances of a component were getting the same copy, effectively
             # making that a class attribute.
             # self.config = deepcopy(config)
             self.config = config
         # This should go second so individual keyword arguments override
         # the values in config.
         super(Configurable, self).__init__(**kwargs)
         self.created = datetime.datetime.now()
 
     #-------------------------------------------------------------------------
     # Static trait notifiations
     #-------------------------------------------------------------------------
     
     @classmethod
     def section_names(cls):
         """return section names as a list"""
         return  [c.__name__ for c in reversed(cls.__mro__) if
             issubclass(c, Configurable) and issubclass(cls, c)
         ]
+    
+    def _find_my_config(self, cfg):
+        """extract my config from a global Config object
+        
+        will construct a Config object of only the config values that apply to me
+        based on my mro(), as well as those of my parent(s) if they exist.
+        
+        If I am Bar and my parent is Foo, and their parent is Tim,
+        this will return merge following config sections, in this order::
+        
+            [Bar, Foo.bar, Tim.Foo.Bar]
+        
+        With the last item being the highest priority.
+        """
+        cfgs = [cfg]
+        if self.parent:
+            cfgs.append(self.parent._find_my_config(cfg))
+        my_config = Config()
+        for c in cfgs:
+            for sname in self.section_names():
+                # Don't do a blind getattr as that would cause the config to
+                # dynamically create the section with name Class.__name__.
+                if c._has_section(sname):
+                    my_config.merge(c[sname])
+        return my_config
 
     def _load_config(self, cfg, section_names=None, traits=None):
         """load traits from a Config object"""
         
         if traits is None:
             traits = self.traits(config=True)
         if section_names is None:
             section_names = self.section_names()
         
-        for sname in section_names:
-            # Don't do a blind getattr as that would cause the config to
-            # dynamically create the section with name self.__class__.__name__.
-            if cfg._has_section(sname):
-                my_config = cfg[sname]
-                for k, v in traits.iteritems():
-                    try:
-                        # Here we grab the value from the config
-                        # If k has the naming convention of a config
-                        # section, it will be auto created.
-                        config_value = my_config[k]
-                    except KeyError:
-                        pass
-                    else:
-                        # We have to do a deepcopy here if we don't deepcopy the entire
-                        # config object. If we don't, a mutable config_value will be
-                        # shared by all instances, effectively making it a class attribute.
-                        setattr(self, k, deepcopy(config_value))
+        my_config = self._find_my_config(cfg)
+        for name, config_value in my_config.iteritems():
+            if name in traits:
+                # We have to do a deepcopy here if we don't deepcopy the entire
+                # config object. If we don't, a mutable config_value will be
+                # shared by all instances, effectively making it a class attribute.
+                setattr(self, name, deepcopy(config_value))
 
     def _config_changed(self, name, old, new):
         """Update all the class traits having ``config=True`` as metadata.
 
         For any class trait with a ``config`` metadata attribute that is
         ``True``, we update the trait with the value of the corresponding
         config entry.
         """
         # Get all traits with a config metadata entry that is True
         traits = self.traits(config=True)
 
         # We auto-load config section for this class as well as any parent
         # classes that are Configurable subclasses.  This starts with Configurable
         # and works down the mro loading the config for each section.
         section_names = self.section_names()
         self._load_config(new, traits=traits, section_names=section_names)
-        
-        # load parent config as well, if we have one
-        parent_section_names = [] if self.parent is None else self.parent.section_names()
-        for parent in parent_section_names:
-            if not new._has_section(parent):
-                continue
-            self._load_config(new[parent], traits=traits, section_names=section_names)
 
     def update_config(self, config):
         """Fire the traits events when the config is updated."""
         # Save a copy of the current config.
         newconfig = deepcopy(self.config)
         # Merge the new config into the current one.
         newconfig.merge(config)
         # Save the combined config as self.config, which triggers the traits
         # events.
         self.config = newconfig
 
     @classmethod
     def class_get_help(cls, inst=None):
         """Get the help string for this class in ReST format.
         
         If `inst` is given, it's current trait values will be used in place of
         class defaults.
         """
         assert inst is None or isinstance(inst, cls)
         final_help = []
         final_help.append(u'%s options' % cls.__name__)
         final_help.append(len(final_help[0])*u'-')
         for k, v in sorted(cls.class_traits(config=True).iteritems()):
             help = cls.class_get_trait_help(v, inst)
             final_help.append(help)
         return '\n'.join(final_help)
 
     @classmethod
     def class_get_trait_help(cls, trait, inst=None):
         """Get the help string for a single trait.
         
         If `inst` is given, it's current trait values will be used in place of
         the class default.
         """
         assert inst is None or isinstance(inst, cls)
         lines = []
         header = "--%s.%s=<%s>" % (cls.__name__, trait.name, trait.__class__.__name__)
         lines.append(header)
         if inst is not None:
             lines.append(indent('Current: %r' % getattr(inst, trait.name), 4))
         else:
             try:
                 dvr = repr(trait.get_default_value())
             except Exception:
                 dvr = None # ignore defaults we can't construct
             if dvr is not None:
                 if len(dvr) > 64:
                     dvr = dvr[:61]+'...'
                 lines.append(indent('Default: %s' % dvr, 4))
         if 'Enum' in trait.__class__.__name__:
             # include Enum choices
             lines.append(indent('Choices: %r' % (trait.values,)))
 
         help = trait.get_metadata('help')
         if help is not None:
             help = '\n'.join(wrap_paragraphs(help, 76))
             lines.append(indent(help, 4))
         return '\n'.join(lines)
 
     @classmethod
     def class_print_help(cls, inst=None):
         """Get the help string for a single trait and print it."""
         print cls.class_get_help(inst)
 
     @classmethod
     def class_config_section(cls):
         """Get the config class config section"""
         def c(s):
             """return a commented, wrapped block."""
             s = '\n\n'.join(wrap_paragraphs(s, 78))
 
             return '# ' + s.replace('\n', '\n# ')
 
         # section header
         breaker = '#' + '-'*78
         s = "# %s configuration" % cls.__name__
         lines = [breaker, s, breaker, '']
         # get the description trait
         desc = cls.class_traits().get('description')
         if desc:
             desc = desc.default_value
         else:
             # no description trait, use __doc__
             desc = getattr(cls, '__doc__', '')
         if desc:
             lines.append(c(desc))
             lines.append('')
 
         parents = []
         for parent in cls.mro():
             # only include parents that are not base classes
             # and are not the class itself
             # and have some configurable traits to inherit
             if parent is not cls and issubclass(parent, Configurable) and \
                     parent.class_traits(config=True):
                 parents.append(parent)
 
         if parents:
             pstr = ', '.join([ p.__name__ for p in parents ])
             lines.append(c('%s will inherit config from: %s'%(cls.__name__, pstr)))
             lines.append('')
 
         for name, trait in cls.class_traits(config=True).iteritems():
             help = trait.get_metadata('help') or ''
             lines.append(c(help))
             lines.append('# c.%s.%s = %r'%(cls.__name__, name, trait.get_default_value()))
             lines.append('')
         return '\n'.join(lines)
 
 
 
 class SingletonConfigurable(Configurable):
     """A configurable that only allows one instance.
 
     This class is for classes that should only have one instance of itself
     or *any* subclass. To create and retrieve such a class use the
     :meth:`SingletonConfigurable.instance` method.
     """
 
     _instance = None
 
     @classmethod
     def _walk_mro(cls):
         """Walk the cls.mro() for parent classes that are also singletons
 
         For use in instance()
         """
 
         for subclass in cls.mro():
             if issubclass(cls, subclass) and \
                     issubclass(subclass, SingletonConfigurable) and \
                     subclass != SingletonConfigurable:
                 yield subclass
 
     @classmethod
     def clear_instance(cls):
         """unset _instance for this class and singleton parents.
         """
         if not cls.initialized():
             return
         for subclass in cls._walk_mro():
             if isinstance(subclass._instance, cls):
                 # only clear instances that are instances
                 # of the calling class
                 subclass._instance = None
 
     @classmethod
     def instance(cls, *args, **kwargs):
         """Returns a global instance of this class.
 
         This method create a new instance if none have previously been created
         and returns a previously created instance is one already exists.
 
         The arguments and keyword arguments passed to this method are passed
         on to the :meth:`__init__` method of the class upon instantiation.
 
         Examples
         --------
 
         Create a singleton class using instance, and retrieve it::
 
             >>> from IPython.config.configurable import SingletonConfigurable
             >>> class Foo(SingletonConfigurable): pass
             >>> foo = Foo.instance()
             >>> foo == Foo.instance()
             True
 
         Create a subclass that is retrived using the base class instance::
 
             >>> class Bar(SingletonConfigurable): pass
             >>> class Bam(Bar): pass
             >>> bam = Bam.instance()
             >>> bam == Bar.instance()
             True
         """
         # Create and save the instance
         if cls._instance is None:
             inst = cls(*args, **kwargs)
             # Now make sure that the instance will also be returned by
             # parent classes' _instance attribute.
             for subclass in cls._walk_mro():
                 subclass._instance = inst
 
         if isinstance(cls._instance, cls):
             return cls._instance
         else:
             raise MultipleInstanceError(
                 'Multiple incompatible subclass instances of '
                 '%s are being created.' % cls.__name__
             )
 
     @classmethod
     def initialized(cls):
         """Has an instance been created?"""
         return hasattr(cls, "_instance") and cls._instance is not None
 
 
 class LoggingConfigurable(Configurable):
     """A parent class for Configurables that log.
 
     Subclasses have a log trait, and the default behavior
     is to get the logger from the currently running Application
     via Application.instance().log.
     """
 
     log = Instance('logging.Logger')
     def _log_default(self):
         from IPython.config.application import Application
         return Application.instance().log
 
 

IPython/config/tests/test_configurable.py

@@ -1,239 +1,284 b''
 # encoding: utf-8
 """
 Tests for IPython.config.configurable
 
 Authors:
 
 * Brian Granger
 * Fernando Perez (design help)
 """
 
 #-----------------------------------------------------------------------------
 #  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
 #-----------------------------------------------------------------------------
 
 from unittest import TestCase
 
 from IPython.config.configurable import (
     Configurable, 
     SingletonConfigurable
 )
 
 from IPython.utils.traitlets import (
     Integer, Float, Unicode
 )
 
 from IPython.config.loader import Config
 from IPython.utils.py3compat import PY3
 
 #-----------------------------------------------------------------------------
 # Test cases
 #-----------------------------------------------------------------------------
 
 
 class MyConfigurable(Configurable):
     a = Integer(1, config=True, help="The integer a.")
     b = Float(1.0, config=True, help="The integer b.")
     c = Unicode('no config')
 
 
 mc_help=u"""MyConfigurable options
 ----------------------
 --MyConfigurable.a=<Integer>
     Default: 1
     The integer a.
 --MyConfigurable.b=<Float>
     Default: 1.0
     The integer b."""
 
 mc_help_inst=u"""MyConfigurable options
 ----------------------
 --MyConfigurable.a=<Integer>
     Current: 5
     The integer a.
 --MyConfigurable.b=<Float>
     Current: 4.0
     The integer b."""
 
 # On Python 3, the Integer trait is a synonym for Int
 if PY3:
     mc_help = mc_help.replace(u"<Integer>", u"<Int>")
     mc_help_inst = mc_help_inst.replace(u"<Integer>", u"<Int>")
 
 class Foo(Configurable):
     a = Integer(0, config=True, help="The integer a.")
     b = Unicode('nope', config=True)
 
 
 class Bar(Foo):
     b = Unicode('gotit', config=False, help="The string b.")
     c = Float(config=True, help="The string c.")
 
 
 class TestConfigurable(TestCase):
 
     def test_default(self):
         c1 = Configurable()
         c2 = Configurable(config=c1.config)
         c3 = Configurable(config=c2.config)
         self.assertEqual(c1.config, c2.config)
         self.assertEqual(c2.config, c3.config)
 
     def test_custom(self):
         config = Config()
         config.foo = 'foo'
         config.bar = 'bar'
         c1 = Configurable(config=config)
         c2 = Configurable(config=c1.config)
         c3 = Configurable(config=c2.config)
         self.assertEqual(c1.config, config)
         self.assertEqual(c2.config, config)
         self.assertEqual(c3.config, config)
         # Test that copies are not made
         self.assertTrue(c1.config is config)
         self.assertTrue(c2.config is config)
         self.assertTrue(c3.config is config)
         self.assertTrue(c1.config is c2.config)
         self.assertTrue(c2.config is c3.config)
         
     def test_inheritance(self):
         config = Config()
         config.MyConfigurable.a = 2
         config.MyConfigurable.b = 2.0
         c1 = MyConfigurable(config=config)
         c2 = MyConfigurable(config=c1.config)
         self.assertEqual(c1.a, config.MyConfigurable.a)
         self.assertEqual(c1.b, config.MyConfigurable.b)
         self.assertEqual(c2.a, config.MyConfigurable.a)
         self.assertEqual(c2.b, config.MyConfigurable.b)
 
     def test_parent(self):
         config = Config()
         config.Foo.a = 10
         config.Foo.b = "wow"
         config.Bar.b = 'later'
         config.Bar.c = 100.0
         f = Foo(config=config)
         b = Bar(config=f.config)
         self.assertEqual(f.a, 10)
         self.assertEqual(f.b, 'wow')
         self.assertEqual(b.b, 'gotit')
         self.assertEqual(b.c, 100.0)
 
     def test_override1(self):
         config = Config()
         config.MyConfigurable.a = 2
         config.MyConfigurable.b = 2.0
         c = MyConfigurable(a=3, config=config)
         self.assertEqual(c.a, 3)
         self.assertEqual(c.b, config.MyConfigurable.b)
         self.assertEqual(c.c, 'no config')
 
     def test_override2(self):
         config = Config()
         config.Foo.a = 1
         config.Bar.b = 'or'  # Up above b is config=False, so this won't do it.
         config.Bar.c = 10.0
         c = Bar(config=config)
         self.assertEqual(c.a, config.Foo.a)
         self.assertEqual(c.b, 'gotit')
         self.assertEqual(c.c, config.Bar.c)
         c = Bar(a=2, b='and', c=20.0, config=config)
         self.assertEqual(c.a, 2)
         self.assertEqual(c.b, 'and')
         self.assertEqual(c.c, 20.0)
 
     def test_help(self):
         self.assertEqual(MyConfigurable.class_get_help(), mc_help)
 
     def test_help_inst(self):
         inst = MyConfigurable(a=5, b=4)
         self.assertEqual(MyConfigurable.class_get_help(inst), mc_help_inst)
 
 
 class TestSingletonConfigurable(TestCase):
 
     def test_instance(self):
         from IPython.config.configurable import SingletonConfigurable
         class Foo(SingletonConfigurable): pass
         self.assertEqual(Foo.initialized(), False)
         foo = Foo.instance()
         self.assertEqual(Foo.initialized(), True)
         self.assertEqual(foo, Foo.instance())
         self.assertEqual(SingletonConfigurable._instance, None)
 
     def test_inheritance(self):
         class Bar(SingletonConfigurable): pass
         class Bam(Bar): pass
         self.assertEqual(Bar.initialized(), False)
         self.assertEqual(Bam.initialized(), False)
         bam = Bam.instance()
         bam == Bar.instance()
         self.assertEqual(Bar.initialized(), True)
         self.assertEqual(Bam.initialized(), True)
         self.assertEqual(bam, Bam._instance)
         self.assertEqual(bam, Bar._instance)
         self.assertEqual(SingletonConfigurable._instance, None)
 
 
 class MyParent(Configurable):
     pass
 
 class MyParent2(MyParent):
     pass
 
 class TestParentConfigurable(TestCase):
     
     def test_parent_config(self):
-        
         cfg = Config({
             'MyParent' : {
                 'MyConfigurable' : {
                     'b' : 2.0,
                 }
             }
         })
         parent = MyParent(config=cfg)
         myc = MyConfigurable(parent=parent)
         self.assertEqual(myc.b, parent.config.MyParent.MyConfigurable.b)
 
     def test_parent_inheritance(self):
-        
         cfg = Config({
             'MyParent' : {
                 'MyConfigurable' : {
                     'b' : 2.0,
                 }
             }
         })
         parent = MyParent2(config=cfg)
         myc = MyConfigurable(parent=parent)
         self.assertEqual(myc.b, parent.config.MyParent.MyConfigurable.b)
 
+    def test_multi_parent(self):
+        cfg = Config({
+            'MyParent2' : {
+                'MyParent' : {
+                    'MyConfigurable' : {
+                        'b' : 2.0,
+                    }
+                },
+                # this one shouldn't count
+                'MyConfigurable' : {
+                    'b' : 3.0,
+                },
+            }
+        })
+        parent2 = MyParent2(config=cfg)
+        parent = MyParent(parent=parent2)
+        myc = MyConfigurable(parent=parent)
+        self.assertEqual(myc.b, parent.config.MyParent2.MyParent.MyConfigurable.b)
+
     def test_parent_priority(self):
-        
         cfg = Config({
             'MyConfigurable' : {
                 'b' : 2.0,
             },
             'MyParent' : {
                 'MyConfigurable' : {
                     'b' : 3.0,
                 }
             },
             'MyParent2' : {
                 'MyConfigurable' : {
                     'b' : 4.0,
                 }
             }
         })
         parent = MyParent2(config=cfg)
         myc = MyConfigurable(parent=parent)
         self.assertEqual(myc.b, parent.config.MyParent2.MyConfigurable.b)
+
+    def test_multi_parent_priority(self):
+        cfg = Config({
+            'MyConfigurable' : {
+                'b' : 2.0,
+            },
+            'MyParent' : {
+                'MyConfigurable' : {
+                    'b' : 3.0,
+                }
+            },
+            'MyParent2' : {
+                'MyConfigurable' : {
+                    'b' : 4.0,
+                }
+            },
+            'MyParent2' : {
+                'MyParent' : {
+                    'MyConfigurable' : {
+                        'b' : 5.0,
+                    }
+                }
+            }
+        })
+        parent2 = MyParent2(config=cfg)
+        parent = MyParent2(parent=parent2)
+        myc = MyConfigurable(parent=parent)
+        self.assertEqual(myc.b, parent.config.MyParent2.MyParent.MyConfigurable.b)
+