include default value in help output

also include choices in help output for Enums

IPython/config/application.py

@@ -1,241 +1,286 b''
 # encoding: utf-8
 """
 A base class for a configurable application.
 
 Authors:
 
 * Brian Granger
 """
 
 #-----------------------------------------------------------------------------
 #  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 copy import deepcopy
 import logging
 import sys
 
 from IPython.config.configurable import SingletonConfigurable
 from IPython.config.loader import (
     KeyValueConfigLoader, PyFileConfigLoader, Config
 )
 
 from IPython.utils.traitlets import (
     Unicode, List, Int, Enum, Dict
 )
 from IPython.utils.text import indent
 
 #-----------------------------------------------------------------------------
-# Descriptions for
+# Descriptions for the various sections
 #-----------------------------------------------------------------------------
 
 flag_description = """
 Flags are command-line arguments passed as '--<flag>'.
 These take no parameters, unlike regular key-value arguments.
 They are typically used for setting boolean flags, or enabling
 modes that involve setting multiple options together.
 """.strip() # trim newlines of front and back
 
 alias_description = """
 These are commonly set parameters, given abbreviated aliases for convenience.
 They are set in the same `name=value` way as class parameters, where
 <name> is replaced by the real parameter for which it is an alias.
 """.strip() # trim newlines of front and back
 
 keyvalue_description = """
 Parameters are set from command-line arguments of the form:
 `Class.trait=value`.  Parameters will *never* be prefixed with '-'.
 This line is evaluated in Python, so simple expressions are allowed, e.g.
     `C.a='range(3)'`   For setting C.a=[0,1,2]
 """.strip() # trim newlines of front and back
 
 #-----------------------------------------------------------------------------
 # Application class
 #-----------------------------------------------------------------------------
 
 
 class ApplicationError(Exception):
     pass
 
 
 class Application(SingletonConfigurable):
     """A singleton application with full configuration support."""
 
     # The name of the application, will usually match the name of the command
     # line application
     name = Unicode(u'application')
 
     # The description of the application that is printed at the beginning
     # of the help.
     description = Unicode(u'This is an application.')
     # default section descriptions
     flag_description = Unicode(flag_description)
     alias_description = Unicode(alias_description)
     keyvalue_description = Unicode(keyvalue_description)
     
 
     # A sequence of Configurable subclasses whose config=True attributes will
     # be exposed at the command line.
     classes = List([])
 
     # The version string of this application.
     version = Unicode(u'0.0')
 
     # The log level for the application
     log_level = Enum((0,10,20,30,40,50), default_value=logging.WARN,
                      config=True,
-                     help="Set the log level (0,10,20,30,40,50).")
+                     help="Set the log level.")
     
     # the alias map for configurables
     aliases = Dict(dict(log_level='Application.log_level'))
     
     # flags for loading Configurables or store_const style flags
     # flags are loaded from this dict by '--key' flags
     # this must be a dict of two-tuples, the first element being the Config/dict
     # and the second being the help string for the flag
     flags = Dict()
     
 
     def __init__(self, **kwargs):
         SingletonConfigurable.__init__(self, **kwargs)
         # Add my class to self.classes so my attributes appear in command line
         # options.
         self.classes.insert(0, self.__class__)
         
         # ensure self.flags dict is valid
         for key,value in self.flags.iteritems():
             assert len(value) == 2, "Bad flag: %r:%s"%(key,value)
             assert isinstance(value[0], (dict, Config)), "Bad flag: %r:%s"%(key,value)
             assert isinstance(value[1], basestring), "Bad flag: %r:%s"%(key,value)
         self.init_logging()
 
     def _config_changed(self, name, old, new):
         SingletonConfigurable._config_changed(self, name, old, new)
         self.log.debug('Config changed:')
         self.log.debug(repr(new))
 
     def init_logging(self):
         """Start logging for this application.
 
         The default is to log to stdout using a StreaHandler. The log level
         starts at loggin.WARN, but this can be adjusted by setting the 
         ``log_level`` attribute.
         """
         self.log = logging.getLogger(self.__class__.__name__)
         self.log.setLevel(self.log_level)
         self._log_handler = logging.StreamHandler()
         self._log_formatter = logging.Formatter("[%(name)s] %(message)s")
         self._log_handler.setFormatter(self._log_formatter)
         self.log.addHandler(self._log_handler)
 
     def _log_level_changed(self, name, old, new):
         """Adjust the log level when log_level is set."""
         self.log.setLevel(new)
     
     def print_alias_help(self):
         """print the alias part of the help"""
         if not self.aliases:
             return
-            
-        print "Aliases"
-        print "-------"
-        print self.alias_description
-        print
+        
+        lines = ['Aliases']
+        lines.append('_'*len(lines[0]))
+        lines.append(self.alias_description)
+        lines.append('')
         
         classdict = {}
         for c in self.classes:
             classdict[c.__name__] = c
         
         for alias, longname in self.aliases.iteritems():
             classname, traitname = longname.split('.',1)
             cls = classdict[classname]
             
             trait = cls.class_traits(config=True)[traitname]
-            help = trait.get_metadata('help')
-            print alias, "(%s)"%longname, ':', trait.__class__.__name__
-            if help:
-                print indent(help, flatten=True)
-        print
+            help = cls.class_get_trait_help(trait)
+            help = help.replace(longname, "%s (%s)"%(alias, longname), 1)
+            lines.append(help)
+            # header = "%s (%s) : %s"%(alias, longname, trait.__class__.__name__)
+            # lines.append(header)
+            # help = cls.class_get_trait_help(trait)
+            # if help:
+            #     lines.append(indent(help, flatten=True))
+        lines.append('')
+        print '\n'.join(lines)
     
     def print_flag_help(self):
         """print the flag part of the help"""
         if not self.flags:
             return
         
-        print "Flags"
-        print "-----"
-        print self.flag_description
-        print
+        lines = ['Flags']
+        lines.append('_'*len(lines[0]))
+        lines.append(self.flag_description)
+        lines.append('')
         
         for m, (cfg,help) in self.flags.iteritems():
-            print '--'+m
-            print indent(help, flatten=True)
-        print
+            lines.append('--'+m)
+            lines.append(indent(help, flatten=True))
+        lines.append('')
+        print '\n'.join(lines)
     
     def print_help(self):
         """Print the help for each Configurable class in self.classes."""
         self.print_flag_help()
         self.print_alias_help()
+        
         if self.classes:
             print "Class parameters"
             print "----------------"
             print self.keyvalue_description
             print
         
         for cls in self.classes:
             cls.class_print_help()
             print
 
     def print_description(self):
         """Print the application description."""
         print self.description
         print
 
     def print_version(self):
         """Print the version string."""
         print self.version
 
     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
 
     def parse_command_line(self, argv=None):
         """Parse the command line arguments."""
         argv = sys.argv[1:] if argv is None else argv
 
         if '-h' in argv or '--help' in argv:
             self.print_description()
             self.print_help()
             self.exit(1)
 
         if '--version' in argv:
             self.print_version()
             self.exit(1)
         
         loader = KeyValueConfigLoader(argv=argv, aliases=self.aliases,
                                         flags=self.flags)
         config = loader.load_config()
         self.update_config(config)
 
     def load_config_file(self, filename, path=None):
         """Load a .py based config file by filename and path."""
         loader = PyFileConfigLoader(filename, path=path)
         config = loader.load_config()
         self.update_config(config)
 
     def exit(self, exit_status=0):
         self.log.debug("Exiting application: %s" % self.name)
         sys.exit(exit_status)
+
+#-----------------------------------------------------------------------------
+# utility functions, for convenience
+#-----------------------------------------------------------------------------
+
+def boolean_flag(name, configurable, set_help='', unset_help=''):
+    """helper for building basic --trait, --no-trait flags
+    
+    Parameters
+    ----------
+    
+    name : str
+        The name of the flag.
+    configurable : str
+        The 'Class.trait' string of the trait to be set/unset with the flag
+    set_help : unicode
+        help string for --name flag
+    unset_help : unicode
+        help string for --no-name flag
+    
+    Returns
+    -------
+    
+    cfg : dict
+        A dict with two keys: 'name', and 'no-name', for setting and unsetting
+        the trait, respectively.
+    """
+    # default helpstrings
+    set_help = set_help or "set %s=True"%configurable
+    unset_help = unset_help or "set %s=False"%configurable
+    
+    cls,trait = configurable.split('.')
+    
+    setter = Config()
+    setter[cls][trait] = True
+    unsetter = Config()
+    unsetter[cls][trait] = False
+    return {name : (setter, set_help), 'no-'+name : (unsetter, unset_help)}

IPython/config/configurable.py

@@ -1,224 +1,242 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 A base class for objects that are configurable.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 """
 
 #-----------------------------------------------------------------------------
 #  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 copy import deepcopy
 import datetime
 
 from loader import Config
 from IPython.utils.traitlets import HasTraits, Instance
 from IPython.utils.text import indent
 
 
 #-----------------------------------------------------------------------------
 # 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 conigurable 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))
 
     @classmethod
     def class_get_help(cls):
         """Get the help string for this class in ReST format."""
         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_traits.items():
-            help = v.get_metadata('help')
-            header = "%s.%s : %s" % (cls.__name__, k, v.__class__.__name__)
-            final_help.append(header)
-            if help is not None:
-                final_help.append(indent(help, flatten=True))
+        for k,v in cls.class_traits(config=True).iteritems():
+            help = cls.class_get_trait_help(v)
+            final_help.append(help)
         return '\n'.join(final_help)
+    
+    @classmethod
+    def class_get_trait_help(cls, trait):
+        """Get the help string for a single """
+        lines = []
+        header = "%s.%s : %s" % (cls.__name__, trait.name, trait.__class__.__name__)
+        try:
+            dvr = repr(trait.get_default_value())
+        except Exception:
+            dvr = None # ignore defaults we can't construct
+        if dvr is not None:
+            header += ' [default: %s]'%dvr
+        lines.append(header)
+        
+        help = trait.get_metadata('help')
+        if help is not None:
+            lines.append(indent(help, flatten=True))
+        if 'Enum' in trait.__class__.__name__:
+            # include Enum choices
+            lines.append(indent('Choices: %r'%(trait.values,), flatten=True))
+        return '\n'.join(lines)
 
     @classmethod
     def class_print_help(cls):
         print cls.class_get_help()
 
 
 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 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
             # the subclasses instance attribute.
             for subclass in cls.mro():
                 if issubclass(cls, subclass) and \
                 issubclass(subclass, SingletonConfigurable) and \
                 subclass != SingletonConfigurable:
                     subclass._instance = inst
                 else:
                     break
         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