allow using instance values in place of defaults in Configurable.class_get_help

IPython/config/configurable.py

@@ -1,338 +1,351 b''
 # encoding: utf-8
 """
 A base class for objects that are configurable.
 
 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,(),{})
     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.
 
         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)
                     # Then any other code you need to finish initialization.
 
         This ensures that instances will be configured properly.
         """
         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
     #-------------------------------------------------------------------------
 
     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 = [cls.__name__ for cls in \
             reversed(self.__class__.__mro__) if
             issubclass(cls, Configurable) and issubclass(self.__class__, cls)]
 
         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 new._has_section(sname):
                 my_config = new[sname]
                 for k, v in traits.iteritems():
                     # Don't allow traitlets with config=True to start with
                     # uppercase.  Otherwise, they are confused with Config
                     # subsections.  But, developers shouldn't have uppercase
                     # attributes anyways! (PEP 6)
                     if k[0].upper()==k[0] and not k.startswith('_'):
                         raise ConfigurableError('Configurable traitlets with '
                         'config=True must start with a lowercase so they are '
                         'not confused with Config subsections: %s.%s' % \
                         (self.__class__.__name__, k))
                     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:
                         # print "Setting %s.%s from %s.%s=%r" % \
                         #     (self.__class__.__name__,k,sname,k,config_value)
                         # 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))
 
     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):
-        """Get the help string for this class in ReST format."""
+    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)
         cls_traits = cls.class_traits(config=True)
         final_help = []
         final_help.append(u'%s options' % cls.__name__)
         final_help.append(len(final_help[0])*u'-')
         for k,v in cls.class_traits(config=True).iteritems():
-            help = cls.class_get_trait_help(v)
+            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):
-        """Get the help string for a single trait."""
+    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):
+    def class_print_help(cls, inst=None):
         """Get the help string for a single trait and print it."""
-        print cls.class_get_help()
+        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,165 +1,178 b''
 # encoding: utf-8
 """
 Tests for IPython.config.configurable
 
 Authors:
 
 * Brian Granger
 * Fernando Perez (design help)
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2010  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 (
     Int, Float, Unicode
 )
 
 from IPython.config.loader import Config
 
 
 #-----------------------------------------------------------------------------
 # Test cases
 #-----------------------------------------------------------------------------
 
 
 class MyConfigurable(Configurable):
     a = Int(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=<Int>
     Default: 1
     The integer a.
 --MyConfigurable.b=<Float>
     Default: 1.0
     The integer b."""
 
+mc_help_inst=u"""MyConfigurable options
+----------------------
+--MyConfigurable.a=<Int>
+    Current: 5
+    The integer a.
+--MyConfigurable.b=<Float>
+    Current: 4.0
+    The integer b."""
+
 class Foo(Configurable):
     a = Int(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.assertEquals(c1.config, c2.config)
         self.assertEquals(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.assertEquals(c1.config, config)
         self.assertEquals(c2.config, config)
         self.assertEquals(c3.config, config)
         # Test that copies are not made
         self.assert_(c1.config is config)
         self.assert_(c2.config is config)
         self.assert_(c3.config is config)
         self.assert_(c1.config is c2.config)
         self.assert_(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.assertEquals(c1.a, config.MyConfigurable.a)
         self.assertEquals(c1.b, config.MyConfigurable.b)
         self.assertEquals(c2.a, config.MyConfigurable.a)
         self.assertEquals(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.assertEquals(f.a, 10)
         self.assertEquals(f.b, 'wow')
         self.assertEquals(b.b, 'gotit')
         self.assertEquals(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.assertEquals(c.a, 3)
         self.assertEquals(c.b, config.MyConfigurable.b)
         self.assertEquals(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.assertEquals(c.a, config.Foo.a)
         self.assertEquals(c.b, 'gotit')
         self.assertEquals(c.c, config.Bar.c)
         c = Bar(a=2, b='and', c=20.0, config=config)
         self.assertEquals(c.a, 2)
         self.assertEquals(c.b, 'and')
         self.assertEquals(c.c, 20.0)
 
     def test_help(self):
         self.assertEquals(MyConfigurable.class_get_help(), mc_help)
 
+    def test_help_inst(self):
+        inst = MyConfigurable(a=5, b=4)
+        self.assertEquals(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.assertEquals(Foo.initialized(), False)
         foo = Foo.instance()
         self.assertEquals(Foo.initialized(), True)
         self.assertEquals(foo, Foo.instance())
         self.assertEquals(SingletonConfigurable._instance, None)
 
     def test_inheritance(self):
         class Bar(SingletonConfigurable): pass
         class Bam(Bar): pass
         self.assertEquals(Bar.initialized(), False)
         self.assertEquals(Bam.initialized(), False)
         bam = Bam.instance()
         bam == Bar.instance()
         self.assertEquals(Bar.initialized(), True)
         self.assertEquals(Bam.initialized(), True)
         self.assertEquals(bam, Bam._instance)
         self.assertEquals(bam, Bar._instance)
         self.assertEquals(SingletonConfigurable._instance, None)