Only include inheritance diagram where it's useful.

IPython/config/configurable.py

@@ -1,351 +1,356 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,(),{})
     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, 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 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/loader.py

@@ -1,696 +1,701 b''
 """A simple configuration system.
 
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.config.loader
+   :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 __builtin__ as builtin_mod
 import os
 import re
 import sys
 
 from IPython.external import argparse
 from IPython.utils.path import filefind, get_ipython_dir
 from IPython.utils import py3compat, text, warn
 from IPython.utils.encoding import DEFAULT_ENCODING
 
 #-----------------------------------------------------------------------------
 # Exceptions
 #-----------------------------------------------------------------------------
 
 
 class ConfigError(Exception):
     pass
 
 class ConfigLoaderError(ConfigError):
     pass
 
 class ConfigFileNotFound(ConfigError):
     pass
 
 class ArgumentError(ConfigLoaderError):
     pass
 
 #-----------------------------------------------------------------------------
 # Argparse fix
 #-----------------------------------------------------------------------------
 
 # Unfortunately argparse by default prints help messages to stderr instead of
 # stdout.  This makes it annoying to capture long help screens at the command
 # line, since one must know how to pipe stderr, which many users don't know how
 # to do.  So we override the print_help method with one that defaults to
 # stdout and use our class instead.
 
 class ArgumentParser(argparse.ArgumentParser):
     """Simple argparse subclass that prints help to stdout by default."""
 
     def print_help(self, file=None):
         if file is None:
             file = sys.stdout
         return super(ArgumentParser, self).print_help(file)
 
     print_help.__doc__ = argparse.ArgumentParser.print_help.__doc__
 
 #-----------------------------------------------------------------------------
 # Config class for holding config information
 #-----------------------------------------------------------------------------
 
 
 class Config(dict):
     """An attribute based dict that can do smart merges."""
 
     def __init__(self, *args, **kwds):
         dict.__init__(self, *args, **kwds)
         # This sets self.__dict__ = self, but it has to be done this way
         # because we are also overriding __setattr__.
         dict.__setattr__(self, '__dict__', self)
 
     def _merge(self, other):
         to_update = {}
         for k, v in other.iteritems():
             if k not in self:
                 to_update[k] = v
             else: # I have this key
                 if isinstance(v, Config):
                     # Recursively merge common sub Configs
                     self[k]._merge(v)
                 else:
                     # Plain updates for non-Configs
                     to_update[k] = v
 
         self.update(to_update)
 
     def _is_section_key(self, key):
         if key[0].upper()==key[0] and not key.startswith('_'):
             return True
         else:
             return False
 
     def __contains__(self, key):
         if self._is_section_key(key):
             return True
         else:
             return super(Config, self).__contains__(key)
     # .has_key is deprecated for dictionaries.
     has_key = __contains__
 
     def _has_section(self, key):
         if self._is_section_key(key):
             if super(Config, self).__contains__(key):
                 return True
         return False
 
     def copy(self):
         return type(self)(dict.copy(self))
 
     def __copy__(self):
         return self.copy()
 
     def __deepcopy__(self, memo):
         import copy
         return type(self)(copy.deepcopy(self.items()))
 
     def __getitem__(self, key):
         # We cannot use directly self._is_section_key, because it triggers
         # infinite recursion on top of PyPy. Instead, we manually fish the
         # bound method.
         is_section_key = self.__class__._is_section_key.__get__(self)
 
         # Because we use this for an exec namespace, we need to delegate
         # the lookup of names in __builtin__ to itself.  This means
         # that you can't have section or attribute names that are
         # builtins.
         try:
             return getattr(builtin_mod, key)
         except AttributeError:
             pass
         if is_section_key(key):
             try:
                 return dict.__getitem__(self, key)
             except KeyError:
                 c = Config()
                 dict.__setitem__(self, key, c)
                 return c
         else:
             return dict.__getitem__(self, key)
 
     def __setitem__(self, key, value):
         # Don't allow names in __builtin__ to be modified.
         if hasattr(builtin_mod, key):
             raise ConfigError('Config variable names cannot have the same name '
                               'as a Python builtin: %s' % key)
         if self._is_section_key(key):
             if not isinstance(value, Config):
                 raise ValueError('values whose keys begin with an uppercase '
                                  'char must be Config instances: %r, %r' % (key, value))
         else:
             dict.__setitem__(self, key, value)
 
     def __getattr__(self, key):
         try:
             return self.__getitem__(key)
         except KeyError as e:
             raise AttributeError(e)
 
     def __setattr__(self, key, value):
         try:
             self.__setitem__(key, value)
         except KeyError as e:
             raise AttributeError(e)
 
     def __delattr__(self, key):
         try:
             dict.__delitem__(self, key)
         except KeyError as e:
             raise AttributeError(e)
 
 
 #-----------------------------------------------------------------------------
 # Config loading classes
 #-----------------------------------------------------------------------------
 
 
 class ConfigLoader(object):
     """A object for loading configurations from just about anywhere.
 
     The resulting configuration is packaged as a :class:`Struct`.
 
     Notes
     -----
     A :class:`ConfigLoader` does one thing: load a config from a source
     (file, command line arguments) and returns the data as a :class:`Struct`.
     There are lots of things that :class:`ConfigLoader` does not do.  It does
     not implement complex logic for finding config files.  It does not handle
     default values or merge multiple configs.  These things need to be
     handled elsewhere.
     """
 
     def __init__(self):
         """A base class for config loaders.
 
         Examples
         --------
 
         >>> cl = ConfigLoader()
         >>> config = cl.load_config()
         >>> config
         {}
         """
         self.clear()
 
     def clear(self):
         self.config = Config()
 
     def load_config(self):
         """Load a config from somewhere, return a :class:`Config` instance.
 
         Usually, this will cause self.config to be set and then returned.
         However, in most cases, :meth:`ConfigLoader.clear` should be called
         to erase any previous state.
         """
         self.clear()
         return self.config
 
 
 class FileConfigLoader(ConfigLoader):
     """A base class for file based configurations.
 
     As we add more file based config loaders, the common logic should go
     here.
     """
     pass
 
 
 class PyFileConfigLoader(FileConfigLoader):
     """A config loader for pure python files.
 
     This calls execfile on a plain python file and looks for attributes
     that are all caps.  These attribute are added to the config Struct.
     """
 
     def __init__(self, filename, path=None):
         """Build a config loader for a filename and path.
 
         Parameters
         ----------
         filename : str
             The file name of the config file.
         path : str, list, tuple
             The path to search for the config file on, or a sequence of
             paths to try in order.
         """
         super(PyFileConfigLoader, self).__init__()
         self.filename = filename
         self.path = path
         self.full_filename = ''
         self.data = None
 
     def load_config(self):
         """Load the config from a file and return it as a Struct."""
         self.clear()
         try:
             self._find_file()
         except IOError as e:
             raise ConfigFileNotFound(str(e))
         self._read_file_as_dict()
         self._convert_to_config()
         return self.config
 
     def _find_file(self):
         """Try to find the file by searching the paths."""
         self.full_filename = filefind(self.filename, self.path)
 
     def _read_file_as_dict(self):
         """Load the config file into self.config, with recursive loading."""
         # This closure is made available in the namespace that is used
         # to exec the config file.  It allows users to call
         # load_subconfig('myconfig.py') to load config files recursively.
         # It needs to be a closure because it has references to self.path
         # and self.config.  The sub-config is loaded with the same path
         # as the parent, but it uses an empty config which is then merged
         # with the parents.
 
         # If a profile is specified, the config file will be loaded
         # from that profile
 
         def load_subconfig(fname, profile=None):
             # import here to prevent circular imports
             from IPython.core.profiledir import ProfileDir, ProfileDirError
             if profile is not None:
                 try:
                     profile_dir = ProfileDir.find_profile_dir_by_name(
                             get_ipython_dir(),
                             profile,
                     )
                 except ProfileDirError:
                     return
                 path = profile_dir.location
             else:
                 path = self.path
             loader = PyFileConfigLoader(fname, path)
             try:
                 sub_config = loader.load_config()
             except ConfigFileNotFound:
                 # Pass silently if the sub config is not there. This happens
                 # when a user s using a profile, but not the default config.
                 pass
             else:
                 self.config._merge(sub_config)
 
         # Again, this needs to be a closure and should be used in config
         # files to get the config being loaded.
         def get_config():
             return self.config
 
         namespace = dict(load_subconfig=load_subconfig, get_config=get_config)
         fs_encoding = sys.getfilesystemencoding() or 'ascii'
         conf_filename = self.full_filename.encode(fs_encoding)
         py3compat.execfile(conf_filename, namespace)
 
     def _convert_to_config(self):
         if self.data is None:
             ConfigLoaderError('self.data does not exist')
 
 
 class CommandLineConfigLoader(ConfigLoader):
     """A config loader for command line arguments.
 
     As we add more command line based loaders, the common logic should go
     here.
     """
 
     def _exec_config_str(self, lhs, rhs):
         """execute self.config.<lhs> = <rhs>
         
         * expands ~ with expanduser
         * tries to assign with raw eval, otherwise assigns with just the string,
           allowing `--C.a=foobar` and `--C.a="foobar"` to be equivalent.  *Not*
           equivalent are `--C.a=4` and `--C.a='4'`.
         """
         rhs = os.path.expanduser(rhs)
         try:
             # Try to see if regular Python syntax will work. This
             # won't handle strings as the quote marks are removed
             # by the system shell.
             value = eval(rhs)
         except (NameError, SyntaxError):
             # This case happens if the rhs is a string.
             value = rhs
 
         exec u'self.config.%s = value' % lhs
 
     def _load_flag(self, cfg):
         """update self.config from a flag, which can be a dict or Config"""
         if isinstance(cfg, (dict, Config)):
             # don't clobber whole config sections, update
             # each section from config:
             for sec,c in cfg.iteritems():
                 self.config[sec].update(c)
         else:
             raise TypeError("Invalid flag: %r" % cfg)
 
 # raw --identifier=value pattern
 # but *also* accept '-' as wordsep, for aliases
 # accepts:  --foo=a
 #           --Class.trait=value
 #           --alias-name=value
 # rejects:  -foo=value
 #           --foo
 #           --Class.trait
 kv_pattern = re.compile(r'\-\-[A-Za-z][\w\-]*(\.[\w\-]+)*\=.*')
 
 # just flags, no assignments, with two *or one* leading '-'
 # accepts:  --foo
 #           -foo-bar-again
 # rejects:  --anything=anything
 #           --two.word
 
 flag_pattern = re.compile(r'\-\-?\w+[\-\w]*$')
 
 class KeyValueConfigLoader(CommandLineConfigLoader):
     """A config loader that loads key value pairs from the command line.
 
     This allows command line options to be gives in the following form::
 
         ipython --profile="foo" --InteractiveShell.autocall=False
     """
 
     def __init__(self, argv=None, aliases=None, flags=None):
         """Create a key value pair config loader.
 
         Parameters
         ----------
         argv : list
             A list that has the form of sys.argv[1:] which has unicode
             elements of the form u"key=value". If this is None (default),
             then sys.argv[1:] will be used.
         aliases : dict
             A dict of aliases for configurable traits.
             Keys are the short aliases, Values are the resolved trait.
             Of the form: `{'alias' : 'Configurable.trait'}`
         flags : dict
             A dict of flags, keyed by str name. Vaues can be Config objects,
             dicts, or "key=value" strings.  If Config or dict, when the flag
             is triggered, The flag is loaded as `self.config.update(m)`.
 
         Returns
         -------
         config : Config
             The resulting Config object.
 
         Examples
         --------
 
             >>> from IPython.config.loader import KeyValueConfigLoader
             >>> cl = KeyValueConfigLoader()
             >>> d = cl.load_config(["--A.name='brian'","--B.number=0"])
             >>> sorted(d.items())
             [('A', {'name': 'brian'}), ('B', {'number': 0})]
         """
         self.clear()
         if argv is None:
             argv = sys.argv[1:]
         self.argv = argv
         self.aliases = aliases or {}
         self.flags = flags or {}
 
 
     def clear(self):
         super(KeyValueConfigLoader, self).clear()
         self.extra_args = []
 
 
     def _decode_argv(self, argv, enc=None):
         """decode argv if bytes, using stin.encoding, falling back on default enc"""
         uargv = []
         if enc is None:
             enc = DEFAULT_ENCODING
         for arg in argv:
             if not isinstance(arg, unicode):
                 # only decode if not already decoded
                 arg = arg.decode(enc)
             uargv.append(arg)
         return uargv
 
 
     def load_config(self, argv=None, aliases=None, flags=None):
         """Parse the configuration and generate the Config object.
 
         After loading, any arguments that are not key-value or
         flags will be stored in self.extra_args - a list of
         unparsed command-line arguments.  This is used for
         arguments such as input files or subcommands.
 
         Parameters
         ----------
         argv : list, optional
             A list that has the form of sys.argv[1:] which has unicode
             elements of the form u"key=value". If this is None (default),
             then self.argv will be used.
         aliases : dict
             A dict of aliases for configurable traits.
             Keys are the short aliases, Values are the resolved trait.
             Of the form: `{'alias' : 'Configurable.trait'}`
         flags : dict
             A dict of flags, keyed by str name. Values can be Config objects
             or dicts.  When the flag is triggered, The config is loaded as
             `self.config.update(cfg)`.
         """
         from IPython.config.configurable import Configurable
 
         self.clear()
         if argv is None:
             argv = self.argv
         if aliases is None:
             aliases = self.aliases
         if flags is None:
             flags = self.flags
 
         # ensure argv is a list of unicode strings:
         uargv = self._decode_argv(argv)
         for idx,raw in enumerate(uargv):
             # strip leading '-'
             item = raw.lstrip('-')
 
             if raw == '--':
                 # don't parse arguments after '--'
                 # this is useful for relaying arguments to scripts, e.g.
                 # ipython -i foo.py --pylab=qt -- args after '--' go-to-foo.py
                 self.extra_args.extend(uargv[idx+1:])
                 break
 
             if kv_pattern.match(raw):
                 lhs,rhs = item.split('=',1)
                 # Substitute longnames for aliases.
                 if lhs in aliases:
                     lhs = aliases[lhs]
                 if '.' not in lhs:
                     # probably a mistyped alias, but not technically illegal
                     warn.warn("Unrecognized alias: '%s', it will probably have no effect."%lhs)
                 try:
                     self._exec_config_str(lhs, rhs)
                 except Exception:
                     raise ArgumentError("Invalid argument: '%s'" % raw)
 
             elif flag_pattern.match(raw):
                 if item in flags:
                     cfg,help = flags[item]
                     self._load_flag(cfg)
                 else:
                     raise ArgumentError("Unrecognized flag: '%s'"%raw)
             elif raw.startswith('-'):
                 kv = '--'+item
                 if kv_pattern.match(kv):
                     raise ArgumentError("Invalid argument: '%s', did you mean '%s'?"%(raw, kv))
                 else:
                     raise ArgumentError("Invalid argument: '%s'"%raw)
             else:
                 # keep all args that aren't valid in a list,
                 # in case our parent knows what to do with them.
                 self.extra_args.append(item)
         return self.config
 
 class ArgParseConfigLoader(CommandLineConfigLoader):
     """A loader that uses the argparse module to load from the command line."""
 
     def __init__(self, argv=None, aliases=None, flags=None, *parser_args, **parser_kw):
         """Create a config loader for use with argparse.
 
         Parameters
         ----------
 
         argv : optional, list
           If given, used to read command-line arguments from, otherwise
           sys.argv[1:] is used.
 
         parser_args : tuple
           A tuple of positional arguments that will be passed to the
           constructor of :class:`argparse.ArgumentParser`.
 
         parser_kw : dict
           A tuple of keyword arguments that will be passed to the
           constructor of :class:`argparse.ArgumentParser`.
 
         Returns
         -------
         config : Config
             The resulting Config object.
         """
         super(CommandLineConfigLoader, self).__init__()
         self.clear()
         if argv is None:
             argv = sys.argv[1:]
         self.argv = argv
         self.aliases = aliases or {}
         self.flags = flags or {}
 
         self.parser_args = parser_args
         self.version = parser_kw.pop("version", None)
         kwargs = dict(argument_default=argparse.SUPPRESS)
         kwargs.update(parser_kw)
         self.parser_kw = kwargs
 
     def load_config(self, argv=None, aliases=None, flags=None):
         """Parse command line arguments and return as a Config object.
 
         Parameters
         ----------
 
         args : optional, list
           If given, a list with the structure of sys.argv[1:] to parse
           arguments from. If not given, the instance's self.argv attribute
           (given at construction time) is used."""
         self.clear()
         if argv is None:
             argv = self.argv
         if aliases is None:
             aliases = self.aliases
         if flags is None:
             flags = self.flags
         self._create_parser(aliases, flags)
         self._parse_args(argv)
         self._convert_to_config()
         return self.config
 
     def get_extra_args(self):
         if hasattr(self, 'extra_args'):
             return self.extra_args
         else:
             return []
 
     def _create_parser(self, aliases=None, flags=None):
         self.parser = ArgumentParser(*self.parser_args, **self.parser_kw)
         self._add_arguments(aliases, flags)
 
     def _add_arguments(self, aliases=None, flags=None):
         raise NotImplementedError("subclasses must implement _add_arguments")
 
     def _parse_args(self, args):
         """self.parser->self.parsed_data"""
         # decode sys.argv to support unicode command-line options
         enc = DEFAULT_ENCODING
         uargs = [py3compat.cast_unicode(a, enc) for a in args]
         self.parsed_data, self.extra_args = self.parser.parse_known_args(uargs)
 
     def _convert_to_config(self):
         """self.parsed_data->self.config"""
         for k, v in vars(self.parsed_data).iteritems():
             exec "self.config.%s = v"%k in locals(), globals()
 
 class KVArgParseConfigLoader(ArgParseConfigLoader):
     """A config loader that loads aliases and flags with argparse,
     but will use KVLoader for the rest.  This allows better parsing
     of common args, such as `ipython -c 'print 5'`, but still gets
     arbitrary config with `ipython --InteractiveShell.use_readline=False`"""
 
     def _add_arguments(self, aliases=None, flags=None):
         self.alias_flags = {}
         # print aliases, flags
         if aliases is None:
             aliases = self.aliases
         if flags is None:
             flags = self.flags
         paa = self.parser.add_argument
         for key,value in aliases.iteritems():
             if key in flags:
                 # flags
                 nargs = '?'
             else:
                 nargs = None
             if len(key) is 1:
                 paa('-'+key, '--'+key, type=unicode, dest=value, nargs=nargs)
             else:
                 paa('--'+key, type=unicode, dest=value, nargs=nargs)
         for key, (value, help) in flags.iteritems():
             if key in self.aliases:
                 #
                 self.alias_flags[self.aliases[key]] = value
                 continue
             if len(key) is 1:
                 paa('-'+key, '--'+key, action='append_const', dest='_flags', const=value)
             else:
                 paa('--'+key, action='append_const', dest='_flags', const=value)
 
     def _convert_to_config(self):
         """self.parsed_data->self.config, parse unrecognized extra args via KVLoader."""
         # remove subconfigs list from namespace before transforming the Namespace
         if '_flags' in self.parsed_data:
             subcs = self.parsed_data._flags
             del self.parsed_data._flags
         else:
             subcs = []
 
         for k, v in vars(self.parsed_data).iteritems():
             if v is None:
                 # it was a flag that shares the name of an alias
                 subcs.append(self.alias_flags[k])
             else:
                 # eval the KV assignment
                 self._exec_config_str(k, v)
 
         for subc in subcs:
             self._load_flag(subc)
 
         if self.extra_args:
             sub_parser = KeyValueConfigLoader()
             sub_parser.load_config(self.extra_args)
             self.config._merge(sub_parser.config)
             self.extra_args = sub_parser.extra_args
 
 
 def load_pyconfig_files(config_files, path):
     """Load multiple Python config files, merging each of them in turn.
 
     Parameters
     ==========
     config_files : list of str
         List of config files names to load and merge into the config.
     path : unicode
         The full path to the location of the config files.
     """
     config = Config()
     for cf in config_files:
         loader = PyFileConfigLoader(cf, path=path)
         try:
             next_config = loader.load_config()
         except ConfigFileNotFound:
             pass
         except:
             raise
         else:
             config._merge(next_config)
     return config

IPython/core/formatters.py

@@ -1,621 +1,625 b''
 # -*- coding: utf-8 -*-
 """Display formatters.
 
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.core.formatters
+   :parts: 3
 
 Authors:
 
 * Robert Kern
 * Brian Granger
 """
 #-----------------------------------------------------------------------------
 # Copyright (C) 2010-2011, IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # Stdlib imports
 import abc
 import sys
 # We must use StringIO, as cStringIO doesn't handle unicode properly.
 from StringIO import StringIO
 
 # Our own imports
 from IPython.config.configurable import Configurable
 from IPython.lib import pretty
 from IPython.utils.traitlets import Bool, Dict, Integer, Unicode, CUnicode, ObjectName
 from IPython.utils.py3compat import unicode_to_str
 
 
 #-----------------------------------------------------------------------------
 # The main DisplayFormatter class
 #-----------------------------------------------------------------------------
 
 
 class DisplayFormatter(Configurable):
 
     # When set to true only the default plain text formatter will be used.
     plain_text_only = Bool(False, config=True)
 
     # A dict of formatter whose keys are format types (MIME types) and whose
     # values are subclasses of BaseFormatter.
     formatters = Dict()
     def _formatters_default(self):
         """Activate the default formatters."""
         formatter_classes = [
             PlainTextFormatter,
             HTMLFormatter,
             SVGFormatter,
             PNGFormatter,
             JPEGFormatter,
             LatexFormatter,
             JSONFormatter,
             JavascriptFormatter
         ]
         d = {}
         for cls in formatter_classes:
             f = cls(config=self.config)
             d[f.format_type] = f
         return d
 
     def format(self, obj, include=None, exclude=None):
         """Return a format data dict for an object.
 
         By default all format types will be computed.
 
         The following MIME types are currently implemented:
 
         * text/plain
         * text/html
         * text/latex
         * application/json
         * application/javascript
         * image/png
         * image/jpeg
         * image/svg+xml
 
         Parameters
         ----------
         obj : object
             The Python object whose format data will be computed.
         include : list or tuple, optional
             A list of format type strings (MIME types) to include in the
             format data dict. If this is set *only* the format types included
             in this list will be computed.
         exclude : list or tuple, optional
             A list of format type string (MIME types) to exclue in the format
             data dict. If this is set all format types will be computed,
             except for those included in this argument.
 
         Returns
         -------
         format_dict : dict
             A dictionary of key/value pairs, one or each format that was
             generated for the object. The keys are the format types, which
             will usually be MIME type strings and the values and JSON'able
             data structure containing the raw data for the representation in
             that format.
         """
         format_dict = {}
 
         # If plain text only is active
         if self.plain_text_only:
             formatter = self.formatters['text/plain']
             try:
                 data = formatter(obj)
             except:
                 # FIXME: log the exception
                 raise
             if data is not None:
                 format_dict['text/plain'] = data
             return format_dict
 
         for format_type, formatter in self.formatters.items():
             if include is not None:
                 if format_type not in include:
                     continue
             if exclude is not None:
                 if format_type in exclude:
                     continue
             try:
                 data = formatter(obj)
             except:
                 # FIXME: log the exception
                 raise
             if data is not None:
                 format_dict[format_type] = data
         return format_dict
 
     @property
     def format_types(self):
         """Return the format types (MIME types) of the active formatters."""
         return self.formatters.keys()
 
 
 #-----------------------------------------------------------------------------
 # Formatters for specific format types (text, html, svg, etc.)
 #-----------------------------------------------------------------------------
 
 
 class FormatterABC(object):
     """ Abstract base class for Formatters.
 
     A formatter is a callable class that is responsible for computing the
     raw format data for a particular format type (MIME type). For example,
     an HTML formatter would have a format type of `text/html` and would return
     the HTML representation of the object when called.
     """
     __metaclass__ = abc.ABCMeta
 
     # The format type of the data returned, usually a MIME type.
     format_type = 'text/plain'
 
     # Is the formatter enabled...
     enabled = True
 
     @abc.abstractmethod
     def __call__(self, obj):
         """Return a JSON'able representation of the object.
 
         If the object cannot be formatted by this formatter, then return None
         """
         try:
             return repr(obj)
         except TypeError:
             return None
 
 
 class BaseFormatter(Configurable):
     """A base formatter class that is configurable.
 
     This formatter should usually be used as the base class of all formatters.
     It is a traited :class:`Configurable` class and includes an extensible
     API for users to determine how their objects are formatted. The following
     logic is used to find a function to format an given object.
 
     1. The object is introspected to see if it has a method with the name
        :attr:`print_method`. If is does, that object is passed to that method
        for formatting.
     2. If no print method is found, three internal dictionaries are consulted
        to find print method: :attr:`singleton_printers`, :attr:`type_printers`
        and :attr:`deferred_printers`.
 
     Users should use these dictionaries to register functions that will be
     used to compute the format data for their objects (if those objects don't
     have the special print methods). The easiest way of using these
     dictionaries is through the :meth:`for_type` and :meth:`for_type_by_name`
     methods.
 
     If no function/callable is found to compute the format data, ``None`` is
     returned and this format type is not used.
     """
 
     format_type = Unicode('text/plain')
 
     enabled = Bool(True, config=True)
 
     print_method = ObjectName('__repr__')
 
     # The singleton printers.
     # Maps the IDs of the builtin singleton objects to the format functions.
     singleton_printers = Dict(config=True)
     def _singleton_printers_default(self):
         return {}
 
     # The type-specific printers.
     # Map type objects to the format functions.
     type_printers = Dict(config=True)
     def _type_printers_default(self):
         return {}
 
     # The deferred-import type-specific printers.
     # Map (modulename, classname) pairs to the format functions.
     deferred_printers = Dict(config=True)
     def _deferred_printers_default(self):
         return {}
 
     def __call__(self, obj):
         """Compute the format for an object."""
         if self.enabled:
             obj_id = id(obj)
             try:
                 obj_class = getattr(obj, '__class__', None) or type(obj)
                 # First try to find registered singleton printers for the type.
                 try:
                     printer = self.singleton_printers[obj_id]
                 except (TypeError, KeyError):
                     pass
                 else:
                     return printer(obj)
                 # Next look for type_printers.
                 for cls in pretty._get_mro(obj_class):
                     if cls in self.type_printers:
                         return self.type_printers[cls](obj)
                     else:
                         printer = self._in_deferred_types(cls)
                         if printer is not None:
                             return printer(obj)
                 # Finally look for special method names.
                 if hasattr(obj_class, self.print_method):
                     printer = getattr(obj_class, self.print_method)
                     return printer(obj)
                 return None
             except Exception:
                 pass
         else:
             return None
 
     def for_type(self, typ, func):
         """Add a format function for a given type.
 
         Parameters
         -----------
         typ : class
             The class of the object that will be formatted using `func`.
         func : callable
             The callable that will be called to compute the format data. The
             call signature of this function is simple, it must take the
             object to be formatted and return the raw data for the given
             format. Subclasses may use a different call signature for the
             `func` argument.
         """
         oldfunc = self.type_printers.get(typ, None)
         if func is not None:
             # To support easy restoration of old printers, we need to ignore
             # Nones.
             self.type_printers[typ] = func
         return oldfunc
 
     def for_type_by_name(self, type_module, type_name, func):
         """Add a format function for a type specified by the full dotted
         module and name of the type, rather than the type of the object.
 
         Parameters
         ----------
         type_module : str
             The full dotted name of the module the type is defined in, like
             ``numpy``.
         type_name : str
             The name of the type (the class name), like ``dtype``
         func : callable
             The callable that will be called to compute the format data. The
             call signature of this function is simple, it must take the
             object to be formatted and return the raw data for the given
             format. Subclasses may use a different call signature for the
             `func` argument.
         """
         key = (type_module, type_name)
         oldfunc = self.deferred_printers.get(key, None)
         if func is not None:
             # To support easy restoration of old printers, we need to ignore
             # Nones.
             self.deferred_printers[key] = func
         return oldfunc
 
     def _in_deferred_types(self, cls):
         """
         Check if the given class is specified in the deferred type registry.
 
         Returns the printer from the registry if it exists, and None if the
         class is not in the registry. Successful matches will be moved to the
         regular type registry for future use.
         """
         mod = getattr(cls, '__module__', None)
         name = getattr(cls, '__name__', None)
         key = (mod, name)
         printer = None
         if key in self.deferred_printers:
             # Move the printer over to the regular registry.
             printer = self.deferred_printers.pop(key)
             self.type_printers[cls] = printer
         return printer
 
 
 class PlainTextFormatter(BaseFormatter):
     """The default pretty-printer.
 
     This uses :mod:`IPython.lib.pretty` to compute the format data of
     the object. If the object cannot be pretty printed, :func:`repr` is used.
     See the documentation of :mod:`IPython.lib.pretty` for details on
     how to write pretty printers.  Here is a simple example::
 
         def dtype_pprinter(obj, p, cycle):
             if cycle:
                 return p.text('dtype(...)')
             if hasattr(obj, 'fields'):
                 if obj.fields is None:
                     p.text(repr(obj))
                 else:
                     p.begin_group(7, 'dtype([')
                     for i, field in enumerate(obj.descr):
                         if i > 0:
                             p.text(',')
                             p.breakable()
                         p.pretty(field)
                     p.end_group(7, '])')
     """
 
     # The format type of data returned.
     format_type = Unicode('text/plain')
 
     # This subclass ignores this attribute as it always need to return
     # something.
     enabled = Bool(True, config=False)
 
     # Look for a _repr_pretty_ methods to use for pretty printing.
     print_method = ObjectName('_repr_pretty_')
 
     # Whether to pretty-print or not.
     pprint = Bool(True, config=True)
 
     # Whether to be verbose or not.
     verbose = Bool(False, config=True)
 
     # The maximum width.
     max_width = Integer(79, config=True)
 
     # The newline character.
     newline = Unicode('\n', config=True)
 
     # format-string for pprinting floats
     float_format = Unicode('%r')
     # setter for float precision, either int or direct format-string
     float_precision = CUnicode('', config=True)
 
     def _float_precision_changed(self, name, old, new):
         """float_precision changed, set float_format accordingly.
 
         float_precision can be set by int or str.
         This will set float_format, after interpreting input.
         If numpy has been imported, numpy print precision will also be set.
 
         integer `n` sets format to '%.nf', otherwise, format set directly.
 
         An empty string returns to defaults (repr for float, 8 for numpy).
 
         This parameter can be set via the '%precision' magic.
         """
 
         if '%' in new:
             # got explicit format string
             fmt = new
             try:
                 fmt%3.14159
             except Exception:
                 raise ValueError("Precision must be int or format string, not %r"%new)
         elif new:
             # otherwise, should be an int
             try:
                 i = int(new)
                 assert i >= 0
             except ValueError:
                 raise ValueError("Precision must be int or format string, not %r"%new)
             except AssertionError:
                 raise ValueError("int precision must be non-negative, not %r"%i)
 
             fmt = '%%.%if'%i
             if 'numpy' in sys.modules:
                 # set numpy precision if it has been imported
                 import numpy
                 numpy.set_printoptions(precision=i)
         else:
             # default back to repr
             fmt = '%r'
             if 'numpy' in sys.modules:
                 import numpy
                 # numpy default is 8
                 numpy.set_printoptions(precision=8)
         self.float_format = fmt
 
     # Use the default pretty printers from IPython.lib.pretty.
     def _singleton_printers_default(self):
         return pretty._singleton_pprinters.copy()
 
     def _type_printers_default(self):
         d = pretty._type_pprinters.copy()
         d[float] = lambda obj,p,cycle: p.text(self.float_format%obj)
         return d
 
     def _deferred_printers_default(self):
         return pretty._deferred_type_pprinters.copy()
 
     #### FormatterABC interface ####
 
     def __call__(self, obj):
         """Compute the pretty representation of the object."""
         if not self.pprint:
             try:
                 return repr(obj)
             except TypeError:
                 return ''
         else:
             # This uses use StringIO, as cStringIO doesn't handle unicode.
             stream = StringIO()
             # self.newline.encode() is a quick fix for issue gh-597. We need to
             # ensure that stream does not get a mix of unicode and bytestrings,
             # or it will cause trouble.
             printer = pretty.RepresentationPrinter(stream, self.verbose,
                 self.max_width, unicode_to_str(self.newline),
                 singleton_pprinters=self.singleton_printers,
                 type_pprinters=self.type_printers,
                 deferred_pprinters=self.deferred_printers)
             printer.pretty(obj)
             printer.flush()
             return stream.getvalue()
 
 
 class HTMLFormatter(BaseFormatter):
     """An HTML formatter.
 
     To define the callables that compute the HTML representation of your
     objects, define a :meth:`_repr_html_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be a valid HTML snippet that
     could be injected into an existing DOM. It should *not* include the
     ```<html>`` or ```<body>`` tags.
     """
     format_type = Unicode('text/html')
 
     print_method = ObjectName('_repr_html_')
 
 
 class SVGFormatter(BaseFormatter):
     """An SVG formatter.
 
     To define the callables that compute the SVG representation of your
     objects, define a :meth:`_repr_svg_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be valid SVG enclosed in
     ```<svg>``` tags, that could be injected into an existing DOM. It should
     *not* include the ```<html>`` or ```<body>`` tags.
     """
     format_type = Unicode('image/svg+xml')
 
     print_method = ObjectName('_repr_svg_')
 
 
 class PNGFormatter(BaseFormatter):
     """A PNG formatter.
 
     To define the callables that compute the PNG representation of your
     objects, define a :meth:`_repr_png_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be raw PNG data, *not*
     base64 encoded.
     """
     format_type = Unicode('image/png')
 
     print_method = ObjectName('_repr_png_')
 
 
 class JPEGFormatter(BaseFormatter):
     """A JPEG formatter.
 
     To define the callables that compute the JPEG representation of your
     objects, define a :meth:`_repr_jpeg_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be raw JPEG data, *not*
     base64 encoded.
     """
     format_type = Unicode('image/jpeg')
 
     print_method = ObjectName('_repr_jpeg_')
 
 
 class LatexFormatter(BaseFormatter):
     """A LaTeX formatter.
 
     To define the callables that compute the LaTeX representation of your
     objects, define a :meth:`_repr_latex_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be a valid LaTeX equation,
     enclosed in either ```$```, ```$$``` or another LaTeX equation
     environment.
     """
     format_type = Unicode('text/latex')
 
     print_method = ObjectName('_repr_latex_')
 
 
 class JSONFormatter(BaseFormatter):
     """A JSON string formatter.
 
     To define the callables that compute the JSON string representation of
     your objects, define a :meth:`_repr_json_` method or use the :meth:`for_type`
     or :meth:`for_type_by_name` methods to register functions that handle
     this.
 
     The return value of this formatter should be a valid JSON string.
     """
     format_type = Unicode('application/json')
 
     print_method = ObjectName('_repr_json_')
 
 
 class JavascriptFormatter(BaseFormatter):
     """A Javascript formatter.
 
     To define the callables that compute the Javascript representation of
     your objects, define a :meth:`_repr_javascript_` method or use the
     :meth:`for_type` or :meth:`for_type_by_name` methods to register functions
     that handle this.
 
     The return value of this formatter should be valid Javascript code and
     should *not* be enclosed in ```<script>``` tags.
     """
     format_type = Unicode('application/javascript')
 
     print_method = ObjectName('_repr_javascript_')
 
 FormatterABC.register(BaseFormatter)
 FormatterABC.register(PlainTextFormatter)
 FormatterABC.register(HTMLFormatter)
 FormatterABC.register(SVGFormatter)
 FormatterABC.register(PNGFormatter)
 FormatterABC.register(JPEGFormatter)
 FormatterABC.register(LatexFormatter)
 FormatterABC.register(JSONFormatter)
 FormatterABC.register(JavascriptFormatter)
 
 
 def format_display_data(obj, include=None, exclude=None):
     """Return a format data dict for an object.
 
     By default all format types will be computed.
 
     The following MIME types are currently implemented:
 
     * text/plain
     * text/html
     * text/latex
     * application/json
     * application/javascript
     * image/png
     * image/jpeg
     * image/svg+xml
 
     Parameters
     ----------
     obj : object
         The Python object whose format data will be computed.
 
     Returns
     -------
     format_dict : dict
         A dictionary of key/value pairs, one or each format that was
         generated for the object. The keys are the format types, which
         will usually be MIME type strings and the values and JSON'able
         data structure containing the raw data for the representation in
         that format.
     include : list or tuple, optional
         A list of format type strings (MIME types) to include in the
         format data dict. If this is set *only* the format types included
         in this list will be computed.
     exclude : list or tuple, optional
         A list of format type string (MIME types) to exclue in the format
         data dict. If this is set all format types will be computed,
         except for those included in this argument.
     """
     from IPython.core.interactiveshell import InteractiveShell
 
     InteractiveShell.instance().display_formatter.format(
         obj,
         include,
         exclude
     )
 

IPython/core/magic_arguments.py

@@ -1,241 +1,246 b''
 ''' A decorator-based method of constructing IPython magics with `argparse`
 option handling.
 
 New magic functions can be defined like so::
 
     from IPython.core.magic_arguments import (argument, magic_arguments,
         parse_argstring)
 
     @magic_arguments()
     @argument('-o', '--option', help='An optional argument.')
     @argument('arg', type=int, help='An integer positional argument.')
     def magic_cool(self, arg):
         """ A really cool magic command.
 
     """
         args = parse_argstring(magic_cool, arg)
         ...
 
 The `@magic_arguments` decorator marks the function as having argparse arguments.
 The `@argument` decorator adds an argument using the same syntax as argparse's
 `add_argument()` method. More sophisticated uses may also require the
 `@argument_group` or `@kwds` decorator to customize the formatting and the
 parsing.
 
 Help text for the magic is automatically generated from the docstring and the
 arguments::
 
     In[1]: %cool?
         %cool [-o OPTION] arg
         
         A really cool magic command.
         
         positional arguments:
           arg                   An integer positional argument.
         
         optional arguments:
           -o OPTION, --option OPTION
                                 An optional argument.
 
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.core.magic_arguments
+   :parts: 3
+
 '''
 #-----------------------------------------------------------------------------
 # Copyright (C) 2010-2011, IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file COPYING.txt, distributed with this software.
 #-----------------------------------------------------------------------------
 
 # Our own imports
 from IPython.external import argparse
 from IPython.core.error import UsageError
 from IPython.utils.process import arg_split
 from IPython.utils.text import dedent
 
 class MagicHelpFormatter(argparse.RawDescriptionHelpFormatter):
     """ A HelpFormatter which dedents but otherwise preserves indentation.
     """
     def _fill_text(self, text, width, indent):
         return argparse.RawDescriptionHelpFormatter._fill_text(self, dedent(text), width, indent)
 
 class MagicArgumentParser(argparse.ArgumentParser):
     """ An ArgumentParser tweaked for use by IPython magics.
     """
     def __init__(self,
                  prog=None,
                  usage=None,
                  description=None,
                  epilog=None,
                  parents=None,
                  formatter_class=MagicHelpFormatter,
                  prefix_chars='-',
                  argument_default=None,
                  conflict_handler='error',
                  add_help=False):
         if parents is None:
             parents = []
         super(MagicArgumentParser, self).__init__(prog=prog, usage=usage,
             description=description, epilog=epilog,
             parents=parents, formatter_class=formatter_class,
             prefix_chars=prefix_chars, argument_default=argument_default,
             conflict_handler=conflict_handler, add_help=add_help)
 
     def error(self, message):
         """ Raise a catchable error instead of exiting.
         """
         raise UsageError(message)
 
     def parse_argstring(self, argstring):
         """ Split a string into an argument list and parse that argument list.
         """
         argv = arg_split(argstring)
         return self.parse_args(argv)
 
 
 def construct_parser(magic_func):
     """ Construct an argument parser using the function decorations.
     """
     kwds = getattr(magic_func, 'argcmd_kwds', {})
     if 'description' not in kwds:
         kwds['description'] = getattr(magic_func, '__doc__', None)
     arg_name = real_name(magic_func)
     parser = MagicArgumentParser(arg_name, **kwds)
     # Reverse the list of decorators in order to apply them in the
     # order in which they appear in the source.
     group = None
     for deco in magic_func.decorators[::-1]:
         result = deco.add_to_parser(parser, group)
         if result is not None:
             group = result
 
     # Replace the starting 'usage: ' with IPython's %.
     help_text = parser.format_help()
     if help_text.startswith('usage: '):
         help_text = help_text.replace('usage: ', '%', 1)
     else:
         help_text = '%' + help_text
 
     # Replace the magic function's docstring with the full help text.
     magic_func.__doc__ = help_text
 
     return parser
 
 
 def parse_argstring(magic_func, argstring):
     """ Parse the string of arguments for the given magic function.
     """
     return magic_func.parser.parse_argstring(argstring)
 
 
 def real_name(magic_func):
     """ Find the real name of the magic.
     """
     magic_name = magic_func.__name__
     if magic_name.startswith('magic_'):
         magic_name = magic_name[len('magic_'):]
     return getattr(magic_func, 'argcmd_name', magic_name)
 
 
 class ArgDecorator(object):
     """ Base class for decorators to add ArgumentParser information to a method.
     """
 
     def __call__(self, func):
         if not getattr(func, 'has_arguments', False):
             func.has_arguments = True
             func.decorators = []
         func.decorators.append(self)
         return func
 
     def add_to_parser(self, parser, group):
         """ Add this object's information to the parser, if necessary.
         """
         pass
 
 
 class magic_arguments(ArgDecorator):
     """ Mark the magic as having argparse arguments and possibly adjust the
     name.
     """
 
     def __init__(self, name=None):
         self.name = name
 
     def __call__(self, func):
         if not getattr(func, 'has_arguments', False):
             func.has_arguments = True
             func.decorators = []
         if self.name is not None:
             func.argcmd_name = self.name
         # This should be the first decorator in the list of decorators, thus the
         # last to execute. Build the parser.
         func.parser = construct_parser(func)
         return func
 
 
 class ArgMethodWrapper(ArgDecorator):
 
     """
     Base class to define a wrapper for ArgumentParser method.
 
     Child class must define either `_method_name` or `add_to_parser`.
 
     """
 
     _method_name = None
 
     def __init__(self, *args, **kwds):
         self.args = args
         self.kwds = kwds
 
     def add_to_parser(self, parser, group):
         """ Add this object's information to the parser.
         """
         if group is not None:
             parser = group
         getattr(parser, self._method_name)(*self.args, **self.kwds)
         return None
 
 
 class argument(ArgMethodWrapper):
     """ Store arguments and keywords to pass to add_argument().
 
     Instances also serve to decorate command methods.
     """
     _method_name = 'add_argument'
 
 
 class defaults(ArgMethodWrapper):
     """ Store arguments and keywords to pass to set_defaults().
 
     Instances also serve to decorate command methods.
     """
     _method_name = 'set_defaults'
 
 
 class argument_group(ArgMethodWrapper):
     """ Store arguments and keywords to pass to add_argument_group().
 
     Instances also serve to decorate command methods.
     """
 
     def add_to_parser(self, parser, group):
         """ Add this object's information to the parser.
         """
         return parser.add_argument_group(*self.args, **self.kwds)
 
 
 class kwds(ArgDecorator):
     """ Provide other keywords to the sub-parser constructor.
     """
     def __init__(self, **kwds):
         self.kwds = kwds
 
     def __call__(self, func):
         func = super(kwds, self).__call__(func)
         func.argcmd_kwds = self.kwds
         return func
 
 
 __all__ = ['magic_arguments', 'argument', 'argument_group', 'kwds',
     'parse_argstring']

IPython/core/ultratb.py

@@ -1,1242 +1,1247 b''
 # -*- coding: utf-8 -*-
 """
 ultratb.py -- Spice up your tracebacks!
 
 * ColorTB
 I've always found it a bit hard to visually parse tracebacks in Python.  The
 ColorTB class is a solution to that problem.  It colors the different parts of a
 traceback in a manner similar to what you would expect from a syntax-highlighting
 text editor.
 
 Installation instructions for ColorTB:
     import sys,ultratb
     sys.excepthook = ultratb.ColorTB()
 
 * VerboseTB
 I've also included a port of Ka-Ping Yee's "cgitb.py" that produces all kinds
 of useful info when a traceback occurs.  Ping originally had it spit out HTML
 and intended it for CGI programmers, but why should they have all the fun?  I
 altered it to spit out colored text to the terminal.  It's a bit overwhelming,
 but kind of neat, and maybe useful for long-running programs that you believe
 are bug-free.  If a crash *does* occur in that type of program you want details.
 Give it a shot--you'll love it or you'll hate it.
 
 Note:
 
   The Verbose mode prints the variables currently visible where the exception
   happened (shortening their strings if too long). This can potentially be
   very slow, if you happen to have a huge data structure whose string
   representation is complex to compute. Your computer may appear to freeze for
   a while with cpu usage at 100%. If this occurs, you can cancel the traceback
   with Ctrl-C (maybe hitting it more than once).
 
   If you encounter this kind of situation often, you may want to use the
   Verbose_novars mode instead of the regular Verbose, which avoids formatting
   variables (but otherwise includes the information and context given by
   Verbose).
 
 
 Installation instructions for ColorTB:
     import sys,ultratb
     sys.excepthook = ultratb.VerboseTB()
 
 Note:  Much of the code in this module was lifted verbatim from the standard
 library module 'traceback.py' and Ka-Ping Yee's 'cgitb.py'.
 
 * Color schemes
 The colors are defined in the class TBTools through the use of the
 ColorSchemeTable class. Currently the following exist:
 
   - NoColor: allows all of this module to be used in any terminal (the color
   escapes are just dummy blank strings).
 
   - Linux: is meant to look good in a terminal like the Linux console (black
   or very dark background).
 
   - LightBG: similar to Linux but swaps dark/light colors to be more readable
   in light background terminals.
 
 You can implement other color schemes easily, the syntax is fairly
 self-explanatory. Please send back new schemes you develop to the author for
 possible inclusion in future releases.
+
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.core.ultratb
+   :parts: 3
 """
 
 #*****************************************************************************
 #       Copyright (C) 2001 Nathaniel Gray <[e-mail]>
 #       Copyright (C) 2001-2004 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from __future__ import unicode_literals
 
 import inspect
 import keyword
 import linecache
 import os
 import pydoc
 import re
 import sys
 import time
 import tokenize
 import traceback
 import types
 
 try:                           # Python 2
     generate_tokens = tokenize.generate_tokens
 except AttributeError:         # Python 3
     generate_tokens = tokenize.tokenize
 
 # For purposes of monkeypatching inspect to fix a bug in it.
 from inspect import getsourcefile, getfile, getmodule,\
      ismodule, isclass, ismethod, isfunction, istraceback, isframe, iscode
 
 # IPython's own modules
 # Modified pdb which doesn't damage IPython's readline handling
 from IPython.core import debugger, ipapi
 from IPython.core.display_trap import DisplayTrap
 from IPython.core.excolors import exception_colors
 from IPython.utils import PyColorize
 from IPython.utils import io
 from IPython.utils import path as util_path
 from IPython.utils import py3compat
 from IPython.utils import pyfile
 from IPython.utils import ulinecache
 from IPython.utils.data import uniq_stable
 from IPython.utils.openpy import read_py_file
 from IPython.utils.warn import info, error
 
 # Globals
 # amount of space to put line numbers before verbose tracebacks
 INDENT_SIZE = 8
 
 # Default color scheme.  This is used, for example, by the traceback
 # formatter.  When running in an actual IPython instance, the user's rc.colors
 # value is used, but havinga module global makes this functionality available
 # to users of ultratb who are NOT running inside ipython.
 DEFAULT_SCHEME = 'NoColor'
 
 #---------------------------------------------------------------------------
 # Code begins
 
 # Utility functions
 def inspect_error():
     """Print a message about internal inspect errors.
 
     These are unfortunately quite common."""
 
     error('Internal Python error in the inspect module.\n'
           'Below is the traceback from this internal error.\n')
 
 # This function is a monkeypatch we apply to the Python inspect module. We have
 # now found when it's needed (see discussion on issue gh-1456), and we have a
 # test case (IPython.core.tests.test_ultratb.ChangedPyFileTest) that fails if
 # the monkeypatch is not applied. TK, Aug 2012.
 def findsource(object):
     """Return the entire source file and starting line number for an object.
 
     The argument may be a module, class, method, function, traceback, frame,
     or code object.  The source code is returned as a list of all the lines
     in the file and the line number indexes a line in that list.  An IOError
     is raised if the source code cannot be retrieved.
 
     FIXED version with which we monkeypatch the stdlib to work around a bug."""
 
     file = getsourcefile(object) or getfile(object)
     # If the object is a frame, then trying to get the globals dict from its
     # module won't work. Instead, the frame object itself has the globals
     # dictionary.
     globals_dict = None
     if inspect.isframe(object):
         # XXX: can this ever be false?
         globals_dict = object.f_globals
     else:
         module = getmodule(object, file)
         if module:
             globals_dict = module.__dict__
     lines = linecache.getlines(file, globals_dict)
     if not lines:
         raise IOError('could not get source code')
 
     if ismodule(object):
         return lines, 0
 
     if isclass(object):
         name = object.__name__
         pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
         # make some effort to find the best matching class definition:
         # use the one with the least indentation, which is the one
         # that's most probably not inside a function definition.
         candidates = []
         for i in range(len(lines)):
             match = pat.match(lines[i])
             if match:
                 # if it's at toplevel, it's already the best one
                 if lines[i][0] == 'c':
                     return lines, i
                 # else add whitespace to candidate list
                 candidates.append((match.group(1), i))
         if candidates:
             # this will sort by whitespace, and by line number,
             # less whitespace first
             candidates.sort()
             return lines, candidates[0][1]
         else:
             raise IOError('could not find class definition')
 
     if ismethod(object):
         object = object.im_func
     if isfunction(object):
         object = object.func_code
     if istraceback(object):
         object = object.tb_frame
     if isframe(object):
         object = object.f_code
     if iscode(object):
         if not hasattr(object, 'co_firstlineno'):
             raise IOError('could not find function definition')
         pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
         pmatch = pat.match
         # fperez - fix: sometimes, co_firstlineno can give a number larger than
         # the length of lines, which causes an error.  Safeguard against that.
         lnum = min(object.co_firstlineno,len(lines))-1
         while lnum > 0:
             if pmatch(lines[lnum]): break
             lnum -= 1
 
         return lines, lnum
     raise IOError('could not find code object')
 
 # Monkeypatch inspect to apply our bugfix.  This code only works with Python >= 2.5
 inspect.findsource = findsource
 
 def fix_frame_records_filenames(records):
     """Try to fix the filenames in each record from inspect.getinnerframes().
 
     Particularly, modules loaded from within zip files have useless filenames
     attached to their code object, and inspect.getinnerframes() just uses it.
     """
     fixed_records = []
     for frame, filename, line_no, func_name, lines, index in records:
         # Look inside the frame's globals dictionary for __file__, which should
         # be better.
         better_fn = frame.f_globals.get('__file__', None)
         if isinstance(better_fn, str):
             # Check the type just in case someone did something weird with
             # __file__. It might also be None if the error occurred during
             # import.
             filename = better_fn
         fixed_records.append((frame, filename, line_no, func_name, lines, index))
     return fixed_records
 
 
 def _fixed_getinnerframes(etb, context=1,tb_offset=0):
     LNUM_POS, LINES_POS, INDEX_POS =  2, 4, 5
 
     records  = fix_frame_records_filenames(inspect.getinnerframes(etb, context))
 
     # If the error is at the console, don't build any context, since it would
     # otherwise produce 5 blank lines printed out (there is no file at the
     # console)
     rec_check = records[tb_offset:]
     try:
         rname = rec_check[0][1]
         if rname == '<ipython console>' or rname.endswith('<string>'):
             return rec_check
     except IndexError:
         pass
 
     aux = traceback.extract_tb(etb)
     assert len(records) == len(aux)
     for i, (file, lnum, _, _) in zip(range(len(records)), aux):
         maybeStart = lnum-1 - context//2
         start =  max(maybeStart, 0)
         end   = start + context
         lines = ulinecache.getlines(file)[start:end]
         buf = list(records[i])
         buf[LNUM_POS] = lnum
         buf[INDEX_POS] = lnum - 1 - start
         buf[LINES_POS] = lines
         records[i] = tuple(buf)
     return records[tb_offset:]
 
 # Helper function -- largely belongs to VerboseTB, but we need the same
 # functionality to produce a pseudo verbose TB for SyntaxErrors, so that they
 # can be recognized properly by ipython.el's py-traceback-line-re
 # (SyntaxErrors have to be treated specially because they have no traceback)
 
 _parser = PyColorize.Parser()
 
 def _format_traceback_lines(lnum, index, lines, Colors, lvals=None,scheme=None):
     numbers_width = INDENT_SIZE - 1
     res = []
     i = lnum - index
 
     # This lets us get fully syntax-highlighted tracebacks.
     if scheme is None:
         ipinst = ipapi.get()
         if ipinst is not None:
             scheme = ipinst.colors
         else:
             scheme = DEFAULT_SCHEME
 
     _line_format = _parser.format2
 
     for line in lines:
         line = py3compat.cast_unicode(line)
 
         new_line, err = _line_format(line, 'str', scheme)
         if not err: line = new_line
 
         if i == lnum:
             # This is the line with the error
             pad = numbers_width - len(str(i))
             if pad >= 3:
                 marker = '-'*(pad-3) + '-> '
             elif pad == 2:
                 marker = '> '
             elif pad == 1:
                 marker = '>'
             else:
                 marker = ''
             num = marker + str(i)
             line = '%s%s%s %s%s' %(Colors.linenoEm, num,
                                    Colors.line, line, Colors.Normal)
         else:
             num = '%*s' % (numbers_width,i)
             line = '%s%s%s %s' %(Colors.lineno, num,
                                  Colors.Normal, line)
 
         res.append(line)
         if lvals and i == lnum:
             res.append(lvals + '\n')
         i = i + 1
     return res
 
 
 #---------------------------------------------------------------------------
 # Module classes
 class TBTools(object):
     """Basic tools used by all traceback printer classes."""
 
     # Number of frames to skip when reporting tracebacks
     tb_offset = 0
 
     def __init__(self, color_scheme='NoColor', call_pdb=False, ostream=None):
         # Whether to call the interactive pdb debugger after printing
         # tracebacks or not
         self.call_pdb = call_pdb
 
         # Output stream to write to.  Note that we store the original value in
         # a private attribute and then make the public ostream a property, so
         # that we can delay accessing io.stdout until runtime.  The way
         # things are written now, the io.stdout object is dynamically managed
         # so a reference to it should NEVER be stored statically.  This
         # property approach confines this detail to a single location, and all
         # subclasses can simply access self.ostream for writing.
         self._ostream = ostream
 
         # Create color table
         self.color_scheme_table = exception_colors()
 
         self.set_colors(color_scheme)
         self.old_scheme = color_scheme  # save initial value for toggles
 
         if call_pdb:
             self.pdb = debugger.Pdb(self.color_scheme_table.active_scheme_name)
         else:
             self.pdb = None
 
     def _get_ostream(self):
         """Output stream that exceptions are written to.
 
         Valid values are:
 
         - None: the default, which means that IPython will dynamically resolve
         to io.stdout.  This ensures compatibility with most tools, including
         Windows (where plain stdout doesn't recognize ANSI escapes).
 
         - Any object with 'write' and 'flush' attributes.
         """
         return io.stdout if self._ostream is None else self._ostream
 
     def _set_ostream(self, val):
         assert val is None or (hasattr(val, 'write') and hasattr(val, 'flush'))
         self._ostream = val
 
     ostream = property(_get_ostream, _set_ostream)
 
     def set_colors(self,*args,**kw):
         """Shorthand access to the color table scheme selector method."""
 
         # Set own color table
         self.color_scheme_table.set_active_scheme(*args,**kw)
         # for convenience, set Colors to the active scheme
         self.Colors = self.color_scheme_table.active_colors
         # Also set colors of debugger
         if hasattr(self,'pdb') and self.pdb is not None:
             self.pdb.set_colors(*args,**kw)
 
     def color_toggle(self):
         """Toggle between the currently active color scheme and NoColor."""
 
         if self.color_scheme_table.active_scheme_name == 'NoColor':
             self.color_scheme_table.set_active_scheme(self.old_scheme)
             self.Colors = self.color_scheme_table.active_colors
         else:
             self.old_scheme = self.color_scheme_table.active_scheme_name
             self.color_scheme_table.set_active_scheme('NoColor')
             self.Colors = self.color_scheme_table.active_colors
 
     def stb2text(self, stb):
         """Convert a structured traceback (a list) to a string."""
         return '\n'.join(stb)
 
     def text(self, etype, value, tb, tb_offset=None, context=5):
         """Return formatted traceback.
 
         Subclasses may override this if they add extra arguments.
         """
         tb_list = self.structured_traceback(etype, value, tb,
                                             tb_offset, context)
         return self.stb2text(tb_list)
 
     def structured_traceback(self, etype, evalue, tb, tb_offset=None,
                              context=5, mode=None):
         """Return a list of traceback frames.
 
         Must be implemented by each class.
         """
         raise NotImplementedError()
 
 
 #---------------------------------------------------------------------------
 class ListTB(TBTools):
     """Print traceback information from a traceback list, with optional color.
 
     Calling: requires 3 arguments:
       (etype, evalue, elist)
     as would be obtained by:
       etype, evalue, tb = sys.exc_info()
       if tb:
         elist = traceback.extract_tb(tb)
       else:
         elist = None
 
     It can thus be used by programs which need to process the traceback before
     printing (such as console replacements based on the code module from the
     standard library).
 
     Because they are meant to be called without a full traceback (only a
     list), instances of this class can't call the interactive pdb debugger."""
 
     def __init__(self,color_scheme = 'NoColor', call_pdb=False, ostream=None):
         TBTools.__init__(self, color_scheme=color_scheme, call_pdb=call_pdb,
                          ostream=ostream)
 
     def __call__(self, etype, value, elist):
         self.ostream.flush()
         self.ostream.write(self.text(etype, value, elist))
         self.ostream.write('\n')
 
     def structured_traceback(self, etype, value, elist, tb_offset=None,
                              context=5):
         """Return a color formatted string with the traceback info.
 
         Parameters
         ----------
         etype : exception type
           Type of the exception raised.
 
         value : object
           Data stored in the exception
 
         elist : list
           List of frames, see class docstring for details.
 
         tb_offset : int, optional
           Number of frames in the traceback to skip.  If not given, the
           instance value is used (set in constructor).
 
         context : int, optional
           Number of lines of context information to print.
 
         Returns
         -------
         String with formatted exception.
         """
         tb_offset = self.tb_offset if tb_offset is None else tb_offset
         Colors = self.Colors
         out_list = []
         if elist:
 
             if tb_offset and len(elist) > tb_offset:
                 elist = elist[tb_offset:]
 
             out_list.append('Traceback %s(most recent call last)%s:' %
                                 (Colors.normalEm, Colors.Normal) + '\n')
             out_list.extend(self._format_list(elist))
         # The exception info should be a single entry in the list.
         lines = ''.join(self._format_exception_only(etype, value))
         out_list.append(lines)
 
         # Note: this code originally read:
 
         ## for line in lines[:-1]:
         ##     out_list.append(" "+line)
         ## out_list.append(lines[-1])
 
         # This means it was indenting everything but the last line by a little
         # bit.  I've disabled this for now, but if we see ugliness somewhre we
         # can restore it.
 
         return out_list
 
     def _format_list(self, extracted_list):
         """Format a list of traceback entry tuples for printing.
 
         Given a list of tuples as returned by extract_tb() or
         extract_stack(), return a list of strings ready for printing.
         Each string in the resulting list corresponds to the item with the
         same index in the argument list.  Each string ends in a newline;
         the strings may contain internal newlines as well, for those items
         whose source text line is not None.
 
         Lifted almost verbatim from traceback.py
         """
 
         Colors = self.Colors
         list = []
         for filename, lineno, name, line in extracted_list[:-1]:
             item = '  File %s"%s"%s, line %s%d%s, in %s%s%s\n' % \
                     (Colors.filename, filename, Colors.Normal,
                      Colors.lineno, lineno, Colors.Normal,
                      Colors.name, name, Colors.Normal)
             if line:
                 item += '    %s\n' % line.strip()
             list.append(item)
         # Emphasize the last entry
         filename, lineno, name, line = extracted_list[-1]
         item = '%s  File %s"%s"%s, line %s%d%s, in %s%s%s%s\n' % \
                 (Colors.normalEm,
                  Colors.filenameEm, filename, Colors.normalEm,
                  Colors.linenoEm, lineno, Colors.normalEm,
                  Colors.nameEm, name, Colors.normalEm,
                  Colors.Normal)
         if line:
             item += '%s    %s%s\n' % (Colors.line, line.strip(),
                                             Colors.Normal)
         list.append(item)
         #from pprint import pformat; print 'LISTTB', pformat(list) # dbg
         return list
 
     def _format_exception_only(self, etype, value):
         """Format the exception part of a traceback.
 
         The arguments are the exception type and value such as given by
         sys.exc_info()[:2]. The return value is a list of strings, each ending
         in a newline.  Normally, the list contains a single string; however,
         for SyntaxError exceptions, it contains several lines that (when
         printed) display detailed information about where the syntax error
         occurred.  The message indicating which exception occurred is the
         always last string in the list.
 
         Also lifted nearly verbatim from traceback.py
         """
         have_filedata = False
         Colors = self.Colors
         list = []
         stype = Colors.excName + etype.__name__ + Colors.Normal
         if value is None:
             # Not sure if this can still happen in Python 2.6 and above
             list.append( py3compat.cast_unicode(stype) + '\n')
         else:
             if issubclass(etype, SyntaxError):
                 have_filedata = True
                 #print 'filename is',filename  # dbg
                 if not value.filename: value.filename = "<string>"
                 if value.lineno:
                     lineno = value.lineno
                     textline = ulinecache.getline(value.filename, value.lineno)
                 else:
                     lineno = 'unknown'
                     textline = ''
                 list.append('%s  File %s"%s"%s, line %s%s%s\n' % \
                         (Colors.normalEm,
                          Colors.filenameEm, py3compat.cast_unicode(value.filename), Colors.normalEm,
                          Colors.linenoEm, lineno, Colors.Normal  ))
                 if textline == '':
                     textline = py3compat.cast_unicode(value.text, "utf-8")
 
                 if textline is not None:
                     i = 0
                     while i < len(textline) and textline[i].isspace():
                         i += 1
                     list.append('%s    %s%s\n' % (Colors.line,
                                                   textline.strip(),
                                                   Colors.Normal))
                     if value.offset is not None:
                         s = '    '
                         for c in textline[i:value.offset-1]:
                             if c.isspace():
                                 s += c
                             else:
                                 s += ' '
                         list.append('%s%s^%s\n' % (Colors.caret, s,
                                                    Colors.Normal) )
 
             try:
                 s = value.msg
             except Exception:
                 s = self._some_str(value)
             if s:
                 list.append('%s%s:%s %s\n' % (str(stype), Colors.excName,
                                               Colors.Normal, s))
             else:
                 list.append('%s\n' % str(stype))
 
         # sync with user hooks
         if have_filedata:
             ipinst = ipapi.get()
             if ipinst is not None:
                 ipinst.hooks.synchronize_with_editor(value.filename, value.lineno, 0)
 
         return list
 
     def get_exception_only(self, etype, value):
         """Only print the exception type and message, without a traceback.
 
         Parameters
         ----------
         etype : exception type
         value : exception value
         """
         return ListTB.structured_traceback(self, etype, value, [])
 
 
     def show_exception_only(self, etype, evalue):
         """Only print the exception type and message, without a traceback.
 
         Parameters
         ----------
         etype : exception type
         value : exception value
         """
         # This method needs to use __call__ from *this* class, not the one from
         # a subclass whose signature or behavior may be different
         ostream = self.ostream
         ostream.flush()
         ostream.write('\n'.join(self.get_exception_only(etype, evalue)))
         ostream.flush()
 
     def _some_str(self, value):
         # Lifted from traceback.py
         try:
             return str(value)
         except:
             return '<unprintable %s object>' % type(value).__name__
 
 #----------------------------------------------------------------------------
 class VerboseTB(TBTools):
     """A port of Ka-Ping Yee's cgitb.py module that outputs color text instead
     of HTML.  Requires inspect and pydoc.  Crazy, man.
 
     Modified version which optionally strips the topmost entries from the
     traceback, to be used with alternate interpreters (because their own code
     would appear in the traceback)."""
 
     def __init__(self,color_scheme = 'Linux', call_pdb=False, ostream=None,
                  tb_offset=0, long_header=False, include_vars=True,
                  check_cache=None):
         """Specify traceback offset, headers and color scheme.
 
         Define how many frames to drop from the tracebacks. Calling it with
         tb_offset=1 allows use of this handler in interpreters which will have
         their own code at the top of the traceback (VerboseTB will first
         remove that frame before printing the traceback info)."""
         TBTools.__init__(self, color_scheme=color_scheme, call_pdb=call_pdb,
                          ostream=ostream)
         self.tb_offset = tb_offset
         self.long_header = long_header
         self.include_vars = include_vars
         # By default we use linecache.checkcache, but the user can provide a
         # different check_cache implementation.  This is used by the IPython
         # kernel to provide tracebacks for interactive code that is cached,
         # by a compiler instance that flushes the linecache but preserves its
         # own code cache.
         if check_cache is None:
             check_cache = linecache.checkcache
         self.check_cache = check_cache
 
     def structured_traceback(self, etype, evalue, etb, tb_offset=None,
                              context=5):
         """Return a nice text document describing the traceback."""
 
         tb_offset = self.tb_offset if tb_offset is None else tb_offset
 
         # some locals
         try:
             etype = etype.__name__
         except AttributeError:
             pass
         Colors        = self.Colors   # just a shorthand + quicker name lookup
         ColorsNormal  = Colors.Normal  # used a lot
         col_scheme    = self.color_scheme_table.active_scheme_name
         indent        = ' '*INDENT_SIZE
         em_normal     = '%s\n%s%s' % (Colors.valEm, indent,ColorsNormal)
         undefined     = '%sundefined%s' % (Colors.em, ColorsNormal)
         exc = '%s%s%s' % (Colors.excName,etype,ColorsNormal)
 
         # some internal-use functions
         def text_repr(value):
             """Hopefully pretty robust repr equivalent."""
             # this is pretty horrible but should always return *something*
             try:
                 return pydoc.text.repr(value)
             except KeyboardInterrupt:
                 raise
             except:
                 try:
                     return repr(value)
                 except KeyboardInterrupt:
                     raise
                 except:
                     try:
                         # all still in an except block so we catch
                         # getattr raising
                         name = getattr(value, '__name__', None)
                         if name:
                             # ick, recursion
                             return text_repr(name)
                         klass = getattr(value, '__class__', None)
                         if klass:
                             return '%s instance' % text_repr(klass)
                     except KeyboardInterrupt:
                         raise
                     except:
                         return 'UNRECOVERABLE REPR FAILURE'
         def eqrepr(value, repr=text_repr): return '=%s' % repr(value)
         def nullrepr(value, repr=text_repr): return ''
 
         # meat of the code begins
         try:
             etype = etype.__name__
         except AttributeError:
             pass
 
         if self.long_header:
             # Header with the exception type, python version, and date
             pyver = 'Python ' + sys.version.split()[0] + ': ' + sys.executable
             date = time.ctime(time.time())
 
             head = '%s%s%s\n%s%s%s\n%s' % (Colors.topline, '-'*75, ColorsNormal,
                                            exc, ' '*(75-len(str(etype))-len(pyver)),
                                            pyver, date.rjust(75) )
             head += "\nA problem occured executing Python code.  Here is the sequence of function"\
                     "\ncalls leading up to the error, with the most recent (innermost) call last."
         else:
             # Simplified header
             head = '%s%s%s\n%s%s' % (Colors.topline, '-'*75, ColorsNormal,exc,
                                      'Traceback (most recent call last)'.\
                                                   rjust(75 - len(str(etype)) ) )
         frames = []
         # Flush cache before calling inspect.  This helps alleviate some of the
         # problems with python 2.3's inspect.py.
         ##self.check_cache()
         # Drop topmost frames if requested
         try:
             # Try the default getinnerframes and Alex's: Alex's fixes some
             # problems, but it generates empty tracebacks for console errors
             # (5 blanks lines) where none should be returned.
             #records = inspect.getinnerframes(etb, context)[tb_offset:]
             #print 'python records:', records # dbg
             records = _fixed_getinnerframes(etb, context, tb_offset)
             #print 'alex   records:', records # dbg
         except:
 
             # FIXME: I've been getting many crash reports from python 2.3
             # users, traceable to inspect.py.  If I can find a small test-case
             # to reproduce this, I should either write a better workaround or
             # file a bug report against inspect (if that's the real problem).
             # So far, I haven't been able to find an isolated example to
             # reproduce the problem.
             inspect_error()
             traceback.print_exc(file=self.ostream)
             info('\nUnfortunately, your original traceback can not be constructed.\n')
             return ''
 
         # build some color string templates outside these nested loops
         tpl_link       = '%s%%s%s' % (Colors.filenameEm,ColorsNormal)
         tpl_call       = 'in %s%%s%s%%s%s' % (Colors.vName, Colors.valEm,
                                               ColorsNormal)
         tpl_call_fail  = 'in %s%%s%s(***failed resolving arguments***)%s' % \
                          (Colors.vName, Colors.valEm, ColorsNormal)
         tpl_local_var  = '%s%%s%s' % (Colors.vName, ColorsNormal)
         tpl_global_var = '%sglobal%s %s%%s%s' % (Colors.em, ColorsNormal,
                                                  Colors.vName, ColorsNormal)
         tpl_name_val   = '%%s %s= %%s%s' % (Colors.valEm, ColorsNormal)
         tpl_line       = '%s%%s%s %%s' % (Colors.lineno, ColorsNormal)
         tpl_line_em    = '%s%%s%s %%s%s' % (Colors.linenoEm,Colors.line,
                                             ColorsNormal)
 
         # now, loop over all records printing context and info
         abspath = os.path.abspath
         for frame, file, lnum, func, lines, index in records:
             #print '*** record:',file,lnum,func,lines,index  # dbg
             if not file:
                 file = '?'
             elif not(file.startswith(str("<")) and file.endswith(str(">"))):
                 # Guess that filenames like <string> aren't real filenames, so
                 # don't call abspath on them.                    
                 try:
                     file = abspath(file)
                 except OSError:
                     # Not sure if this can still happen: abspath now works with
                     # file names like <string>
                     pass
             file = py3compat.cast_unicode(file, util_path.fs_encoding)
             link = tpl_link % file
             args, varargs, varkw, locals = inspect.getargvalues(frame)
 
             if func == '?':
                 call = ''
             else:
                 # Decide whether to include variable details or not
                 var_repr = self.include_vars and eqrepr or nullrepr
                 try:
                     call = tpl_call % (func,inspect.formatargvalues(args,
                                                 varargs, varkw,
                                                 locals,formatvalue=var_repr))
                 except KeyError:
                     # This happens in situations like errors inside generator
                     # expressions, where local variables are listed in the
                     # line, but can't be extracted from the frame.  I'm not
                     # 100% sure this isn't actually a bug in inspect itself,
                     # but since there's no info for us to compute with, the
                     # best we can do is report the failure and move on.  Here
                     # we must *not* call any traceback construction again,
                     # because that would mess up use of %debug later on.  So we
                     # simply report the failure and move on.  The only
                     # limitation will be that this frame won't have locals
                     # listed in the call signature.  Quite subtle problem...
                     # I can't think of a good way to validate this in a unit
                     # test, but running a script consisting of:
                     #  dict( (k,v.strip()) for (k,v) in range(10) )
                     # will illustrate the error, if this exception catch is
                     # disabled.
                     call = tpl_call_fail % func
             
             # Don't attempt to tokenize binary files.
             if file.endswith(('.so', '.pyd', '.dll')):
                 frames.append('%s %s\n' % (link,call))
                 continue
             elif file.endswith(('.pyc','.pyo')):
                 # Look up the corresponding source file.
                 file = pyfile.source_from_cache(file)
 
             def linereader(file=file, lnum=[lnum], getline=ulinecache.getline):
                 line = getline(file, lnum[0])
                 lnum[0] += 1
                 return line
 
             # Build the list of names on this line of code where the exception
             # occurred.
             try:
                 names = []
                 name_cont = False
                 
                 for token_type, token, start, end, line in generate_tokens(linereader):
                     # build composite names
                     if token_type == tokenize.NAME and token not in keyword.kwlist:
                         if name_cont:
                             # Continuation of a dotted name
                             try:
                                 names[-1].append(token)
                             except IndexError:
                                 names.append([token])
                             name_cont = False
                         else:
                             # Regular new names.  We append everything, the caller
                             # will be responsible for pruning the list later.  It's
                             # very tricky to try to prune as we go, b/c composite
                             # names can fool us.  The pruning at the end is easy
                             # to do (or the caller can print a list with repeated
                             # names if so desired.
                             names.append([token])
                     elif token == '.':
                         name_cont = True
                     elif token_type == tokenize.NEWLINE:
                         break
                         
             except (IndexError, UnicodeDecodeError):
                 # signals exit of tokenizer
                 pass
             except tokenize.TokenError as msg:
                 _m = ("An unexpected error occurred while tokenizing input\n"
                       "The following traceback may be corrupted or invalid\n"
                       "The error message is: %s\n" % msg)
                 error(_m)
 
             # Join composite names (e.g. "dict.fromkeys")
             names = ['.'.join(n) for n in names]
             # prune names list of duplicates, but keep the right order
             unique_names = uniq_stable(names)
 
             # Start loop over vars
             lvals = []
             if self.include_vars:
                 for name_full in unique_names:
                     name_base = name_full.split('.',1)[0]
                     if name_base in frame.f_code.co_varnames:
                         if name_base in locals:
                             try:
                                 value = repr(eval(name_full,locals))
                             except:
                                 value = undefined
                         else:
                             value = undefined
                         name = tpl_local_var % name_full
                     else:
                         if name_base in frame.f_globals:
                             try:
                                 value = repr(eval(name_full,frame.f_globals))
                             except:
                                 value = undefined
                         else:
                             value = undefined
                         name = tpl_global_var % name_full
                     lvals.append(tpl_name_val % (name,value))
             if lvals:
                 lvals = '%s%s' % (indent,em_normal.join(lvals))
             else:
                 lvals = ''
 
             level = '%s %s\n' % (link,call)
 
             if index is None:
                 frames.append(level)
             else:
                 frames.append('%s%s' % (level,''.join(
                     _format_traceback_lines(lnum,index,lines,Colors,lvals,
                                             col_scheme))))
 
         # Get (safely) a string form of the exception info
         try:
             etype_str,evalue_str = map(str,(etype,evalue))
         except:
             # User exception is improperly defined.
             etype,evalue = str,sys.exc_info()[:2]
             etype_str,evalue_str = map(str,(etype,evalue))
         # ... and format it
         exception = ['%s%s%s: %s' % (Colors.excName, etype_str,
                                      ColorsNormal, py3compat.cast_unicode(evalue_str))]
         if (not py3compat.PY3) and type(evalue) is types.InstanceType:
             try:
                 names = [w for w in dir(evalue) if isinstance(w, basestring)]
             except:
                 # Every now and then, an object with funny inernals blows up
                 # when dir() is called on it.  We do the best we can to report
                 # the problem and continue
                 _m = '%sException reporting error (object with broken dir())%s:'
                 exception.append(_m % (Colors.excName,ColorsNormal))
                 etype_str,evalue_str = map(str,sys.exc_info()[:2])
                 exception.append('%s%s%s: %s' % (Colors.excName,etype_str,
                                      ColorsNormal, py3compat.cast_unicode(evalue_str)))
                 names = []
             for name in names:
                 value = text_repr(getattr(evalue, name))
                 exception.append('\n%s%s = %s' % (indent, name, value))
 
         # vds: >>
         if records:
              filepath, lnum = records[-1][1:3]
              #print "file:", str(file), "linenb", str(lnum) # dbg
              filepath = os.path.abspath(filepath)
              ipinst = ipapi.get()
              if ipinst is not None:
                  ipinst.hooks.synchronize_with_editor(filepath, lnum, 0)
         # vds: <<
 
         # return all our info assembled as a single string
         # return '%s\n\n%s\n%s' % (head,'\n'.join(frames),''.join(exception[0]) )
         return [head] + frames + [''.join(exception[0])]
 
     def debugger(self,force=False):
         """Call up the pdb debugger if desired, always clean up the tb
         reference.
 
         Keywords:
 
           - force(False): by default, this routine checks the instance call_pdb
           flag and does not actually invoke the debugger if the flag is false.
           The 'force' option forces the debugger to activate even if the flag
           is false.
 
         If the call_pdb flag is set, the pdb interactive debugger is
         invoked. In all cases, the self.tb reference to the current traceback
         is deleted to prevent lingering references which hamper memory
         management.
 
         Note that each call to pdb() does an 'import readline', so if your app
         requires a special setup for the readline completers, you'll have to
         fix that by hand after invoking the exception handler."""
 
         if force or self.call_pdb:
             if self.pdb is None:
                 self.pdb = debugger.Pdb(
                     self.color_scheme_table.active_scheme_name)
             # the system displayhook may have changed, restore the original
             # for pdb
             display_trap = DisplayTrap(hook=sys.__displayhook__)
             with display_trap:
                 self.pdb.reset()
                 # Find the right frame so we don't pop up inside ipython itself
                 if hasattr(self,'tb') and self.tb is not None:
                     etb = self.tb
                 else:
                     etb = self.tb = sys.last_traceback
                 while self.tb is not None and self.tb.tb_next is not None:
                     self.tb = self.tb.tb_next
                 if etb and etb.tb_next:
                     etb = etb.tb_next
                 self.pdb.botframe = etb.tb_frame
                 self.pdb.interaction(self.tb.tb_frame, self.tb)
 
         if hasattr(self,'tb'):
             del self.tb
 
     def handler(self, info=None):
         (etype, evalue, etb) = info or sys.exc_info()
         self.tb = etb
         ostream = self.ostream
         ostream.flush()
         ostream.write(self.text(etype, evalue, etb))
         ostream.write('\n')
         ostream.flush()
 
     # Changed so an instance can just be called as VerboseTB_inst() and print
     # out the right info on its own.
     def __call__(self, etype=None, evalue=None, etb=None):
         """This hook can replace sys.excepthook (for Python 2.1 or higher)."""
         if etb is None:
             self.handler()
         else:
             self.handler((etype, evalue, etb))
         try:
             self.debugger()
         except KeyboardInterrupt:
             print "\nKeyboardInterrupt"
 
 #----------------------------------------------------------------------------
 class FormattedTB(VerboseTB, ListTB):
     """Subclass ListTB but allow calling with a traceback.
 
     It can thus be used as a sys.excepthook for Python > 2.1.
 
     Also adds 'Context' and 'Verbose' modes, not available in ListTB.
 
     Allows a tb_offset to be specified. This is useful for situations where
     one needs to remove a number of topmost frames from the traceback (such as
     occurs with python programs that themselves execute other python code,
     like Python shells).  """
 
     def __init__(self, mode='Plain', color_scheme='Linux', call_pdb=False,
                  ostream=None,
                  tb_offset=0, long_header=False, include_vars=False,
                  check_cache=None):
 
         # NEVER change the order of this list. Put new modes at the end:
         self.valid_modes = ['Plain','Context','Verbose']
         self.verbose_modes = self.valid_modes[1:3]
 
         VerboseTB.__init__(self, color_scheme=color_scheme, call_pdb=call_pdb,
                            ostream=ostream, tb_offset=tb_offset,
                            long_header=long_header, include_vars=include_vars,
                            check_cache=check_cache)
 
         # Different types of tracebacks are joined with different separators to
         # form a single string.  They are taken from this dict
         self._join_chars = dict(Plain='', Context='\n', Verbose='\n')
         # set_mode also sets the tb_join_char attribute
         self.set_mode(mode)
 
     def _extract_tb(self,tb):
         if tb:
             return traceback.extract_tb(tb)
         else:
             return None
 
     def structured_traceback(self, etype, value, tb, tb_offset=None, context=5):
         tb_offset = self.tb_offset if tb_offset is None else tb_offset
         mode = self.mode
         if mode in self.verbose_modes:
             # Verbose modes need a full traceback
             return VerboseTB.structured_traceback(
                 self, etype, value, tb, tb_offset, context
             )
         else:
             # We must check the source cache because otherwise we can print
             # out-of-date source code.
             self.check_cache()
             # Now we can extract and format the exception
             elist = self._extract_tb(tb)
             return ListTB.structured_traceback(
                 self, etype, value, elist, tb_offset, context
             )
 
     def stb2text(self, stb):
         """Convert a structured traceback (a list) to a string."""
         return self.tb_join_char.join(stb)
 
 
     def set_mode(self,mode=None):
         """Switch to the desired mode.
 
         If mode is not specified, cycles through the available modes."""
 
         if not mode:
             new_idx = ( self.valid_modes.index(self.mode) + 1 ) % \
                       len(self.valid_modes)
             self.mode = self.valid_modes[new_idx]
         elif mode not in self.valid_modes:
             raise ValueError('Unrecognized mode in FormattedTB: <'+mode+'>\n'
                              'Valid modes: '+str(self.valid_modes))
         else:
             self.mode = mode
         # include variable details only in 'Verbose' mode
         self.include_vars = (self.mode == self.valid_modes[2])
         # Set the join character for generating text tracebacks
         self.tb_join_char = self._join_chars[self.mode]
 
     # some convenient shorcuts
     def plain(self):
         self.set_mode(self.valid_modes[0])
 
     def context(self):
         self.set_mode(self.valid_modes[1])
 
     def verbose(self):
         self.set_mode(self.valid_modes[2])
 
 #----------------------------------------------------------------------------
 class AutoFormattedTB(FormattedTB):
     """A traceback printer which can be called on the fly.
 
     It will find out about exceptions by itself.
 
     A brief example:
 
     AutoTB = AutoFormattedTB(mode = 'Verbose',color_scheme='Linux')
     try:
       ...
     except:
       AutoTB()  # or AutoTB(out=logfile) where logfile is an open file object
     """
 
     def __call__(self,etype=None,evalue=None,etb=None,
                  out=None,tb_offset=None):
         """Print out a formatted exception traceback.
 
         Optional arguments:
           - out: an open file-like object to direct output to.
 
           - tb_offset: the number of frames to skip over in the stack, on a
           per-call basis (this overrides temporarily the instance's tb_offset
           given at initialization time.  """
 
 
         if out is None:
             out = self.ostream
         out.flush()
         out.write(self.text(etype, evalue, etb, tb_offset))
         out.write('\n')
         out.flush()
         # FIXME: we should remove the auto pdb behavior from here and leave
         # that to the clients.
         try:
             self.debugger()
         except KeyboardInterrupt:
             print "\nKeyboardInterrupt"
 
     def structured_traceback(self, etype=None, value=None, tb=None,
                              tb_offset=None, context=5):
         if etype is None:
             etype,value,tb = sys.exc_info()
         self.tb = tb
         return FormattedTB.structured_traceback(
             self, etype, value, tb, tb_offset, context)
 
 #---------------------------------------------------------------------------
 
 # A simple class to preserve Nathan's original functionality.
 class ColorTB(FormattedTB):
     """Shorthand to initialize a FormattedTB in Linux colors mode."""
     def __init__(self,color_scheme='Linux',call_pdb=0):
         FormattedTB.__init__(self,color_scheme=color_scheme,
                              call_pdb=call_pdb)
 
 
 class SyntaxTB(ListTB):
     """Extension which holds some state: the last exception value"""
 
     def __init__(self,color_scheme = 'NoColor'):
         ListTB.__init__(self,color_scheme)
         self.last_syntax_error = None
 
     def __call__(self, etype, value, elist):
         self.last_syntax_error = value
         ListTB.__call__(self,etype,value,elist)
 
     def clear_err_state(self):
         """Return the current error state and clear it"""
         e = self.last_syntax_error
         self.last_syntax_error = None
         return e
 
     def stb2text(self, stb):
         """Convert a structured traceback (a list) to a string."""
         return ''.join(stb)
 
 
 #----------------------------------------------------------------------------
 # module testing (minimal)
 if __name__ == "__main__":
     def spam(c, d_e):
         (d, e) = d_e
         x = c + d
         y = c * d
         foo(x, y)
 
     def foo(a, b, bar=1):
         eggs(a, b + bar)
 
     def eggs(f, g, z=globals()):
         h = f + g
         i = f - g
         return h / i
 
     print ''
     print '*** Before ***'
     try:
         print spam(1, (2, 3))
     except:
         traceback.print_exc()
     print ''
 
     handler = ColorTB()
     print '*** ColorTB ***'
     try:
         print spam(1, (2, 3))
     except:
         handler(*sys.exc_info())
     print ''
 
     handler = VerboseTB()
     print '*** VerboseTB ***'
     try:
         print spam(1, (2, 3))
     except:
         handler(*sys.exc_info())
     print ''
 

IPython/lib/demo.py

@@ -1,578 +1,583 b''
-from __future__ import unicode_literals
-
-
 """Module for interactive demos using IPython.
 
 This module implements a few classes for running Python scripts interactively
 in IPython for demonstrations.  With very simple markup (a few tags in
 comments), you can control points where the script stops executing and returns
 control to IPython.
 
 
 Provided classes
-================
+----------------
 
 The classes are (see their docstrings for further details):
 
  - Demo: pure python demos
 
  - IPythonDemo: demos with input to be processed by IPython as if it had been
  typed interactively (so magics work, as well as any other special syntax you
  may have added via input prefilters).
 
  - LineDemo: single-line version of the Demo class.  These demos are executed
  one line at a time, and require no markup.
 
  - IPythonLineDemo: IPython version of the LineDemo class (the demo is
  executed a line at a time, but processed via IPython).
 
  - ClearMixin: mixin to make Demo classes with less visual clutter.  It
    declares an empty marquee and a pre_cmd that clears the screen before each
    block (see Subclassing below).
 
  - ClearDemo, ClearIPDemo: mixin-enabled versions of the Demo and IPythonDemo
    classes.
 
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.lib.demo
+   :parts: 3
 
 Subclassing
-===========
+-----------
 
 The classes here all include a few methods meant to make customization by
 subclassing more convenient.  Their docstrings below have some more details:
 
   - marquee(): generates a marquee to provide visible on-screen markers at each
     block start and end.
 
   - pre_cmd(): run right before the execution of each block.
 
   - post_cmd(): run right after the execution of each block.  If the block
     raises an exception, this is NOT called.
 
 
 Operation
-=========
+---------
 
 The file is run in its own empty namespace (though you can pass it a string of
 arguments as if in a command line environment, and it will see those as
 sys.argv).  But at each stop, the global IPython namespace is updated with the
 current internal demo namespace, so you can work interactively with the data
 accumulated so far.
 
 By default, each block of code is printed (with syntax highlighting) before
 executing it and you have to confirm execution.  This is intended to show the
 code to an audience first so you can discuss it, and only proceed with
 execution once you agree.  There are a few tags which allow you to modify this
 behavior.
 
 The supported tags are:
 
 # <demo> stop
 
   Defines block boundaries, the points where IPython stops execution of the
   file and returns to the interactive prompt.
 
   You can optionally mark the stop tag with extra dashes before and after the
   word 'stop', to help visually distinguish the blocks in a text editor:
 
   # <demo> --- stop ---
 
 
 # <demo> silent
 
   Make a block execute silently (and hence automatically).  Typically used in
   cases where you have some boilerplate or initialization code which you need
   executed but do not want to be seen in the demo.
 
 # <demo> auto
 
   Make a block execute automatically, but still being printed.  Useful for
   simple code which does not warrant discussion, since it avoids the extra
   manual confirmation.
 
 # <demo> auto_all
 
   This tag can _only_ be in the first block, and if given it overrides the
   individual auto tags to make the whole demo fully automatic (no block asks
   for confirmation).  It can also be given at creation time (or the attribute
   set later) to override what's in the file.
 
 While _any_ python file can be run as a Demo instance, if there are no stop
 tags the whole file will run in a single block (no different that calling
 first %pycat and then %run).  The minimal markup to make this useful is to
 place a set of stop tags; the other tags are only there to let you fine-tune
 the execution.
 
 This is probably best explained with the simple example file below.  You can
 copy this into a file named ex_demo.py, and try running it via:
 
 from IPython.demo import Demo
 d = Demo('ex_demo.py')
 d()  <--- Call the d object (omit the parens if you have autocall set to 2).
 
 Each time you call the demo object, it runs the next block.  The demo object
 has a few useful methods for navigation, like again(), edit(), jump(), seek()
 and back().  It can be reset for a new run via reset() or reloaded from disk
 (in case you've edited the source) via reload().  See their docstrings below.
 
 Note: To make this simpler to explore, a file called "demo-exercizer.py" has
 been added to the "docs/examples/core" directory.  Just cd to this directory in
 an IPython session, and type::
 
   %run demo-exercizer.py
 
 and then follow the directions.
 
 Example
-=======
+-------
 
 The following is a very simple example of a valid demo file.
 
+::
+
 #################### EXAMPLE DEMO <ex_demo.py> ###############################
 '''A simple interactive demo to illustrate the use of IPython's Demo class.'''
 
 print 'Hello, welcome to an interactive IPython demo.'
 
 # The mark below defines a block boundary, which is a point where IPython will
 # stop execution and return to the interactive prompt. The dashes are actually
 # optional and used only as a visual aid to clearly separate blocks while
 # editing the demo code.
 # <demo> stop
 
 x = 1
 y = 2
 
 # <demo> stop
 
 # the mark below makes this block as silent
 # <demo> silent
 
 print 'This is a silent block, which gets executed but not printed.'
 
 # <demo> stop
 # <demo> auto
 print 'This is an automatic block.'
 print 'It is executed without asking for confirmation, but printed.'
 z = x+y
 
 print 'z=',x
 
 # <demo> stop
 # This is just another normal block.
 print 'z is now:', z
 
 print 'bye!'
 ################### END EXAMPLE DEMO <ex_demo.py> ############################
 """
 
+from __future__ import unicode_literals
+
 #*****************************************************************************
 #     Copyright (C) 2005-2006 Fernando Perez. <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #
 #*****************************************************************************
 from __future__ import print_function
 
 import os
 import re
 import shlex
 import sys
 
 from IPython.utils.PyColorize import Parser
 from IPython.utils import io
 from IPython.utils.io import file_read, file_readlines
 from IPython.utils.text import marquee
 from IPython.utils import openpy
 __all__ = ['Demo','IPythonDemo','LineDemo','IPythonLineDemo','DemoError']
 
 class DemoError(Exception): pass
 
 def re_mark(mark):
     return re.compile(r'^\s*#\s+<demo>\s+%s\s*$' % mark,re.MULTILINE)
 
 class Demo(object):
 
     re_stop     = re_mark('-*\s?stop\s?-*')
     re_silent   = re_mark('silent')
     re_auto     = re_mark('auto')
     re_auto_all = re_mark('auto_all')
 
     def __init__(self,src,title='',arg_str='',auto_all=None):
         """Make a new demo object.  To run the demo, simply call the object.
 
         See the module docstring for full details and an example (you can use
         IPython.Demo? in IPython to see it).
 
         Inputs:
 
           - src is either a file, or file-like object, or a
               string that can be resolved to a filename.
 
         Optional inputs:
 
           - title: a string to use as the demo name.  Of most use when the demo
           you are making comes from an object that has no filename, or if you
           want an alternate denotation distinct from the filename.
 
           - arg_str(''): a string of arguments, internally converted to a list
           just like sys.argv, so the demo script can see a similar
           environment.
 
           - auto_all(None): global flag to run all blocks automatically without
           confirmation.  This attribute overrides the block-level tags and
           applies to the whole demo.  It is an attribute of the object, and
           can be changed at runtime simply by reassigning it to a boolean
           value.
           """
         if hasattr(src, "read"):
              # It seems to be a file or a file-like object
             self.fname = "from a file-like object"
             if title == '':
                 self.title = "from a file-like object"
             else:
                 self.title = title
         else:
              # Assume it's a string or something that can be converted to one
             self.fname = src
             if title == '':
                 (filepath, filename) = os.path.split(src)
                 self.title = filename
             else:
                 self.title = title
         self.sys_argv = [src] + shlex.split(arg_str)
         self.auto_all = auto_all
         self.src = src
 
         # get a few things from ipython.  While it's a bit ugly design-wise,
         # it ensures that things like color scheme and the like are always in
         # sync with the ipython mode being used.  This class is only meant to
         # be used inside ipython anyways,  so it's OK.
         ip = get_ipython()  # this is in builtins whenever IPython is running
         self.ip_ns       = ip.user_ns
         self.ip_colorize = ip.pycolorize
         self.ip_showtb   = ip.showtraceback
         self.ip_run_cell = ip.run_cell
         self.shell       = ip
 
         # load user data and initialize data structures
         self.reload()
 
     def fload(self):
         """Load file object."""
         # read data and parse into blocks
         if hasattr(self, 'fobj') and self.fobj is not None:
            self.fobj.close()
         if hasattr(self.src, "read"):
              # It seems to be a file or a file-like object
             self.fobj = self.src
         else:
              # Assume it's a string or something that can be converted to one
             self.fobj = openpy.open(self.fname)
 
     def reload(self):
         """Reload source from disk and initialize state."""
         self.fload()
 
         self.src     = "".join(openpy.strip_encoding_cookie(self.fobj))
         src_b        = [b.strip() for b in self.re_stop.split(self.src) if b]
         self._silent = [bool(self.re_silent.findall(b)) for b in src_b]
         self._auto   = [bool(self.re_auto.findall(b)) for b in src_b]
 
         # if auto_all is not given (def. None), we read it from the file
         if self.auto_all is None:
             self.auto_all = bool(self.re_auto_all.findall(src_b[0]))
         else:
             self.auto_all = bool(self.auto_all)
 
         # Clean the sources from all markup so it doesn't get displayed when
         # running the demo
         src_blocks = []
         auto_strip = lambda s: self.re_auto.sub('',s)
         for i,b in enumerate(src_b):
             if self._auto[i]:
                 src_blocks.append(auto_strip(b))
             else:
                 src_blocks.append(b)
         # remove the auto_all marker
         src_blocks[0] = self.re_auto_all.sub('',src_blocks[0])
 
         self.nblocks = len(src_blocks)
         self.src_blocks = src_blocks
 
         # also build syntax-highlighted source
         self.src_blocks_colored = map(self.ip_colorize,self.src_blocks)
 
         # ensure clean namespace and seek offset
         self.reset()
 
     def reset(self):
         """Reset the namespace and seek pointer to restart the demo"""
         self.user_ns     = {}
         self.finished    = False
         self.block_index = 0
 
     def _validate_index(self,index):
         if index<0 or index>=self.nblocks:
             raise ValueError('invalid block index %s' % index)
 
     def _get_index(self,index):
         """Get the current block index, validating and checking status.
 
         Returns None if the demo is finished"""
 
         if index is None:
             if self.finished:
                 print('Demo finished.  Use <demo_name>.reset() if you want to rerun it.', file=io.stdout)
                 return None
             index = self.block_index
         else:
             self._validate_index(index)
         return index
 
     def seek(self,index):
         """Move the current seek pointer to the given block.
 
         You can use negative indices to seek from the end, with identical
         semantics to those of Python lists."""
         if index<0:
             index = self.nblocks + index
         self._validate_index(index)
         self.block_index = index
         self.finished = False
 
     def back(self,num=1):
         """Move the seek pointer back num blocks (default is 1)."""
         self.seek(self.block_index-num)
 
     def jump(self,num=1):
         """Jump a given number of blocks relative to the current one.
 
         The offset can be positive or negative, defaults to 1."""
         self.seek(self.block_index+num)
 
     def again(self):
         """Move the seek pointer back one block and re-execute."""
         self.back(1)
         self()
 
     def edit(self,index=None):
         """Edit a block.
 
         If no number is given, use the last block executed.
 
         This edits the in-memory copy of the demo, it does NOT modify the
         original source file.  If you want to do that, simply open the file in
         an editor and use reload() when you make changes to the file.  This
         method is meant to let you change a block during a demonstration for
         explanatory purposes, without damaging your original script."""
 
         index = self._get_index(index)
         if index is None:
             return
         # decrease the index by one (unless we're at the very beginning), so
         # that the default demo.edit() call opens up the sblock we've last run
         if index>0:
             index -= 1
 
         filename = self.shell.mktempfile(self.src_blocks[index])
         self.shell.hooks.editor(filename,1)
         new_block = file_read(filename)
         # update the source and colored block
         self.src_blocks[index] = new_block
         self.src_blocks_colored[index] = self.ip_colorize(new_block)
         self.block_index = index
         # call to run with the newly edited index
         self()
 
     def show(self,index=None):
         """Show a single block on screen"""
 
         index = self._get_index(index)
         if index is None:
             return
 
         print(self.marquee('<%s> block # %s (%s remaining)' %
                            (self.title,index,self.nblocks-index-1)), file=io.stdout)
         print((self.src_blocks_colored[index]), file=io.stdout)
         sys.stdout.flush()
 
     def show_all(self):
         """Show entire demo on screen, block by block"""
 
         fname = self.title
         title = self.title
         nblocks = self.nblocks
         silent = self._silent
         marquee = self.marquee
         for index,block in enumerate(self.src_blocks_colored):
             if silent[index]:
                 print(marquee('<%s> SILENT block # %s (%s remaining)' %
                               (title,index,nblocks-index-1)), file=io.stdout)
             else:
                 print(marquee('<%s> block # %s (%s remaining)' %
                               (title,index,nblocks-index-1)), file=io.stdout)
             print(block, end=' ', file=io.stdout)
         sys.stdout.flush()
 
     def run_cell(self,source):
         """Execute a string with one or more lines of code"""
 
         exec source in self.user_ns
 
     def __call__(self,index=None):
         """run a block of the demo.
 
         If index is given, it should be an integer >=1 and <= nblocks.  This
         means that the calling convention is one off from typical Python
         lists.  The reason for the inconsistency is that the demo always
         prints 'Block n/N, and N is the total, so it would be very odd to use
         zero-indexing here."""
 
         index = self._get_index(index)
         if index is None:
             return
         try:
             marquee = self.marquee
             next_block = self.src_blocks[index]
             self.block_index += 1
             if self._silent[index]:
                 print(marquee('Executing silent block # %s (%s remaining)' %
                               (index,self.nblocks-index-1)), file=io.stdout)
             else:
                 self.pre_cmd()
                 self.show(index)
                 if self.auto_all or self._auto[index]:
                     print(marquee('output:'), file=io.stdout)
                 else:
                     print(marquee('Press <q> to quit, <Enter> to execute...'), end=' ', file=io.stdout)
                     ans = raw_input().strip()
                     if ans:
                         print(marquee('Block NOT executed'), file=io.stdout)
                         return
             try:
                 save_argv = sys.argv
                 sys.argv = self.sys_argv
                 self.run_cell(next_block)
                 self.post_cmd()
             finally:
                 sys.argv = save_argv
 
         except:
             self.ip_showtb(filename=self.fname)
         else:
             self.ip_ns.update(self.user_ns)
 
         if self.block_index == self.nblocks:
             mq1 = self.marquee('END OF DEMO')
             if mq1:
                 # avoid spurious print >>io.stdout,s if empty marquees are used
                 print(file=io.stdout)
                 print(mq1, file=io.stdout)
                 print(self.marquee('Use <demo_name>.reset() if you want to rerun it.'), file=io.stdout)
             self.finished = True
 
     # These methods are meant to be overridden by subclasses who may wish to
     # customize the behavior of of their demos.
     def marquee(self,txt='',width=78,mark='*'):
         """Return the input string centered in a 'marquee'."""
         return marquee(txt,width,mark)
 
     def pre_cmd(self):
         """Method called before executing each block."""
         pass
 
     def post_cmd(self):
         """Method called after executing each block."""
         pass
 
 
 class IPythonDemo(Demo):
     """Class for interactive demos with IPython's input processing applied.
 
     This subclasses Demo, but instead of executing each block by the Python
     interpreter (via exec), it actually calls IPython on it, so that any input
     filters which may be in place are applied to the input block.
 
     If you have an interactive environment which exposes special input
     processing, you can use this class instead to write demo scripts which
     operate exactly as if you had typed them interactively.  The default Demo
     class requires the input to be valid, pure Python code.
     """
 
     def run_cell(self,source):
         """Execute a string with one or more lines of code"""
 
         self.shell.run_cell(source)
 
 class LineDemo(Demo):
     """Demo where each line is executed as a separate block.
 
     The input script should be valid Python code.
 
     This class doesn't require any markup at all, and it's meant for simple
     scripts (with no nesting or any kind of indentation) which consist of
     multiple lines of input to be executed, one at a time, as if they had been
     typed in the interactive prompt.
 
     Note: the input can not have *any* indentation, which means that only
     single-lines of input are accepted, not even function definitions are
     valid."""
 
     def reload(self):
         """Reload source from disk and initialize state."""
         # read data and parse into blocks
         self.fload()
         lines           = self.fobj.readlines()
         src_b           = [l for l in lines if l.strip()]
         nblocks         = len(src_b)
         self.src        = ''.join(lines)
         self._silent    = [False]*nblocks
         self._auto      = [True]*nblocks
         self.auto_all   = True
         self.nblocks    = nblocks
         self.src_blocks = src_b
 
         # also build syntax-highlighted source
         self.src_blocks_colored = map(self.ip_colorize,self.src_blocks)
 
         # ensure clean namespace and seek offset
         self.reset()
 
 
 class IPythonLineDemo(IPythonDemo,LineDemo):
     """Variant of the LineDemo class whose input is processed by IPython."""
     pass
 
 
 class ClearMixin(object):
     """Use this mixin to make Demo classes with less visual clutter.
 
     Demos using this mixin will clear the screen before every block and use
     blank marquees.
 
     Note that in order for the methods defined here to actually override those
     of the classes it's mixed with, it must go /first/ in the inheritance
     tree.  For example:
 
         class ClearIPDemo(ClearMixin,IPythonDemo): pass
 
     will provide an IPythonDemo class with the mixin's features.
     """
 
     def marquee(self,txt='',width=78,mark='*'):
         """Blank marquee that returns '' no matter what the input."""
         return ''
 
     def pre_cmd(self):
         """Method called before executing each block.
 
         This one simply clears the screen."""
         from IPython.utils.terminal import term_clear
         term_clear()
 
 class ClearDemo(ClearMixin,Demo):
     pass
 
 
 class ClearIPDemo(ClearMixin,IPythonDemo):
     pass

IPython/lib/irunner.py

@@ -1,443 +1,441 b''
 #!/usr/bin/env python
 """Module for interactively running scripts.
 
 This module implements classes for interactively running scripts written for
 any system with a prompt which can be matched by a regexp suitable for
 pexpect.  It can be used to run as if they had been typed up interactively, an
 arbitrary series of commands for the target system.
 
 The module includes classes ready for IPython (with the default prompts),
 plain Python and SAGE, but making a new one is trivial.  To see how to use it,
 simply run the module as a script:
 
 ./irunner.py --help
 
 
 This is an extension of Ken Schutte <kschutte-AT-csail.mit.edu>'s script
 contributed on the ipython-user list:
 
 http://mail.scipy.org/pipermail/ipython-user/2006-May/003539.html
 
-
-NOTES:
+Notes
+-----
 
  - This module requires pexpect, available in most linux distros, or which can
- be downloaded from
-
-    http://pexpect.sourceforge.net
+   be downloaded from http://pexpect.sourceforge.net
 
  - Because pexpect only works under Unix or Windows-Cygwin, this has the same
  limitations.  This means that it will NOT work under native windows Python.
 """
 from __future__ import print_function
 
 # Stdlib imports
 import optparse
 import os
 import sys
 
 # Third-party modules: we carry a copy of pexpect to reduce the need for
 # external dependencies, but our import checks for a system version first.
 from IPython.external import pexpect
 from IPython.utils import py3compat
 
 # Global usage strings, to avoid indentation issues when typing it below.
 USAGE = """
 Interactive script runner, type: %s
 
 runner [opts] script_name
 """
 
 def pexpect_monkeypatch():
     """Patch pexpect to prevent unhandled exceptions at VM teardown.
 
     Calling this function will monkeypatch the pexpect.spawn class and modify
     its __del__ method to make it more robust in the face of failures that can
     occur if it is called when the Python VM is shutting down.
 
     Since Python may fire __del__ methods arbitrarily late, it's possible for
     them to execute during the teardown of the Python VM itself.  At this
     point, various builtin modules have been reset to None.  Thus, the call to
     self.close() will trigger an exception because it tries to call os.close(),
     and os is now None.
     """
 
     if pexpect.__version__[:3] >= '2.2':
         # No need to patch, fix is already the upstream version.
         return
 
     def __del__(self):
         """This makes sure that no system resources are left open.
         Python only garbage collects Python objects. OS file descriptors
         are not Python objects, so they must be handled explicitly.
         If the child file descriptor was opened outside of this class
         (passed to the constructor) then this does not close it.
         """
         if not self.closed:
             try:
                 self.close()
             except AttributeError:
                 pass
 
     pexpect.spawn.__del__ = __del__
 
 pexpect_monkeypatch()
 
 # The generic runner class
 class InteractiveRunner(object):
     """Class to run a sequence of commands through an interactive program."""
 
     def __init__(self,program,prompts,args=None,out=sys.stdout,echo=True):
         """Construct a runner.
 
         Inputs:
 
           - program: command to execute the given program.
 
           - prompts: a list of patterns to match as valid prompts, in the
           format used by pexpect.  This basically means that it can be either
           a string (to be compiled as a regular expression) or a list of such
           (it must be a true list, as pexpect does type checks).
 
           If more than one prompt is given, the first is treated as the main
           program prompt and the others as 'continuation' prompts, like
           python's.  This means that blank lines in the input source are
           ommitted when the first prompt is matched, but are NOT ommitted when
           the continuation one matches, since this is how python signals the
           end of multiline input interactively.
 
         Optional inputs:
 
           - args(None): optional list of strings to pass as arguments to the
           child program.
 
           - out(sys.stdout): if given, an output stream to be used when writing
           output.  The only requirement is that it must have a .write() method.
 
         Public members not parameterized in the constructor:
 
           - delaybeforesend(0): Newer versions of pexpect have a delay before
           sending each new input.  For our purposes here, it's typically best
           to just set this to zero, but if you encounter reliability problems
           or want an interactive run to pause briefly at each prompt, just
           increase this value (it is measured in seconds).  Note that this
           variable is not honored at all by older versions of pexpect.
         """
 
         self.program = program
         self.prompts = prompts
         if args is None: args = []
         self.args = args
         self.out = out
         self.echo = echo
         # Other public members which we don't make as parameters, but which
         # users may occasionally want to tweak
         self.delaybeforesend = 0
 
         # Create child process and hold on to it so we don't have to re-create
         # for every single execution call
         c = self.child = pexpect.spawn(self.program,self.args,timeout=None)
         c.delaybeforesend = self.delaybeforesend
         # pexpect hard-codes the terminal size as (24,80) (rows,columns).
         # This causes problems because any line longer than 80 characters gets
         # completely overwrapped on the printed outptut (even though
         # internally the code runs fine).  We reset this to 99 rows X 200
         # columns (arbitrarily chosen), which should avoid problems in all
         # reasonable cases.
         c.setwinsize(99,200)
 
     def close(self):
         """close child process"""
 
         self.child.close()
 
     def run_file(self,fname,interact=False,get_output=False):
         """Run the given file interactively.
 
         Inputs:
 
           -fname: name of the file to execute.
 
         See the run_source docstring for the meaning of the optional
         arguments."""
 
         fobj = open(fname,'r')
         try:
             out = self.run_source(fobj,interact,get_output)
         finally:
             fobj.close()
         if get_output:
             return out
 
     def run_source(self,source,interact=False,get_output=False):
         """Run the given source code interactively.
 
         Inputs:
 
           - source: a string of code to be executed, or an open file object we
           can iterate over.
 
         Optional inputs:
 
           - interact(False): if true, start to interact with the running
           program at the end of the script.  Otherwise, just exit.
 
           - get_output(False): if true, capture the output of the child process
           (filtering the input commands out) and return it as a string.
 
         Returns:
           A string containing the process output, but only if requested.
           """
 
         # if the source is a string, chop it up in lines so we can iterate
         # over it just as if it were an open file.
         if isinstance(source, basestring):
             source = source.splitlines(True)
 
         if self.echo:
             # normalize all strings we write to use the native OS line
             # separators.
             linesep  = os.linesep
             stdwrite = self.out.write
             write    = lambda s: stdwrite(s.replace('\r\n',linesep))
         else:
             # Quiet mode, all writes are no-ops
             write = lambda s: None
 
         c = self.child
         prompts = c.compile_pattern_list(self.prompts)
         prompt_idx = c.expect_list(prompts)
 
         # Flag whether the script ends normally or not, to know whether we can
         # do anything further with the underlying process.
         end_normal = True
 
         # If the output was requested, store it in a list for return at the end
         if get_output:
             output = []
             store_output = output.append
 
         for cmd in source:
             # skip blank lines for all matches to the 'main' prompt, while the
             # secondary prompts do not
             if prompt_idx==0 and \
                    (cmd.isspace() or cmd.lstrip().startswith('#')):
                 write(cmd)
                 continue
 
             # write('AFTER: '+c.after)  # dbg
             write(c.after)
             c.send(cmd)
             try:
                 prompt_idx = c.expect_list(prompts)
             except pexpect.EOF:
                 # this will happen if the child dies unexpectedly
                 write(c.before)
                 end_normal = False
                 break
 
             write(c.before)
 
             # With an echoing process, the output we get in c.before contains
             # the command sent, a newline, and then the actual process output
             if get_output:
                 store_output(c.before[len(cmd+'\n'):])
                 #write('CMD: <<%s>>' % cmd)  # dbg
                 #write('OUTPUT: <<%s>>' % output[-1])  # dbg
 
         self.out.flush()
         if end_normal:
             if interact:
                 c.send('\n')
                 print('<< Starting interactive mode >>', end=' ')
                 try:
                     c.interact()
                 except OSError:
                     # This is what fires when the child stops.  Simply print a
                     # newline so the system prompt is aligned.  The extra
                     # space is there to make sure it gets printed, otherwise
                     # OS buffering sometimes just suppresses it.
                     write(' \n')
                     self.out.flush()
         else:
             if interact:
                 e="Further interaction is not possible: child process is dead."
                 print(e, file=sys.stderr)
 
         # Leave the child ready for more input later on, otherwise select just
         # hangs on the second invocation.
         if c.isalive():
             c.send('\n')
 
         # Return any requested output
         if get_output:
             return ''.join(output)
 
     def main(self,argv=None):
         """Run as a command-line script."""
 
         parser = optparse.OptionParser(usage=USAGE % self.__class__.__name__)
         newopt = parser.add_option
         newopt('-i','--interact',action='store_true',default=False,
                help='Interact with the program after the script is run.')
 
         opts,args = parser.parse_args(argv)
 
         if len(args) != 1:
             print("You must supply exactly one file to run.", file=sys.stderr)
             sys.exit(1)
 
         self.run_file(args[0],opts.interact)
 
 _ipython_cmd = "ipython3" if py3compat.PY3 else "ipython"
 
 # Specific runners for particular programs
 class IPythonRunner(InteractiveRunner):
     """Interactive IPython runner.
 
     This initalizes IPython in 'nocolor' mode for simplicity.  This lets us
     avoid having to write a regexp that matches ANSI sequences, though pexpect
     does support them.  If anyone contributes patches for ANSI color support,
     they will be welcome.
 
     It also sets the prompts manually, since the prompt regexps for
     pexpect need to be matched to the actual prompts, so user-customized
     prompts would break this.
     """
 
     def __init__(self,program = _ipython_cmd, args=None, out=sys.stdout, echo=True):
         """New runner, optionally passing the ipython command to use."""
         args0 = ['--colors=NoColor',
                  '--no-term-title',
                  '--no-autoindent',
                  # '--quick' is important, to prevent loading default config:
                  '--quick']
         if args is None: args = args0
         else: args = args0 + args
         prompts = [r'In \[\d+\]: ',r'   \.*: ']
         InteractiveRunner.__init__(self,program,prompts,args,out,echo)
 
 
 class PythonRunner(InteractiveRunner):
     """Interactive Python runner."""
 
     def __init__(self,program=sys.executable, args=None, out=sys.stdout, echo=True):
         """New runner, optionally passing the python command to use."""
 
         prompts = [r'>>> ',r'\.\.\. ']
         InteractiveRunner.__init__(self,program,prompts,args,out,echo)
 
 
 class SAGERunner(InteractiveRunner):
     """Interactive SAGE runner.
 
     WARNING: this runner only works if you manually adjust your SAGE
     configuration so that the 'color' option in the configuration file is set to
     'NoColor', because currently the prompt matching regexp does not identify
     color sequences."""
 
     def __init__(self,program='sage',args=None,out=sys.stdout,echo=True):
         """New runner, optionally passing the sage command to use."""
 
         prompts = ['sage: ',r'\s*\.\.\. ']
         InteractiveRunner.__init__(self,program,prompts,args,out,echo)
 
 
 class RunnerFactory(object):
     """Code runner factory.
 
     This class provides an IPython code runner, but enforces that only one
     runner is ever instantiated.  The runner is created based on the extension
     of the first file to run, and it raises an exception if a runner is later
     requested for a different extension type.
 
     This ensures that we don't generate example files for doctest with a mix of
     python and ipython syntax.
     """
 
     def __init__(self,out=sys.stdout):
         """Instantiate a code runner."""
 
         self.out = out
         self.runner = None
         self.runnerClass = None
 
     def _makeRunner(self,runnerClass):
         self.runnerClass = runnerClass
         self.runner = runnerClass(out=self.out)
         return self.runner
 
     def __call__(self,fname):
         """Return a runner for the given filename."""
 
         if fname.endswith('.py'):
             runnerClass = PythonRunner
         elif fname.endswith('.ipy'):
             runnerClass = IPythonRunner
         else:
             raise ValueError('Unknown file type for Runner: %r' % fname)
 
         if self.runner is None:
             return self._makeRunner(runnerClass)
         else:
             if runnerClass==self.runnerClass:
                 return self.runner
             else:
                 e='A runner of type %r can not run file %r' % \
                    (self.runnerClass,fname)
                 raise ValueError(e)
 
 
 # Global usage string, to avoid indentation issues if typed in a function def.
 MAIN_USAGE = """
 %prog [options] file_to_run
 
 This is an interface to the various interactive runners available in this
 module.  If you want to pass specific options to one of the runners, you need
 to first terminate the main options with a '--', and then provide the runner's
 options.  For example:
 
 irunner.py --python -- --help
 
 will pass --help to the python runner.  Similarly,
 
 irunner.py --ipython -- --interact script.ipy
 
 will run the script.ipy file under the IPython runner, and then will start to
 interact with IPython at the end of the script (instead of exiting).
 
 The already implemented runners are listed below; adding one for a new program
 is a trivial task, see the source for examples.
 """
 
 def main():
     """Run as a command-line script."""
 
     parser = optparse.OptionParser(usage=MAIN_USAGE)
     newopt = parser.add_option
     newopt('--ipython',action='store_const',dest='mode',const='ipython',
            help='IPython interactive runner (default).')
     newopt('--python',action='store_const',dest='mode',const='python',
            help='Python interactive runner.')
     newopt('--sage',action='store_const',dest='mode',const='sage',
            help='SAGE interactive runner.')
 
     opts,args = parser.parse_args()
     runners = dict(ipython=IPythonRunner,
                    python=PythonRunner,
                    sage=SAGERunner)
 
     try:
         ext = os.path.splitext(args[0])[-1]
     except IndexError:
         ext = ''
     modes = {'.ipy':'ipython',
              '.py':'python',
              '.sage':'sage'}
     mode = modes.get(ext,"ipython")
     if opts.mode:
         mode = opts.mode
     runners[mode]().main(args)
 
 if __name__ == '__main__':
     main()

IPython/lib/pretty.py

@@ -1,734 +1,736 b''
 # -*- coding: utf-8 -*-
 """
-    pretty
-    ~~
-
     Python advanced pretty printer.  This pretty printer is intended to
     replace the old `pprint` python module which does not allow developers
     to provide their own pretty print callbacks.
 
     This module is based on ruby's `prettyprint.rb` library by `Tanaka Akira`.
 
 
     Example Usage
-    =============
+-------------
 
     To directly print the representation of an object use `pprint`::
 
         from pretty import pprint
         pprint(complex_object)
 
     To get a string of the output use `pretty`::
 
         from pretty import pretty
         string = pretty(complex_object)
 
 
     Extending
-    =========
+---------
 
     The pretty library allows developers to add pretty printing rules for their
     own objects.  This process is straightforward.  All you have to do is to
     add a `_repr_pretty_` method to your object and call the methods on the
     pretty printer passed::
 
         class MyObject(object):
 
             def _repr_pretty_(self, p, cycle):
                 ...
 
     Depending on the python version you want to support you have two
     possibilities.  The following list shows the python 2.5 version and the
     compatibility one.
 
 
     Here the example implementation of a `_repr_pretty_` method for a list
     subclass for python 2.5 and higher (python 2.5 requires the with statement
     __future__ import)::
 
         class MyList(list):
 
             def _repr_pretty_(self, p, cycle):
                 if cycle:
                     p.text('MyList(...)')
                 else:
                     with p.group(8, 'MyList([', '])'):
                         for idx, item in enumerate(self):
                             if idx:
                                 p.text(',')
                                 p.breakable()
                             p.pretty(item)
 
     The `cycle` parameter is `True` if pretty detected a cycle.  You *have* to
     react to that or the result is an infinite loop.  `p.text()` just adds
     non breaking text to the output, `p.breakable()` either adds a whitespace
     or breaks here.  If you pass it an argument it's used instead of the
     default space.  `p.pretty` prettyprints another object using the pretty print
     method.
 
     The first parameter to the `group` function specifies the extra indentation
     of the next line.  In this example the next item will either be not
     breaked (if the items are short enough) or aligned with the right edge of
     the opening bracked of `MyList`.
 
     If you want to support python 2.4 and lower you can use this code::
 
         class MyList(list):
 
             def _repr_pretty_(self, p, cycle):
                 if cycle:
                     p.text('MyList(...)')
                 else:
                     p.begin_group(8, 'MyList([')
                     for idx, item in enumerate(self):
                         if idx:
                             p.text(',')
                             p.breakable()
                         p.pretty(item)
                     p.end_group(8, '])')
 
     If you just want to indent something you can use the group function
     without open / close parameters.  Under python 2.5 you can also use this
     code::
 
         with p.indent(2):
             ...
 
     Or under python2.4 you might want to modify ``p.indentation`` by hand but
     this is rather ugly.
 
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.lib.pretty
+   :parts: 3
+
     :copyright: 2007 by Armin Ronacher.
                 Portions (c) 2009 by Robert Kern.
     :license: BSD License.
 """
 from __future__ import with_statement
 from contextlib import contextmanager
 import sys
 import types
 import re
 import datetime
 from StringIO import StringIO
 from collections import deque
 
 
 __all__ = ['pretty', 'pprint', 'PrettyPrinter', 'RepresentationPrinter',
     'for_type', 'for_type_by_name']
 
 
 _re_pattern_type = type(re.compile(''))
 
 
 def pretty(obj, verbose=False, max_width=79, newline='\n'):
     """
     Pretty print the object's representation.
     """
     stream = StringIO()
     printer = RepresentationPrinter(stream, verbose, max_width, newline)
     printer.pretty(obj)
     printer.flush()
     return stream.getvalue()
 
 
 def pprint(obj, verbose=False, max_width=79, newline='\n'):
     """
     Like `pretty` but print to stdout.
     """
     printer = RepresentationPrinter(sys.stdout, verbose, max_width, newline)
     printer.pretty(obj)
     printer.flush()
     sys.stdout.write(newline)
     sys.stdout.flush()
 
 class _PrettyPrinterBase(object):
 
     @contextmanager
     def indent(self, indent):
         """with statement support for indenting/dedenting."""
         self.indentation += indent
         try:
             yield
         finally:
             self.indentation -= indent
 
     @contextmanager
     def group(self, indent=0, open='', close=''):
         """like begin_group / end_group but for the with statement."""
         self.begin_group(indent, open)
         try:
             yield
         finally:
             self.end_group(indent, close)
 
 class PrettyPrinter(_PrettyPrinterBase):
     """
     Baseclass for the `RepresentationPrinter` prettyprinter that is used to
     generate pretty reprs of objects.  Contrary to the `RepresentationPrinter`
     this printer knows nothing about the default pprinters or the `_repr_pretty_`
     callback method.
     """
 
     def __init__(self, output, max_width=79, newline='\n'):
         self.output = output
         self.max_width = max_width
         self.newline = newline
         self.output_width = 0
         self.buffer_width = 0
         self.buffer = deque()
 
         root_group = Group(0)
         self.group_stack = [root_group]
         self.group_queue = GroupQueue(root_group)
         self.indentation = 0
 
     def _break_outer_groups(self):
         while self.max_width < self.output_width + self.buffer_width:
             group = self.group_queue.deq()
             if not group:
                 return
             while group.breakables:
                 x = self.buffer.popleft()
                 self.output_width = x.output(self.output, self.output_width)
                 self.buffer_width -= x.width
             while self.buffer and isinstance(self.buffer[0], Text):
                 x = self.buffer.popleft()
                 self.output_width = x.output(self.output, self.output_width)
                 self.buffer_width -= x.width
 
     def text(self, obj):
         """Add literal text to the output."""
         width = len(obj)
         if self.buffer:
             text = self.buffer[-1]
             if not isinstance(text, Text):
                 text = Text()
                 self.buffer.append(text)
             text.add(obj, width)
             self.buffer_width += width
             self._break_outer_groups()
         else:
             self.output.write(obj)
             self.output_width += width
 
     def breakable(self, sep=' '):
         """
         Add a breakable separator to the output.  This does not mean that it
         will automatically break here.  If no breaking on this position takes
         place the `sep` is inserted which default to one space.
         """
         width = len(sep)
         group = self.group_stack[-1]
         if group.want_break:
             self.flush()
             self.output.write(self.newline)
             self.output.write(' ' * self.indentation)
             self.output_width = self.indentation
             self.buffer_width = 0
         else:
             self.buffer.append(Breakable(sep, width, self))
             self.buffer_width += width
             self._break_outer_groups()
 
 
     def begin_group(self, indent=0, open=''):
         """
         Begin a group.  If you want support for python < 2.5 which doesn't has
         the with statement this is the preferred way:
 
             p.begin_group(1, '{')
             ...
             p.end_group(1, '}')
 
         The python 2.5 expression would be this:
 
             with p.group(1, '{', '}'):
                 ...
 
         The first parameter specifies the indentation for the next line (usually
         the width of the opening text), the second the opening text.  All
         parameters are optional.
         """
         if open:
             self.text(open)
         group = Group(self.group_stack[-1].depth + 1)
         self.group_stack.append(group)
         self.group_queue.enq(group)
         self.indentation += indent
 
     def end_group(self, dedent=0, close=''):
         """End a group. See `begin_group` for more details."""
         self.indentation -= dedent
         group = self.group_stack.pop()
         if not group.breakables:
             self.group_queue.remove(group)
         if close:
             self.text(close)
 
     def flush(self):
         """Flush data that is left in the buffer."""
         for data in self.buffer:
             self.output_width += data.output(self.output, self.output_width)
         self.buffer.clear()
         self.buffer_width = 0
 
 
 def _get_mro(obj_class):
     """ Get a reasonable method resolution order of a class and its superclasses
     for both old-style and new-style classes.
     """
     if not hasattr(obj_class, '__mro__'):
         # Old-style class. Mix in object to make a fake new-style class.
         try:
             obj_class = type(obj_class.__name__, (obj_class, object), {})
         except TypeError:
             # Old-style extension type that does not descend from object.
             # FIXME: try to construct a more thorough MRO.
             mro = [obj_class]
         else:
             mro = obj_class.__mro__[1:-1]
     else:
         mro = obj_class.__mro__
     return mro
 
 
 class RepresentationPrinter(PrettyPrinter):
     """
     Special pretty printer that has a `pretty` method that calls the pretty
     printer for a python object.
 
     This class stores processing data on `self` so you must *never* use
     this class in a threaded environment.  Always lock it or reinstanciate
     it.
 
     Instances also have a verbose flag callbacks can access to control their
     output.  For example the default instance repr prints all attributes and
     methods that are not prefixed by an underscore if the printer is in
     verbose mode.
     """
 
     def __init__(self, output, verbose=False, max_width=79, newline='\n',
         singleton_pprinters=None, type_pprinters=None, deferred_pprinters=None):
 
         PrettyPrinter.__init__(self, output, max_width, newline)
         self.verbose = verbose
         self.stack = []
         if singleton_pprinters is None:
             singleton_pprinters = _singleton_pprinters.copy()
         self.singleton_pprinters = singleton_pprinters
         if type_pprinters is None:
             type_pprinters = _type_pprinters.copy()
         self.type_pprinters = type_pprinters
         if deferred_pprinters is None:
             deferred_pprinters = _deferred_type_pprinters.copy()
         self.deferred_pprinters = deferred_pprinters
 
     def pretty(self, obj):
         """Pretty print the given object."""
         obj_id = id(obj)
         cycle = obj_id in self.stack
         self.stack.append(obj_id)
         self.begin_group()
         try:
             obj_class = getattr(obj, '__class__', None) or type(obj)
             # First try to find registered singleton printers for the type.
             try:
                 printer = self.singleton_pprinters[obj_id]
             except (TypeError, KeyError):
                 pass
             else:
                 return printer(obj, self, cycle)
             # Next walk the mro and check for either:
             #   1) a registered printer
             #   2) a _repr_pretty_ method
             for cls in _get_mro(obj_class):
                 if cls in self.type_pprinters:
                     # printer registered in self.type_pprinters
                     return self.type_pprinters[cls](obj, self, cycle)
                 else:
                     # deferred printer
                     printer = self._in_deferred_types(cls)
                     if printer is not None:
                         return printer(obj, self, cycle)
                     else:
                         # Finally look for special method names.
                         # Some objects automatically create any requested
                         # attribute. Try to ignore most of them by checking for
                         # callability.
                         if '_repr_pretty_' in cls.__dict__:
                             meth = cls._repr_pretty_
                             if callable(meth):
                                 return meth(obj, self, cycle)
             return _default_pprint(obj, self, cycle)
         finally:
             self.end_group()
             self.stack.pop()
 
     def _in_deferred_types(self, cls):
         """
         Check if the given class is specified in the deferred type registry.
 
         Returns the printer from the registry if it exists, and None if the
         class is not in the registry. Successful matches will be moved to the
         regular type registry for future use.
         """
         mod = getattr(cls, '__module__', None)
         name = getattr(cls, '__name__', None)
         key = (mod, name)
         printer = None
         if key in self.deferred_pprinters:
             # Move the printer over to the regular registry.
             printer = self.deferred_pprinters.pop(key)
             self.type_pprinters[cls] = printer
         return printer
 
 
 class Printable(object):
 
     def output(self, stream, output_width):
         return output_width
 
 
 class Text(Printable):
 
     def __init__(self):
         self.objs = []
         self.width = 0
 
     def output(self, stream, output_width):
         for obj in self.objs:
             stream.write(obj)
         return output_width + self.width
 
     def add(self, obj, width):
         self.objs.append(obj)
         self.width += width
 
 
 class Breakable(Printable):
 
     def __init__(self, seq, width, pretty):
         self.obj = seq
         self.width = width
         self.pretty = pretty
         self.indentation = pretty.indentation
         self.group = pretty.group_stack[-1]
         self.group.breakables.append(self)
 
     def output(self, stream, output_width):
         self.group.breakables.popleft()
         if self.group.want_break:
             stream.write(self.pretty.newline)
             stream.write(' ' * self.indentation)
             return self.indentation
         if not self.group.breakables:
             self.pretty.group_queue.remove(self.group)
         stream.write(self.obj)
         return output_width + self.width
 
 
 class Group(Printable):
 
     def __init__(self, depth):
         self.depth = depth
         self.breakables = deque()
         self.want_break = False
 
 
 class GroupQueue(object):
 
     def __init__(self, *groups):
         self.queue = []
         for group in groups:
             self.enq(group)
 
     def enq(self, group):
         depth = group.depth
         while depth > len(self.queue) - 1:
             self.queue.append([])
         self.queue[depth].append(group)
 
     def deq(self):
         for stack in self.queue:
             for idx, group in enumerate(reversed(stack)):
                 if group.breakables:
                     del stack[idx]
                     group.want_break = True
                     return group
             for group in stack:
                 group.want_break = True
             del stack[:]
 
     def remove(self, group):
         try:
             self.queue[group.depth].remove(group)
         except ValueError:
             pass
 
 try:
     _baseclass_reprs = (object.__repr__, types.InstanceType.__repr__)
 except AttributeError:  # Python 3
     _baseclass_reprs = (object.__repr__,)
 
 
 def _default_pprint(obj, p, cycle):
     """
     The default print function.  Used if an object does not provide one and
     it's none of the builtin objects.
     """
     klass = getattr(obj, '__class__', None) or type(obj)
     if getattr(klass, '__repr__', None) not in _baseclass_reprs:
         # A user-provided repr.
         p.text(repr(obj))
         return
     p.begin_group(1, '<')
     p.pretty(klass)
     p.text(' at 0x%x' % id(obj))
     if cycle:
         p.text(' ...')
     elif p.verbose:
         first = True
         for key in dir(obj):
             if not key.startswith('_'):
                 try:
                     value = getattr(obj, key)
                 except AttributeError:
                     continue
                 if isinstance(value, types.MethodType):
                     continue
                 if not first:
                     p.text(',')
                 p.breakable()
                 p.text(key)
                 p.text('=')
                 step = len(key) + 1
                 p.indentation += step
                 p.pretty(value)
                 p.indentation -= step
                 first = False
     p.end_group(1, '>')
 
 
 def _seq_pprinter_factory(start, end, basetype):
     """
     Factory that returns a pprint function useful for sequences.  Used by
     the default pprint for tuples, dicts, lists, sets and frozensets.
     """
     def inner(obj, p, cycle):
         typ = type(obj)
         if basetype is not None and typ is not basetype and typ.__repr__ != basetype.__repr__:
             # If the subclass provides its own repr, use it instead.
             return p.text(typ.__repr__(obj))
 
         if cycle:
             return p.text(start + '...' + end)
         step = len(start)
         p.begin_group(step, start)
         for idx, x in enumerate(obj):
             if idx:
                 p.text(',')
                 p.breakable()
             p.pretty(x)
         if len(obj) == 1 and type(obj) is tuple:
             # Special case for 1-item tuples.
             p.text(',')
         p.end_group(step, end)
     return inner
 
 
 def _dict_pprinter_factory(start, end, basetype=None):
     """
     Factory that returns a pprint function used by the default pprint of
     dicts and dict proxies.
     """
     def inner(obj, p, cycle):
         typ = type(obj)
         if basetype is not None and typ is not basetype and typ.__repr__ != basetype.__repr__:
             # If the subclass provides its own repr, use it instead.
             return p.text(typ.__repr__(obj))
 
         if cycle:
             return p.text('{...}')
         p.begin_group(1, start)
         keys = obj.keys()
         try:
             keys.sort()
         except Exception as e:
             # Sometimes the keys don't sort.
             pass
         for idx, key in enumerate(keys):
             if idx:
                 p.text(',')
                 p.breakable()
             p.pretty(key)
             p.text(': ')
             p.pretty(obj[key])
         p.end_group(1, end)
     return inner
 
 
 def _super_pprint(obj, p, cycle):
     """The pprint for the super type."""
     p.begin_group(8, '<super: ')
     p.pretty(obj.__self_class__)
     p.text(',')
     p.breakable()
     p.pretty(obj.__self__)
     p.end_group(8, '>')
 
 
 def _re_pattern_pprint(obj, p, cycle):
     """The pprint function for regular expression patterns."""
     p.text('re.compile(')
     pattern = repr(obj.pattern)
     if pattern[:1] in 'uU':
         pattern = pattern[1:]
         prefix = 'ur'
     else:
         prefix = 'r'
     pattern = prefix + pattern.replace('\\\\', '\\')
     p.text(pattern)
     if obj.flags:
         p.text(',')
         p.breakable()
         done_one = False
         for flag in ('TEMPLATE', 'IGNORECASE', 'LOCALE', 'MULTILINE', 'DOTALL',
             'UNICODE', 'VERBOSE', 'DEBUG'):
             if obj.flags & getattr(re, flag):
                 if done_one:
                     p.text('|')
                 p.text('re.' + flag)
                 done_one = True
     p.text(')')
 
 
 def _type_pprint(obj, p, cycle):
     """The pprint for classes and types."""
     if obj.__module__ in ('__builtin__', 'exceptions'):
         name = obj.__name__
     else:
         name = obj.__module__ + '.' + obj.__name__
     p.text(name)
 
 
 def _repr_pprint(obj, p, cycle):
     """A pprint that just redirects to the normal repr function."""
     p.text(repr(obj))
 
 
 def _function_pprint(obj, p, cycle):
     """Base pprint for all functions and builtin functions."""
     if obj.__module__ in ('__builtin__', 'exceptions') or not obj.__module__:
         name = obj.__name__
     else:
         name = obj.__module__ + '.' + obj.__name__
     p.text('<function %s>' % name)
 
 
 def _exception_pprint(obj, p, cycle):
     """Base pprint for all exceptions."""
     if obj.__class__.__module__ in ('exceptions', 'builtins'):
         name = obj.__class__.__name__
     else:
         name = '%s.%s' % (
             obj.__class__.__module__,
             obj.__class__.__name__
         )
     step = len(name) + 1
     p.begin_group(step, name + '(')
     for idx, arg in enumerate(getattr(obj, 'args', ())):
         if idx:
             p.text(',')
             p.breakable()
         p.pretty(arg)
     p.end_group(step, ')')
 
 
 #: the exception base
 try:
     _exception_base = BaseException
 except NameError:
     _exception_base = Exception
 
 
 #: printers for builtin types
 _type_pprinters = {
     int:                        _repr_pprint,
     long:                       _repr_pprint,
     float:                      _repr_pprint,
     str:                        _repr_pprint,
     unicode:                    _repr_pprint,
     tuple:                      _seq_pprinter_factory('(', ')', tuple),
     list:                       _seq_pprinter_factory('[', ']', list),
     dict:                       _dict_pprinter_factory('{', '}', dict),
     
     set:                        _seq_pprinter_factory('set([', '])', set),
     frozenset:                  _seq_pprinter_factory('frozenset([', '])', frozenset),
     super:                      _super_pprint,
     _re_pattern_type:           _re_pattern_pprint,
     type:                       _type_pprint,
     types.FunctionType:         _function_pprint,
     types.BuiltinFunctionType:  _function_pprint,
     types.SliceType:            _repr_pprint,
     types.MethodType:           _repr_pprint,
     
     datetime.datetime:          _repr_pprint,
     datetime.timedelta:         _repr_pprint,
     _exception_base:            _exception_pprint
 }
 
 try:
     _type_pprinters[types.DictProxyType] = _dict_pprinter_factory('<dictproxy {', '}>')
     _type_pprinters[types.ClassType] = _type_pprint
 except AttributeError: # Python 3
     pass
     
 try:
     _type_pprinters[xrange] = _repr_pprint
 except NameError:
     _type_pprinters[range] = _repr_pprint
 
 #: printers for types specified by name
 _deferred_type_pprinters = {
 }
 
 def for_type(typ, func):
     """
     Add a pretty printer for a given type.
     """
     oldfunc = _type_pprinters.get(typ, None)
     if func is not None:
         # To support easy restoration of old pprinters, we need to ignore Nones.
         _type_pprinters[typ] = func
     return oldfunc
 
 def for_type_by_name(type_module, type_name, func):
     """
     Add a pretty printer for a type specified by the module and name of a type
     rather than the type object itself.
     """
     key = (type_module, type_name)
     oldfunc = _deferred_type_pprinters.get(key, None)
     if func is not None:
         # To support easy restoration of old pprinters, we need to ignore Nones.
         _deferred_type_pprinters[key] = func
     return oldfunc
 
 
 #: printers for the default singletons
 _singleton_pprinters = dict.fromkeys(map(id, [None, True, False, Ellipsis,
                                       NotImplemented]), _repr_pprint)
 
 
 if __name__ == '__main__':
     from random import randrange
     class Foo(object):
         def __init__(self):
             self.foo = 1
             self.bar = re.compile(r'\s+')
             self.blub = dict.fromkeys(range(30), randrange(1, 40))
             self.hehe = 23424.234234
             self.list = ["blub", "blah", self]
 
         def get_foo(self):
             print "foo"
 
     pprint(Foo(), verbose=True)

IPython/parallel/error.py

@@ -1,341 +1,346 b''
 # encoding: utf-8
 
 """Classes and functions for kernel related errors and exceptions.
 
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.parallel.error
+   :parts: 3
+
 Authors:
 
 * Brian Granger
 * Min RK
 """
 from __future__ import print_function
 
 import sys
 import traceback
 
 __docformat__ = "restructuredtext en"
 
 # Tell nose to skip this module
 __test__ = {}
 
 #-------------------------------------------------------------------------------
 #  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.
 #-------------------------------------------------------------------------------
 
 #-------------------------------------------------------------------------------
 # Error classes
 #-------------------------------------------------------------------------------
 class IPythonError(Exception):
     """Base exception that all of our exceptions inherit from.
 
     This can be raised by code that doesn't have any more specific
     information."""
 
     pass
 
 # Exceptions associated with the controller objects
 class ControllerError(IPythonError): pass
 
 class ControllerCreationError(ControllerError): pass
 
 
 # Exceptions associated with the Engines
 class EngineError(IPythonError): pass
 
 class EngineCreationError(EngineError): pass
 
 class KernelError(IPythonError):
     pass
 
 class NotDefined(KernelError):
     def __init__(self, name):
         self.name = name
         self.args = (name,)
 
     def __repr__(self):
         return '<NotDefined: %s>' % self.name
 
     __str__ = __repr__
 
 
 class QueueCleared(KernelError):
     pass
 
 
 class IdInUse(KernelError):
     pass
 
 
 class ProtocolError(KernelError):
     pass
 
 
 class ConnectionError(KernelError):
     pass
 
 
 class InvalidEngineID(KernelError):
     pass
 
 
 class NoEnginesRegistered(KernelError):
     pass
 
 
 class InvalidClientID(KernelError):
     pass
 
 
 class InvalidDeferredID(KernelError):
     pass
 
 
 class SerializationError(KernelError):
     pass
 
 
 class MessageSizeError(KernelError):
     pass
 
 
 class PBMessageSizeError(MessageSizeError):
     pass
 
 
 class ResultNotCompleted(KernelError):
     pass
 
 
 class ResultAlreadyRetrieved(KernelError):
     pass
 
 class ClientError(KernelError):
     pass
 
 
 class TaskAborted(KernelError):
     pass
 
 
 class TaskTimeout(KernelError):
     pass
 
 
 class NotAPendingResult(KernelError):
     pass
 
 
 class UnpickleableException(KernelError):
     pass
 
 
 class AbortedPendingDeferredError(KernelError):
     pass
 
 
 class InvalidProperty(KernelError):
     pass
 
 
 class MissingBlockArgument(KernelError):
     pass
 
 
 class StopLocalExecution(KernelError):
     pass
 
 
 class SecurityError(KernelError):
     pass
 
 
 class FileTimeoutError(KernelError):
     pass
 
 class TimeoutError(KernelError):
     pass
 
 class UnmetDependency(KernelError):
     pass
 
 class ImpossibleDependency(UnmetDependency):
     pass
 
 class DependencyTimeout(ImpossibleDependency):
     pass
 
 class InvalidDependency(ImpossibleDependency):
     pass
 
 class RemoteError(KernelError):
     """Error raised elsewhere"""
     ename=None
     evalue=None
     traceback=None
     engine_info=None
 
     def __init__(self, ename, evalue, traceback, engine_info=None):
         self.ename=ename
         self.evalue=evalue
         self.traceback=traceback
         self.engine_info=engine_info or {}
         self.args=(ename, evalue)
 
     def __repr__(self):
         engineid = self.engine_info.get('engine_id', ' ')
         return "<Remote[%s]:%s(%s)>"%(engineid, self.ename, self.evalue)
 
     def __str__(self):
         return "%s(%s)" % (self.ename, self.evalue)
     
     def render_traceback(self):
         """render traceback to a list of lines"""
         return (self.traceback or "No traceback available").splitlines()
     
     def _render_traceback_(self):
         """Special method for custom tracebacks within IPython.
         
         This will be called by IPython instead of displaying the local traceback.
         
         It should return a traceback rendered as a list of lines.
         """
         return self.render_traceback()
     
     def print_traceback(self, excid=None):
         """print my traceback"""
         print('\n'.join(self.render_traceback()))
 
     
 
 
 class TaskRejectError(KernelError):
     """Exception to raise when a task should be rejected by an engine.
 
     This exception can be used to allow a task running on an engine to test
     if the engine (or the user's namespace on the engine) has the needed
     task dependencies.  If not, the task should raise this exception.  For
     the task to be retried on another engine, the task should be created
     with the `retries` argument > 1.
 
     The advantage of this approach over our older properties system is that
     tasks have full access to the user's namespace on the engines and the
     properties don't have to be managed or tested by the controller.
     """
 
 
 class CompositeError(RemoteError):
     """Error for representing possibly multiple errors on engines"""
     def __init__(self, message, elist):
         Exception.__init__(self, *(message, elist))
         # Don't use pack_exception because it will conflict with the .message
         # attribute that is being deprecated in 2.6 and beyond.
         self.msg = message
         self.elist = elist
         self.args = [ e[0] for e in elist ]
 
     def _get_engine_str(self, ei):
         if not ei:
             return '[Engine Exception]'
         else:
             return '[%s:%s]: ' % (ei['engine_id'], ei['method'])
 
     def _get_traceback(self, ev):
         try:
             tb = ev._ipython_traceback_text
         except AttributeError:
             return 'No traceback available'
         else:
             return tb
 
     def __str__(self):
         s = str(self.msg)
         for en, ev, etb, ei in self.elist:
             engine_str = self._get_engine_str(ei)
             s = s + '\n' + engine_str + en + ': ' + str(ev)
         return s
 
     def __repr__(self):
         return "CompositeError(%i)"%len(self.elist)
     
     def render_traceback(self, excid=None):
         """render one or all of my tracebacks to a list of lines"""
         lines = []
         if excid is None:
             for (en,ev,etb,ei) in self.elist:
                 lines.append(self._get_engine_str(ei))
                 lines.extend((etb or 'No traceback available').splitlines())
                 lines.append('')
         else:
             try:
                 en,ev,etb,ei = self.elist[excid]
             except:
                 raise IndexError("an exception with index %i does not exist"%excid)
             else:
                 lines.append(self._get_engine_str(ei))
                 lines.extend((etb or 'No traceback available').splitlines())
         
         return lines
     
     def print_traceback(self, excid=None):
         print('\n'.join(self.render_traceback(excid)))
 
     def raise_exception(self, excid=0):
         try:
             en,ev,etb,ei = self.elist[excid]
         except:
             raise IndexError("an exception with index %i does not exist"%excid)
         else:
             raise RemoteError(en, ev, etb, ei)
 
 
 def collect_exceptions(rdict_or_list, method='unspecified'):
     """check a result dict for errors, and raise CompositeError if any exist.
     Passthrough otherwise."""
     elist = []
     if isinstance(rdict_or_list, dict):
         rlist = rdict_or_list.values()
     else:
         rlist = rdict_or_list
     for r in rlist:
         if isinstance(r, RemoteError):
             en, ev, etb, ei = r.ename, r.evalue, r.traceback, r.engine_info
             # Sometimes we could have CompositeError in our list.  Just take
             # the errors out of them and put them in our new list.  This
             # has the effect of flattening lists of CompositeErrors into one
             # CompositeError
             if en=='CompositeError':
                 for e in ev.elist:
                     elist.append(e)
             else:
                 elist.append((en, ev, etb, ei))
     if len(elist)==0:
         return rdict_or_list
     else:
         msg = "one or more exceptions from call to method: %s" % (method)
         # This silliness is needed so the debugger has access to the exception
         # instance (e in this case)
         try:
             raise CompositeError(msg, elist)
         except CompositeError as e:
             raise e
 
 def wrap_exception(engine_info={}):
     etype, evalue, tb = sys.exc_info()
     stb = traceback.format_exception(etype, evalue, tb)
     exc_content = {
         'status' : 'error',
         'traceback' : stb,
         'ename' : unicode(etype.__name__),
         'evalue' : unicode(evalue),
         'engine_info' : engine_info
     }
     return exc_content
 
 def unwrap_exception(content):
     err = RemoteError(content['ename'], content['evalue'],
                 ''.join(content['traceback']),
                 content.get('engine_info', {}))
     return err
 

IPython/utils/text.py

@@ -1,845 +1,850 b''
 # encoding: utf-8
 """
 Utilities for working with strings and text.
+
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.utils.text
+   :parts: 3
 """
 
 #-----------------------------------------------------------------------------
 #  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 __main__
 
 import os
 import re
 import shutil
 import sys
 import textwrap
 from string import Formatter
 
 from IPython.external.path import path
 from IPython.testing.skipdoctest import skip_doctest_py3, skip_doctest
 from IPython.utils import py3compat
 from IPython.utils.io import nlprint
 from IPython.utils.data import flatten
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
 def unquote_ends(istr):
     """Remove a single pair of quotes from the endpoints of a string."""
 
     if not istr:
         return istr
     if (istr[0]=="'" and istr[-1]=="'") or \
        (istr[0]=='"' and istr[-1]=='"'):
         return istr[1:-1]
     else:
         return istr
 
 
 class LSString(str):
     """String derivative with a special access attributes.
 
     These are normal strings, but with the special attributes:
 
         .l (or .list) : value as list (split on newlines).
         .n (or .nlstr): original value (the string itself).
         .s (or .spstr): value as whitespace-separated string.
         .p (or .paths): list of path objects
 
     Any values which require transformations are computed only once and
     cached.
 
     Such strings are very useful to efficiently interact with the shell, which
     typically only understands whitespace-separated options for commands."""
 
     def get_list(self):
         try:
             return self.__list
         except AttributeError:
             self.__list = self.split('\n')
             return self.__list
 
     l = list = property(get_list)
 
     def get_spstr(self):
         try:
             return self.__spstr
         except AttributeError:
             self.__spstr = self.replace('\n',' ')
             return self.__spstr
 
     s = spstr = property(get_spstr)
 
     def get_nlstr(self):
         return self
 
     n = nlstr = property(get_nlstr)
 
     def get_paths(self):
         try:
             return self.__paths
         except AttributeError:
             self.__paths = [path(p) for p in self.split('\n') if os.path.exists(p)]
             return self.__paths
 
     p = paths = property(get_paths)
 
 # FIXME: We need to reimplement type specific displayhook and then add this
 # back as a custom printer. This should also be moved outside utils into the
 # core.
 
 # def print_lsstring(arg):
 #     """ Prettier (non-repr-like) and more informative printer for LSString """
 #     print "LSString (.p, .n, .l, .s available). Value:"
 #     print arg
 #
 #
 # print_lsstring = result_display.when_type(LSString)(print_lsstring)
 
 
 class SList(list):
     """List derivative with a special access attributes.
 
     These are normal lists, but with the special attributes:
 
         .l (or .list) : value as list (the list itself).
         .n (or .nlstr): value as a string, joined on newlines.
         .s (or .spstr): value as a string, joined on spaces.
         .p (or .paths): list of path objects
 
     Any values which require transformations are computed only once and
     cached."""
 
     def get_list(self):
         return self
 
     l = list = property(get_list)
 
     def get_spstr(self):
         try:
             return self.__spstr
         except AttributeError:
             self.__spstr = ' '.join(self)
             return self.__spstr
 
     s = spstr = property(get_spstr)
 
     def get_nlstr(self):
         try:
             return self.__nlstr
         except AttributeError:
             self.__nlstr = '\n'.join(self)
             return self.__nlstr
 
     n = nlstr = property(get_nlstr)
 
     def get_paths(self):
         try:
             return self.__paths
         except AttributeError:
             self.__paths = [path(p) for p in self if os.path.exists(p)]
             return self.__paths
 
     p = paths = property(get_paths)
 
     def grep(self, pattern, prune = False, field = None):
         """ Return all strings matching 'pattern' (a regex or callable)
 
         This is case-insensitive. If prune is true, return all items
         NOT matching the pattern.
 
         If field is specified, the match must occur in the specified
         whitespace-separated field.
 
         Examples::
 
             a.grep( lambda x: x.startswith('C') )
             a.grep('Cha.*log', prune=1)
             a.grep('chm', field=-1)
         """
 
         def match_target(s):
             if field is None:
                 return s
             parts = s.split()
             try:
                 tgt = parts[field]
                 return tgt
             except IndexError:
                 return ""
 
         if isinstance(pattern, basestring):
             pred = lambda x : re.search(pattern, x, re.IGNORECASE)
         else:
             pred = pattern
         if not prune:
             return SList([el for el in self if pred(match_target(el))])
         else:
             return SList([el for el in self if not pred(match_target(el))])
 
     def fields(self, *fields):
         """ Collect whitespace-separated fields from string list
 
         Allows quick awk-like usage of string lists.
 
         Example data (in var a, created by 'a = !ls -l')::
             -rwxrwxrwx  1 ville None      18 Dec 14  2006 ChangeLog
             drwxrwxrwx+ 6 ville None       0 Oct 24 18:05 IPython
 
         a.fields(0) is ['-rwxrwxrwx', 'drwxrwxrwx+']
         a.fields(1,0) is ['1 -rwxrwxrwx', '6 drwxrwxrwx+']
         (note the joining by space).
         a.fields(-1) is ['ChangeLog', 'IPython']
 
         IndexErrors are ignored.
 
         Without args, fields() just split()'s the strings.
         """
         if len(fields) == 0:
             return [el.split() for el in self]
 
         res = SList()
         for el in [f.split() for f in self]:
             lineparts = []
 
             for fd in fields:
                 try:
                     lineparts.append(el[fd])
                 except IndexError:
                     pass
             if lineparts:
                 res.append(" ".join(lineparts))
 
         return res
 
     def sort(self,field= None,  nums = False):
         """ sort by specified fields (see fields())
 
         Example::
             a.sort(1, nums = True)
 
         Sorts a by second field, in numerical order (so that 21 > 3)
 
         """
 
         #decorate, sort, undecorate
         if field is not None:
             dsu = [[SList([line]).fields(field),  line] for line in self]
         else:
             dsu = [[line,  line] for line in self]
         if nums:
             for i in range(len(dsu)):
                 numstr = "".join([ch for ch in dsu[i][0] if ch.isdigit()])
                 try:
                     n = int(numstr)
                 except ValueError:
                     n = 0;
                 dsu[i][0] = n
 
 
         dsu.sort()
         return SList([t[1] for t in dsu])
 
 
 # FIXME: We need to reimplement type specific displayhook and then add this
 # back as a custom printer. This should also be moved outside utils into the
 # core.
 
 # def print_slist(arg):
 #     """ Prettier (non-repr-like) and more informative printer for SList """
 #     print "SList (.p, .n, .l, .s, .grep(), .fields(), sort() available):"
 #     if hasattr(arg,  'hideonce') and arg.hideonce:
 #         arg.hideonce = False
 #         return
 #
 #     nlprint(arg)
 #
 # print_slist = result_display.when_type(SList)(print_slist)
 
 
 def esc_quotes(strng):
     """Return the input string with single and double quotes escaped out"""
 
     return strng.replace('"','\\"').replace("'","\\'")
 
 
 def qw(words,flat=0,sep=None,maxsplit=-1):
     """Similar to Perl's qw() operator, but with some more options.
 
     qw(words,flat=0,sep=' ',maxsplit=-1) -> words.split(sep,maxsplit)
 
     words can also be a list itself, and with flat=1, the output will be
     recursively flattened.
 
     Examples:
 
     >>> qw('1 2')
     ['1', '2']
 
     >>> qw(['a b','1 2',['m n','p q']])
     [['a', 'b'], ['1', '2'], [['m', 'n'], ['p', 'q']]]
 
     >>> qw(['a b','1 2',['m n','p q']],flat=1)
     ['a', 'b', '1', '2', 'm', 'n', 'p', 'q']
     """
 
     if isinstance(words, basestring):
         return [word.strip() for word in words.split(sep,maxsplit)
                 if word and not word.isspace() ]
     if flat:
         return flatten(map(qw,words,[1]*len(words)))
     return map(qw,words)
 
 
 def qwflat(words,sep=None,maxsplit=-1):
     """Calls qw(words) in flat mode. It's just a convenient shorthand."""
     return qw(words,1,sep,maxsplit)
 
 
 def qw_lol(indata):
     """qw_lol('a b') -> [['a','b']],
     otherwise it's just a call to qw().
 
     We need this to make sure the modules_some keys *always* end up as a
     list of lists."""
 
     if isinstance(indata, basestring):
         return [qw(indata)]
     else:
         return qw(indata)
 
 
 def grep(pat,list,case=1):
     """Simple minded grep-like function.
     grep(pat,list) returns occurrences of pat in list, None on failure.
 
     It only does simple string matching, with no support for regexps. Use the
     option case=0 for case-insensitive matching."""
 
     # This is pretty crude. At least it should implement copying only references
     # to the original data in case it's big. Now it copies the data for output.
     out=[]
     if case:
         for term in list:
             if term.find(pat)>-1: out.append(term)
     else:
         lpat=pat.lower()
         for term in list:
             if term.lower().find(lpat)>-1: out.append(term)
 
     if len(out): return out
     else: return None
 
 
 def dgrep(pat,*opts):
     """Return grep() on dir()+dir(__builtins__).
 
     A very common use of grep() when working interactively."""
 
     return grep(pat,dir(__main__)+dir(__main__.__builtins__),*opts)
 
 
 def idgrep(pat):
     """Case-insensitive dgrep()"""
 
     return dgrep(pat,0)
 
 
 def igrep(pat,list):
     """Synonym for case-insensitive grep."""
 
     return grep(pat,list,case=0)
 
 
 def indent(instr,nspaces=4, ntabs=0, flatten=False):
     """Indent a string a given number of spaces or tabstops.
 
     indent(str,nspaces=4,ntabs=0) -> indent str by ntabs+nspaces.
 
     Parameters
     ----------
 
     instr : basestring
         The string to be indented.
     nspaces : int (default: 4)
         The number of spaces to be indented.
     ntabs : int (default: 0)
         The number of tabs to be indented.
     flatten : bool (default: False)
         Whether to scrub existing indentation.  If True, all lines will be
         aligned to the same indentation.  If False, existing indentation will
         be strictly increased.
 
     Returns
     -------
 
     str|unicode : string indented by ntabs and nspaces.
 
     """
     if instr is None:
         return
     ind = '\t'*ntabs+' '*nspaces
     if flatten:
         pat = re.compile(r'^\s*', re.MULTILINE)
     else:
         pat = re.compile(r'^', re.MULTILINE)
     outstr = re.sub(pat, ind, instr)
     if outstr.endswith(os.linesep+ind):
         return outstr[:-len(ind)]
     else:
         return outstr
 
 def native_line_ends(filename,backup=1):
     """Convert (in-place) a file to line-ends native to the current OS.
 
     If the optional backup argument is given as false, no backup of the
     original file is left.  """
 
     backup_suffixes = {'posix':'~','dos':'.bak','nt':'.bak','mac':'.bak'}
 
     bak_filename = filename + backup_suffixes[os.name]
 
     original = open(filename).read()
     shutil.copy2(filename,bak_filename)
     try:
         new = open(filename,'wb')
         new.write(os.linesep.join(original.splitlines()))
         new.write(os.linesep) # ALWAYS put an eol at the end of the file
         new.close()
     except:
         os.rename(bak_filename,filename)
     if not backup:
         try:
             os.remove(bak_filename)
         except:
             pass
 
 
 def list_strings(arg):
     """Always return a list of strings, given a string or list of strings
     as input.
 
     :Examples:
 
         In [7]: list_strings('A single string')
         Out[7]: ['A single string']
 
         In [8]: list_strings(['A single string in a list'])
         Out[8]: ['A single string in a list']
 
         In [9]: list_strings(['A','list','of','strings'])
         Out[9]: ['A', 'list', 'of', 'strings']
     """
 
     if isinstance(arg,basestring): return [arg]
     else: return arg
 
 
 def marquee(txt='',width=78,mark='*'):
     """Return the input string centered in a 'marquee'.
 
     :Examples:
 
         In [16]: marquee('A test',40)
         Out[16]: '**************** A test ****************'
 
         In [17]: marquee('A test',40,'-')
         Out[17]: '---------------- A test ----------------'
 
         In [18]: marquee('A test',40,' ')
         Out[18]: '                 A test                 '
 
     """
     if not txt:
         return (mark*width)[:width]
     nmark = (width-len(txt)-2)//len(mark)//2
     if nmark < 0: nmark =0
     marks = mark*nmark
     return '%s %s %s' % (marks,txt,marks)
 
 
 ini_spaces_re = re.compile(r'^(\s+)')
 
 def num_ini_spaces(strng):
     """Return the number of initial spaces in a string"""
 
     ini_spaces = ini_spaces_re.match(strng)
     if ini_spaces:
         return ini_spaces.end()
     else:
         return 0
 
 
 def format_screen(strng):
     """Format a string for screen printing.
 
     This removes some latex-type format codes."""
     # Paragraph continue
     par_re = re.compile(r'\\$',re.MULTILINE)
     strng = par_re.sub('',strng)
     return strng
 
 
 def dedent(text):
     """Equivalent of textwrap.dedent that ignores unindented first line.
 
     This means it will still dedent strings like:
     '''foo
     is a bar
     '''
 
     For use in wrap_paragraphs.
     """
 
     if text.startswith('\n'):
         # text starts with blank line, don't ignore the first line
         return textwrap.dedent(text)
 
     # split first line
     splits = text.split('\n',1)
     if len(splits) == 1:
         # only one line
         return textwrap.dedent(text)
 
     first, rest = splits
     # dedent everything but the first line
     rest = textwrap.dedent(rest)
     return '\n'.join([first, rest])
 
 
 def wrap_paragraphs(text, ncols=80):
     """Wrap multiple paragraphs to fit a specified width.
 
     This is equivalent to textwrap.wrap, but with support for multiple
     paragraphs, as separated by empty lines.
 
     Returns
     -------
 
     list of complete paragraphs, wrapped to fill `ncols` columns.
     """
     paragraph_re = re.compile(r'\n(\s*\n)+', re.MULTILINE)
     text = dedent(text).strip()
     paragraphs = paragraph_re.split(text)[::2] # every other entry is space
     out_ps = []
     indent_re = re.compile(r'\n\s+', re.MULTILINE)
     for p in paragraphs:
         # presume indentation that survives dedent is meaningful formatting,
         # so don't fill unless text is flush.
         if indent_re.search(p) is None:
             # wrap paragraph
             p = textwrap.fill(p, ncols)
         out_ps.append(p)
     return out_ps
 
 
 def long_substr(data):
     """Return the longest common substring in a list of strings.
     
     Credit: http://stackoverflow.com/questions/2892931/longest-common-substring-from-more-than-two-strings-python
     """
     substr = ''
     if len(data) > 1 and len(data[0]) > 0:
         for i in range(len(data[0])):
             for j in range(len(data[0])-i+1):
                 if j > len(substr) and all(data[0][i:i+j] in x for x in data):
                     substr = data[0][i:i+j]
     elif len(data) == 1:
         substr = data[0]
     return substr
 
 
 def strip_email_quotes(text):
     """Strip leading email quotation characters ('>').
 
     Removes any combination of leading '>' interspersed with whitespace that
     appears *identically* in all lines of the input text.
 
     Parameters
     ----------
     text : str
 
     Examples
     --------
 
     Simple uses::
 
         In [2]: strip_email_quotes('> > text')
         Out[2]: 'text'
 
         In [3]: strip_email_quotes('> > text\\n> > more')
         Out[3]: 'text\\nmore'
 
     Note how only the common prefix that appears in all lines is stripped::
 
         In [4]: strip_email_quotes('> > text\\n> > more\\n> more...')
         Out[4]: '> text\\n> more\\nmore...'
 
     So if any line has no quote marks ('>') , then none are stripped from any
     of them ::
     
         In [5]: strip_email_quotes('> > text\\n> > more\\nlast different')
         Out[5]: '> > text\\n> > more\\nlast different'
     """
     lines = text.splitlines()
     matches = set()
     for line in lines:
         prefix = re.match(r'^(\s*>[ >]*)', line)
         if prefix:
             matches.add(prefix.group(1))
         else:
             break
     else:
         prefix = long_substr(list(matches))
         if prefix:
             strip = len(prefix)
             text = '\n'.join([ ln[strip:] for ln in lines])
     return text
 
 
 class EvalFormatter(Formatter):
     """A String Formatter that allows evaluation of simple expressions.
     
     Note that this version interprets a : as specifying a format string (as per
     standard string formatting), so if slicing is required, you must explicitly
     create a slice.
     
     This is to be used in templating cases, such as the parallel batch
     script templates, where simple arithmetic on arguments is useful.
 
     Examples
     --------
     
     In  [1]: f = EvalFormatter()
     In  [2]: f.format('{n//4}', n=8)
     Out [2]: '2'
     
     In  [3]: f.format("{greeting[slice(2,4)]}", greeting="Hello")
     Out [3]: 'll'
     """
     def get_field(self, name, args, kwargs):
         v = eval(name, kwargs)
         return v, name
 
 
 @skip_doctest_py3
 class FullEvalFormatter(Formatter):
     """A String Formatter that allows evaluation of simple expressions.
     
     Any time a format key is not found in the kwargs,
     it will be tried as an expression in the kwargs namespace.
     
     Note that this version allows slicing using [1:2], so you cannot specify
     a format string. Use :class:`EvalFormatter` to permit format strings.
     
     Examples
     --------
     
     In [1]: f = FullEvalFormatter()
     In [2]: f.format('{n//4}', n=8)
     Out[2]: u'2'
     
     In [3]: f.format('{list(range(5))[2:4]}')
     Out[3]: u'[2, 3]'
 
     In [4]: f.format('{3*2}')
     Out[4]: u'6'
     """
     # copied from Formatter._vformat with minor changes to allow eval
     # and replace the format_spec code with slicing
     def _vformat(self, format_string, args, kwargs, used_args, recursion_depth):
         if recursion_depth < 0:
             raise ValueError('Max string recursion exceeded')
         result = []
         for literal_text, field_name, format_spec, conversion in \
                 self.parse(format_string):
 
             # output the literal text
             if literal_text:
                 result.append(literal_text)
 
             # if there's a field, output it
             if field_name is not None:
                 # this is some markup, find the object and do
                 # the formatting
 
                 if format_spec:
                     # override format spec, to allow slicing:
                     field_name = ':'.join([field_name, format_spec])
 
                 # eval the contents of the field for the object
                 # to be formatted
                 obj = eval(field_name, kwargs)
 
                 # do any conversion on the resulting object
                 obj = self.convert_field(obj, conversion)
 
                 # format the object and append to the result
                 result.append(self.format_field(obj, ''))
 
         return u''.join(py3compat.cast_unicode(s) for s in result)
 
 
 @skip_doctest_py3
 class DollarFormatter(FullEvalFormatter):
     """Formatter allowing Itpl style $foo replacement, for names and attribute
     access only. Standard {foo} replacement also works, and allows full
     evaluation of its arguments.
 
     Examples
     --------
     In [1]: f = DollarFormatter()
     In [2]: f.format('{n//4}', n=8)
     Out[2]: u'2'
     
     In [3]: f.format('23 * 76 is $result', result=23*76)
     Out[3]: u'23 * 76 is 1748'
     
     In [4]: f.format('$a or {b}', a=1, b=2)
     Out[4]: u'1 or 2'
     """
     _dollar_pattern = re.compile("(.*?)\$(\$?[\w\.]+)")
     def parse(self, fmt_string):
         for literal_txt, field_name, format_spec, conversion \
                     in Formatter.parse(self, fmt_string):
             
             # Find $foo patterns in the literal text.
             continue_from = 0
             txt = ""
             for m in self._dollar_pattern.finditer(literal_txt):
                 new_txt, new_field = m.group(1,2)
                 # $$foo --> $foo
                 if new_field.startswith("$"):
                     txt += new_txt + new_field
                 else:
                     yield (txt + new_txt, new_field, "", None)
                     txt = ""
                 continue_from = m.end()
             
             # Re-yield the {foo} style pattern
             yield (txt + literal_txt[continue_from:], field_name, format_spec, conversion)
 
 #-----------------------------------------------------------------------------
 # Utils to columnize a list of string
 #-----------------------------------------------------------------------------
 
 def _chunks(l, n):
     """Yield successive n-sized chunks from l."""
     for i in xrange(0, len(l), n):
         yield l[i:i+n]
 
 
 def _find_optimal(rlist , separator_size=2 , displaywidth=80):
     """Calculate optimal info to columnize a list of string"""
     for nrow in range(1, len(rlist)+1) :
         chk = map(max,_chunks(rlist, nrow))
         sumlength = sum(chk)
         ncols = len(chk)
         if sumlength+separator_size*(ncols-1) <= displaywidth :
             break;
     return {'columns_numbers' : ncols,
             'optimal_separator_width':(displaywidth - sumlength)/(ncols-1) if (ncols -1) else 0,
             'rows_numbers' : nrow,
             'columns_width' : chk
            }
 
 
 def _get_or_default(mylist, i, default=None):
     """return list item number, or default if don't exist"""
     if i >= len(mylist):
         return default
     else :
         return mylist[i]
 
 
 @skip_doctest
 def compute_item_matrix(items, empty=None, *args, **kwargs) :
     """Returns a nested list, and info to columnize items
 
     Parameters :
     ------------
 
     items :
         list of strings to columize
     empty : (default None)
         default value to fill list if needed
     separator_size : int (default=2)
         How much caracters will be used as a separation between each columns.
     displaywidth : int (default=80)
         The width of the area onto wich the columns should enter
 
     Returns :
     ---------
 
     Returns a tuple of (strings_matrix, dict_info)
 
     strings_matrix :
 
         nested list of string, the outer most list contains as many list as
         rows, the innermost lists have each as many element as colums. If the
         total number of elements in `items` does not equal the product of
         rows*columns, the last element of some lists are filled with `None`.
 
     dict_info :
         some info to make columnize easier:
 
         columns_numbers : number of columns
         rows_numbers    : number of rows
         columns_width   : list of with of each columns
         optimal_separator_width : best separator width between columns
 
     Exemple :
     ---------
 
     In [1]: l = ['aaa','b','cc','d','eeeee','f','g','h','i','j','k','l']
        ...: compute_item_matrix(l,displaywidth=12)
     Out[1]:
         ([['aaa', 'f', 'k'],
         ['b', 'g', 'l'],
         ['cc', 'h', None],
         ['d', 'i', None],
         ['eeeee', 'j', None]],
         {'columns_numbers': 3,
         'columns_width': [5, 1, 1],
         'optimal_separator_width': 2,
         'rows_numbers': 5})
 
     """
     info = _find_optimal(map(len, items), *args, **kwargs)
     nrow, ncol = info['rows_numbers'], info['columns_numbers']
     return ([[ _get_or_default(items, c*nrow+i, default=empty) for c in range(ncol) ] for i in range(nrow) ], info)
 
 
 def columnize(items, separator='  ', displaywidth=80):
     """ Transform a list of strings into a single string with columns.
 
     Parameters
     ----------
     items : sequence of strings
         The strings to process.
 
     separator : str, optional [default is two spaces]
         The string that separates columns.
 
     displaywidth : int, optional [default is 80]
         Width of the display in number of characters.
 
     Returns
     -------
     The formatted string.
     """
     if not items :
         return '\n'
     matrix, info = compute_item_matrix(items, separator_size=len(separator), displaywidth=displaywidth)
     fmatrix = [filter(None, x) for x in matrix]
     sjoin = lambda x : separator.join([ y.ljust(w, ' ') for y, w in zip(x, info['columns_width'])])
     return '\n'.join(map(sjoin, fmatrix))+'\n'

IPython/utils/traitlets.py

@@ -1,1434 +1,1439 b''
 # encoding: utf-8
 """
 A lightweight Traits like module.
 
 This is designed to provide a lightweight, simple, pure Python version of
 many of the capabilities of enthought.traits.  This includes:
 
 * Validation
 * Type specification with defaults
 * Static and dynamic notification
 * Basic predefined types
 * An API that is similar to enthought.traits
 
 We don't support:
 
 * Delegation
 * Automatic GUI generation
 * A full set of trait types.  Most importantly, we don't provide container
   traits (list, dict, tuple) that can trigger notifications if their
   contents change.
 * API compatibility with enthought.traits
 
 There are also some important difference in our design:
 
 * enthought.traits does not validate default values.  We do.
 
 We choose to create this module because we need these capabilities, but
 we need them to be pure Python so they work in all Python implementations,
 including Jython and IronPython.
 
+Inheritance diagram:
+
+.. inheritance-diagram:: IPython.utils.traitlets
+   :parts: 3
+
 Authors:
 
 * Brian Granger
 * Enthought, Inc.  Some of the code in this file comes from enthought.traits
   and is licensed under the BSD license.  Also, many of the ideas also come
   from enthought.traits even though our implementation is very different.
 """
 
 #-----------------------------------------------------------------------------
 #  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 inspect
 import re
 import sys
 import types
 from types import FunctionType
 try:
     from types import ClassType, InstanceType
     ClassTypes = (ClassType, type)
 except:
     ClassTypes = (type,)
 
 from .importstring import import_item
 from IPython.utils import py3compat
 
 SequenceTypes = (list, tuple, set, frozenset)
 
 #-----------------------------------------------------------------------------
 # Basic classes
 #-----------------------------------------------------------------------------
 
 
 class NoDefaultSpecified ( object ): pass
 NoDefaultSpecified = NoDefaultSpecified()
 
 
 class Undefined ( object ): pass
 Undefined = Undefined()
 
 class TraitError(Exception):
     pass
 
 #-----------------------------------------------------------------------------
 # Utilities
 #-----------------------------------------------------------------------------
 
 
 def class_of ( object ):
     """ Returns a string containing the class name of an object with the
     correct indefinite article ('a' or 'an') preceding it (e.g., 'an Image',
     'a PlotValue').
     """
     if isinstance( object, basestring ):
         return add_article( object )
 
     return add_article( object.__class__.__name__ )
 
 
 def add_article ( name ):
     """ Returns a string containing the correct indefinite article ('a' or 'an')
     prefixed to the specified string.
     """
     if name[:1].lower() in 'aeiou':
        return 'an ' + name
 
     return 'a ' + name
 
 
 def repr_type(obj):
     """ Return a string representation of a value and its type for readable
     error messages.
     """
     the_type = type(obj)
     if (not py3compat.PY3) and the_type is InstanceType:
         # Old-style class.
         the_type = obj.__class__
     msg = '%r %r' % (obj, the_type)
     return msg
 
 
 def is_trait(t):
     """ Returns whether the given value is an instance or subclass of TraitType.
     """
     return (isinstance(t, TraitType) or
             (isinstance(t, type) and issubclass(t, TraitType)))
 
 
 def parse_notifier_name(name):
     """Convert the name argument to a list of names.
 
     Examples
     --------
 
     >>> parse_notifier_name('a')
     ['a']
     >>> parse_notifier_name(['a','b'])
     ['a', 'b']
     >>> parse_notifier_name(None)
     ['anytrait']
     """
     if isinstance(name, str):
         return [name]
     elif name is None:
         return ['anytrait']
     elif isinstance(name, (list, tuple)):
         for n in name:
             assert isinstance(n, str), "names must be strings"
         return name
 
 
 class _SimpleTest:
     def __init__ ( self, value ): self.value = value
     def __call__ ( self, test  ):
         return test == self.value
     def __repr__(self):
         return "<SimpleTest(%r)" % self.value
     def __str__(self):
         return self.__repr__()
 
 
 def getmembers(object, predicate=None):
     """A safe version of inspect.getmembers that handles missing attributes.
 
     This is useful when there are descriptor based attributes that for
     some reason raise AttributeError even though they exist.  This happens
     in zope.inteface with the __provides__ attribute.
     """
     results = []
     for key in dir(object):
         try:
             value = getattr(object, key)
         except AttributeError:
             pass
         else:
             if not predicate or predicate(value):
                 results.append((key, value))
     results.sort()
     return results
 
 
 #-----------------------------------------------------------------------------
 # Base TraitType for all traits
 #-----------------------------------------------------------------------------
 
 
 class TraitType(object):
     """A base class for all trait descriptors.
 
     Notes
     -----
     Our implementation of traits is based on Python's descriptor
     prototol.  This class is the base class for all such descriptors.  The
     only magic we use is a custom metaclass for the main :class:`HasTraits`
     class that does the following:
 
     1. Sets the :attr:`name` attribute of every :class:`TraitType`
        instance in the class dict to the name of the attribute.
     2. Sets the :attr:`this_class` attribute of every :class:`TraitType`
        instance in the class dict to the *class* that declared the trait.
        This is used by the :class:`This` trait to allow subclasses to
        accept superclasses for :class:`This` values.
     """
 
 
     metadata = {}
     default_value = Undefined
     info_text = 'any value'
 
     def __init__(self, default_value=NoDefaultSpecified, **metadata):
         """Create a TraitType.
         """
         if default_value is not NoDefaultSpecified:
             self.default_value = default_value
 
         if len(metadata) > 0:
             if len(self.metadata) > 0:
                 self._metadata = self.metadata.copy()
                 self._metadata.update(metadata)
             else:
                 self._metadata = metadata
         else:
             self._metadata = self.metadata
 
         self.init()
 
     def init(self):
         pass
 
     def get_default_value(self):
         """Create a new instance of the default value."""
         return self.default_value
 
     def instance_init(self, obj):
         """This is called by :meth:`HasTraits.__new__` to finish init'ing.
 
         Some stages of initialization must be delayed until the parent
         :class:`HasTraits` instance has been created.  This method is
         called in :meth:`HasTraits.__new__` after the instance has been
         created.
 
         This method trigger the creation and validation of default values
         and also things like the resolution of str given class names in
         :class:`Type` and :class`Instance`.
 
         Parameters
         ----------
         obj : :class:`HasTraits` instance
             The parent :class:`HasTraits` instance that has just been
             created.
         """
         self.set_default_value(obj)
 
     def set_default_value(self, obj):
         """Set the default value on a per instance basis.
 
         This method is called by :meth:`instance_init` to create and
         validate the default value.  The creation and validation of
         default values must be delayed until the parent :class:`HasTraits`
         class has been instantiated.
         """
         # Check for a deferred initializer defined in the same class as the
         # trait declaration or above.
         mro = type(obj).mro()
         meth_name = '_%s_default' % self.name
         for cls in mro[:mro.index(self.this_class)+1]:
             if meth_name in cls.__dict__:
                 break
         else:
             # We didn't find one. Do static initialization.
             dv = self.get_default_value()
             newdv = self._validate(obj, dv)
             obj._trait_values[self.name] = newdv
             return
         # Complete the dynamic initialization.
         obj._trait_dyn_inits[self.name] = cls.__dict__[meth_name]
 
     def __get__(self, obj, cls=None):
         """Get the value of the trait by self.name for the instance.
 
         Default values are instantiated when :meth:`HasTraits.__new__`
         is called.  Thus by the time this method gets called either the
         default value or a user defined value (they called :meth:`__set__`)
         is in the :class:`HasTraits` instance.
         """
         if obj is None:
             return self
         else:
             try:
                 value = obj._trait_values[self.name]
             except KeyError:
                 # Check for a dynamic initializer.
                 if self.name in obj._trait_dyn_inits:
                     value = obj._trait_dyn_inits[self.name](obj)
                     # FIXME: Do we really validate here?
                     value = self._validate(obj, value)
                     obj._trait_values[self.name] = value
                     return value
                 else:
                     raise TraitError('Unexpected error in TraitType: '
                         'both default value and dynamic initializer are '
                         'absent.')
             except Exception:
                 # HasTraits should call set_default_value to populate
                 # this.  So this should never be reached.
                 raise TraitError('Unexpected error in TraitType: '
                                     'default value not set properly')
             else:
                 return value
 
     def __set__(self, obj, value):
         new_value = self._validate(obj, value)
         old_value = self.__get__(obj)
         obj._trait_values[self.name] = new_value
         if old_value != new_value:
             obj._notify_trait(self.name, old_value, new_value)
 
     def _validate(self, obj, value):
         if hasattr(self, 'validate'):
             return self.validate(obj, value)
         elif hasattr(self, 'is_valid_for'):
             valid = self.is_valid_for(value)
             if valid:
                 return value
             else:
                 raise TraitError('invalid value for type: %r' % value)
         elif hasattr(self, 'value_for'):
             return self.value_for(value)
         else:
             return value
 
     def info(self):
         return self.info_text
 
     def error(self, obj, value):
         if obj is not None:
             e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \
                 % (self.name, class_of(obj),
                    self.info(), repr_type(value))
         else:
             e = "The '%s' trait must be %s, but a value of %r was specified." \
                 % (self.name, self.info(), repr_type(value))
         raise TraitError(e)
 
     def get_metadata(self, key):
         return getattr(self, '_metadata', {}).get(key, None)
 
     def set_metadata(self, key, value):
         getattr(self, '_metadata', {})[key] = value
 
 
 #-----------------------------------------------------------------------------
 # The HasTraits implementation
 #-----------------------------------------------------------------------------
 
 
 class MetaHasTraits(type):
     """A metaclass for HasTraits.
 
     This metaclass makes sure that any TraitType class attributes are
     instantiated and sets their name attribute.
     """
 
     def __new__(mcls, name, bases, classdict):
         """Create the HasTraits class.
 
         This instantiates all TraitTypes in the class dict and sets their
         :attr:`name` attribute.
         """
         # print "MetaHasTraitlets (mcls, name): ", mcls, name
         # print "MetaHasTraitlets (bases): ", bases
         # print "MetaHasTraitlets (classdict): ", classdict
         for k,v in classdict.iteritems():
             if isinstance(v, TraitType):
                 v.name = k
             elif inspect.isclass(v):
                 if issubclass(v, TraitType):
                     vinst = v()
                     vinst.name = k
                     classdict[k] = vinst
         return super(MetaHasTraits, mcls).__new__(mcls, name, bases, classdict)
 
     def __init__(cls, name, bases, classdict):
         """Finish initializing the HasTraits class.
 
         This sets the :attr:`this_class` attribute of each TraitType in the
         class dict to the newly created class ``cls``.
         """
         for k, v in classdict.iteritems():
             if isinstance(v, TraitType):
                 v.this_class = cls
         super(MetaHasTraits, cls).__init__(name, bases, classdict)
 
 class HasTraits(object):
 
     __metaclass__ = MetaHasTraits
 
     def __new__(cls, **kw):
         # This is needed because in Python 2.6 object.__new__ only accepts
         # the cls argument.
         new_meth = super(HasTraits, cls).__new__
         if new_meth is object.__new__:
             inst = new_meth(cls)
         else:
             inst = new_meth(cls, **kw)
         inst._trait_values = {}
         inst._trait_notifiers = {}
         inst._trait_dyn_inits = {}
         # Here we tell all the TraitType instances to set their default
         # values on the instance.
         for key in dir(cls):
             # Some descriptors raise AttributeError like zope.interface's
             # __provides__ attributes even though they exist.  This causes
             # AttributeErrors even though they are listed in dir(cls).
             try:
                 value = getattr(cls, key)
             except AttributeError:
                 pass
             else:
                 if isinstance(value, TraitType):
                     value.instance_init(inst)
 
         return inst
 
     def __init__(self, **kw):
         # Allow trait values to be set using keyword arguments.
         # We need to use setattr for this to trigger validation and
         # notifications.
         for key, value in kw.iteritems():
             setattr(self, key, value)
 
     def _notify_trait(self, name, old_value, new_value):
 
         # First dynamic ones
         callables = self._trait_notifiers.get(name,[])
         more_callables = self._trait_notifiers.get('anytrait',[])
         callables.extend(more_callables)
 
         # Now static ones
         try:
             cb = getattr(self, '_%s_changed' % name)
         except:
             pass
         else:
             callables.append(cb)
 
         # Call them all now
         for c in callables:
             # Traits catches and logs errors here.  I allow them to raise
             if callable(c):
                 argspec = inspect.getargspec(c)
                 nargs = len(argspec[0])
                 # Bound methods have an additional 'self' argument
                 # I don't know how to treat unbound methods, but they
                 # can't really be used for callbacks.
                 if isinstance(c, types.MethodType):
                     offset = -1
                 else:
                     offset = 0
                 if nargs + offset == 0:
                     c()
                 elif nargs + offset == 1:
                     c(name)
                 elif nargs + offset == 2:
                     c(name, new_value)
                 elif nargs + offset == 3:
                     c(name, old_value, new_value)
                 else:
                     raise TraitError('a trait changed callback '
                                         'must have 0-3 arguments.')
             else:
                 raise TraitError('a trait changed callback '
                                     'must be callable.')
 
 
     def _add_notifiers(self, handler, name):
         if name not in self._trait_notifiers:
             nlist = []
             self._trait_notifiers[name] = nlist
         else:
             nlist = self._trait_notifiers[name]
         if handler not in nlist:
             nlist.append(handler)
 
     def _remove_notifiers(self, handler, name):
         if name in self._trait_notifiers:
             nlist = self._trait_notifiers[name]
             try:
                 index = nlist.index(handler)
             except ValueError:
                 pass
             else:
                 del nlist[index]
 
     def on_trait_change(self, handler, name=None, remove=False):
         """Setup a handler to be called when a trait changes.
 
         This is used to setup dynamic notifications of trait changes.
 
         Static handlers can be created by creating methods on a HasTraits
         subclass with the naming convention '_[traitname]_changed'.  Thus,
         to create static handler for the trait 'a', create the method
         _a_changed(self, name, old, new) (fewer arguments can be used, see
         below).
 
         Parameters
         ----------
         handler : callable
             A callable that is called when a trait changes.  Its
             signature can be handler(), handler(name), handler(name, new)
             or handler(name, old, new).
         name : list, str, None
             If None, the handler will apply to all traits.  If a list
             of str, handler will apply to all names in the list.  If a
             str, the handler will apply just to that name.
         remove : bool
             If False (the default), then install the handler.  If True
             then unintall it.
         """
         if remove:
             names = parse_notifier_name(name)
             for n in names:
                 self._remove_notifiers(handler, n)
         else:
             names = parse_notifier_name(name)
             for n in names:
                 self._add_notifiers(handler, n)
 
     @classmethod
     def class_trait_names(cls, **metadata):
         """Get a list of all the names of this classes traits.
 
         This method is just like the :meth:`trait_names` method, but is unbound.
         """
         return cls.class_traits(**metadata).keys()
 
     @classmethod
     def class_traits(cls, **metadata):
         """Get a list of all the traits of this class.
 
         This method is just like the :meth:`traits` method, but is unbound.
 
         The TraitTypes returned don't know anything about the values
         that the various HasTrait's instances are holding.
 
         This follows the same algorithm as traits does and does not allow
         for any simple way of specifying merely that a metadata name
         exists, but has any value.  This is because get_metadata returns
         None if a metadata key doesn't exist.
         """
         traits = dict([memb for memb in getmembers(cls) if \
                      isinstance(memb[1], TraitType)])
 
         if len(metadata) == 0:
             return traits
 
         for meta_name, meta_eval in metadata.items():
             if type(meta_eval) is not FunctionType:
                 metadata[meta_name] = _SimpleTest(meta_eval)
 
         result = {}
         for name, trait in traits.items():
             for meta_name, meta_eval in metadata.items():
                 if not meta_eval(trait.get_metadata(meta_name)):
                     break
             else:
                 result[name] = trait
 
         return result
 
     def trait_names(self, **metadata):
         """Get a list of all the names of this classes traits."""
         return self.traits(**metadata).keys()
 
     def traits(self, **metadata):
         """Get a list of all the traits of this class.
 
         The TraitTypes returned don't know anything about the values
         that the various HasTrait's instances are holding.
 
         This follows the same algorithm as traits does and does not allow
         for any simple way of specifying merely that a metadata name
         exists, but has any value.  This is because get_metadata returns
         None if a metadata key doesn't exist.
         """
         traits = dict([memb for memb in getmembers(self.__class__) if \
                      isinstance(memb[1], TraitType)])
 
         if len(metadata) == 0:
             return traits
 
         for meta_name, meta_eval in metadata.items():
             if type(meta_eval) is not FunctionType:
                 metadata[meta_name] = _SimpleTest(meta_eval)
 
         result = {}
         for name, trait in traits.items():
             for meta_name, meta_eval in metadata.items():
                 if not meta_eval(trait.get_metadata(meta_name)):
                     break
             else:
                 result[name] = trait
 
         return result
 
     def trait_metadata(self, traitname, key):
         """Get metadata values for trait by key."""
         try:
             trait = getattr(self.__class__, traitname)
         except AttributeError:
             raise TraitError("Class %s does not have a trait named %s" %
                                 (self.__class__.__name__, traitname))
         else:
             return trait.get_metadata(key)
 
 #-----------------------------------------------------------------------------
 # Actual TraitTypes implementations/subclasses
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # TraitTypes subclasses for handling classes and instances of classes
 #-----------------------------------------------------------------------------
 
 
 class ClassBasedTraitType(TraitType):
     """A trait with error reporting for Type, Instance and This."""
 
     def error(self, obj, value):
         kind = type(value)
         if (not py3compat.PY3) and kind is InstanceType:
             msg = 'class %s' % value.__class__.__name__
         else:
             msg = '%s (i.e. %s)' % ( str( kind )[1:-1], repr( value ) )
 
         if obj is not None:
             e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \
                 % (self.name, class_of(obj),
                    self.info(), msg)
         else:
             e = "The '%s' trait must be %s, but a value of %r was specified." \
                 % (self.name, self.info(), msg)
 
         raise TraitError(e)
 
 
 class Type(ClassBasedTraitType):
     """A trait whose value must be a subclass of a specified class."""
 
     def __init__ (self, default_value=None, klass=None, allow_none=True, **metadata ):
         """Construct a Type trait
 
         A Type trait specifies that its values must be subclasses of
         a particular class.
 
         If only ``default_value`` is given, it is used for the ``klass`` as
         well.
 
         Parameters
         ----------
         default_value : class, str or None
             The default value must be a subclass of klass.  If an str,
             the str must be a fully specified class name, like 'foo.bar.Bah'.
             The string is resolved into real class, when the parent
             :class:`HasTraits` class is instantiated.
         klass : class, str, None
             Values of this trait must be a subclass of klass.  The klass
             may be specified in a string like: 'foo.bar.MyClass'.
             The string is resolved into real class, when the parent
             :class:`HasTraits` class is instantiated.
         allow_none : boolean
             Indicates whether None is allowed as an assignable value. Even if
             ``False``, the default value may be ``None``.
         """
         if default_value is None:
             if klass is None:
                 klass = object
         elif klass is None:
             klass = default_value
 
         if not (inspect.isclass(klass) or isinstance(klass, basestring)):
             raise TraitError("A Type trait must specify a class.")
 
         self.klass       = klass
         self._allow_none = allow_none
 
         super(Type, self).__init__(default_value, **metadata)
 
     def validate(self, obj, value):
         """Validates that the value is a valid object instance."""
         try:
             if issubclass(value, self.klass):
                 return value
         except:
             if (value is None) and (self._allow_none):
                 return value
 
         self.error(obj, value)
 
     def info(self):
         """ Returns a description of the trait."""
         if isinstance(self.klass, basestring):
             klass = self.klass
         else:
             klass = self.klass.__name__
         result = 'a subclass of ' + klass
         if self._allow_none:
             return result + ' or None'
         return result
 
     def instance_init(self, obj):
         self._resolve_classes()
         super(Type, self).instance_init(obj)
 
     def _resolve_classes(self):
         if isinstance(self.klass, basestring):
             self.klass = import_item(self.klass)
         if isinstance(self.default_value, basestring):
             self.default_value = import_item(self.default_value)
 
     def get_default_value(self):
         return self.default_value
 
 
 class DefaultValueGenerator(object):
     """A class for generating new default value instances."""
 
     def __init__(self, *args, **kw):
         self.args = args
         self.kw = kw
 
     def generate(self, klass):
         return klass(*self.args, **self.kw)
 
 
 class Instance(ClassBasedTraitType):
     """A trait whose value must be an instance of a specified class.
 
     The value can also be an instance of a subclass of the specified class.
     """
 
     def __init__(self, klass=None, args=None, kw=None,
                  allow_none=True, **metadata ):
         """Construct an Instance trait.
 
         This trait allows values that are instances of a particular
         class or its sublclasses.  Our implementation is quite different
         from that of enthough.traits as we don't allow instances to be used
         for klass and we handle the ``args`` and ``kw`` arguments differently.
 
         Parameters
         ----------
         klass : class, str
             The class that forms the basis for the trait.  Class names
             can also be specified as strings, like 'foo.bar.Bar'.
         args : tuple
             Positional arguments for generating the default value.
         kw : dict
             Keyword arguments for generating the default value.
         allow_none : bool
             Indicates whether None is allowed as a value.
 
         Default Value
         -------------
         If both ``args`` and ``kw`` are None, then the default value is None.
         If ``args`` is a tuple and ``kw`` is a dict, then the default is
         created as ``klass(*args, **kw)``.  If either ``args`` or ``kw`` is
         not (but not both), None is replace by ``()`` or ``{}``.
         """
 
         self._allow_none = allow_none
 
         if (klass is None) or (not (inspect.isclass(klass) or isinstance(klass, basestring))):
             raise TraitError('The klass argument must be a class'
                                 ' you gave: %r' % klass)
         self.klass = klass
 
         # self.klass is a class, so handle default_value
         if args is None and kw is None:
             default_value = None
         else:
             if args is None:
                 # kw is not None
                 args = ()
             elif kw is None:
                 # args is not None
                 kw = {}
 
             if not isinstance(kw, dict):
                 raise TraitError("The 'kw' argument must be a dict or None.")
             if not isinstance(args, tuple):
                 raise TraitError("The 'args' argument must be a tuple or None.")
 
             default_value = DefaultValueGenerator(*args, **kw)
 
         super(Instance, self).__init__(default_value, **metadata)
 
     def validate(self, obj, value):
         if value is None:
             if self._allow_none:
                 return value
             self.error(obj, value)
 
         if isinstance(value, self.klass):
             return value
         else:
             self.error(obj, value)
 
     def info(self):
         if isinstance(self.klass, basestring):
             klass = self.klass
         else:
             klass = self.klass.__name__
         result = class_of(klass)
         if self._allow_none:
             return result + ' or None'
 
         return result
 
     def instance_init(self, obj):
         self._resolve_classes()
         super(Instance, self).instance_init(obj)
 
     def _resolve_classes(self):
         if isinstance(self.klass, basestring):
             self.klass = import_item(self.klass)
 
     def get_default_value(self):
         """Instantiate a default value instance.
 
         This is called when the containing HasTraits classes'
         :meth:`__new__` method is called to ensure that a unique instance
         is created for each HasTraits instance.
         """
         dv  = self.default_value
         if isinstance(dv, DefaultValueGenerator):
             return dv.generate(self.klass)
         else:
             return dv
 
 
 class This(ClassBasedTraitType):
     """A trait for instances of the class containing this trait.
 
     Because how how and when class bodies are executed, the ``This``
     trait can only have a default value of None.  This, and because we
     always validate default values, ``allow_none`` is *always* true.
     """
 
     info_text = 'an instance of the same type as the receiver or None'
 
     def __init__(self, **metadata):
         super(This, self).__init__(None, **metadata)
 
     def validate(self, obj, value):
         # What if value is a superclass of obj.__class__?  This is
         # complicated if it was the superclass that defined the This
         # trait.
         if isinstance(value, self.this_class) or (value is None):
             return value
         else:
             self.error(obj, value)
 
 
 #-----------------------------------------------------------------------------
 # Basic TraitTypes implementations/subclasses
 #-----------------------------------------------------------------------------
 
 
 class Any(TraitType):
     default_value = None
     info_text = 'any value'
 
 
 class Int(TraitType):
     """An int trait."""
 
     default_value = 0
     info_text = 'an int'
 
     def validate(self, obj, value):
         if isinstance(value, int):
             return value
         self.error(obj, value)
 
 class CInt(Int):
     """A casting version of the int trait."""
 
     def validate(self, obj, value):
         try:
             return int(value)
         except:
             self.error(obj, value)
 
 if py3compat.PY3:
     Long, CLong = Int, CInt
     Integer = Int
 else:
     class Long(TraitType):
         """A long integer trait."""
 
         default_value = 0L
         info_text = 'a long'
 
         def validate(self, obj, value):
             if isinstance(value, long):
                 return value
             if isinstance(value, int):
                 return long(value)
             self.error(obj, value)
 
 
     class CLong(Long):
         """A casting version of the long integer trait."""
 
         def validate(self, obj, value):
             try:
                 return long(value)
             except:
                 self.error(obj, value)
 
     class Integer(TraitType):
         """An integer trait.
 
         Longs that are unnecessary (<= sys.maxint) are cast to ints."""
 
         default_value = 0
         info_text = 'an integer'
 
         def validate(self, obj, value):
             if isinstance(value, int):
                 return value
             if isinstance(value, long):
                 # downcast longs that fit in int:
                 # note that int(n > sys.maxint) returns a long, so
                 # we don't need a condition on this cast
                 return int(value)
             if sys.platform == "cli":
                 from System import Int64
                 if isinstance(value, Int64):
                     return int(value)
             self.error(obj, value)
 
 
 class Float(TraitType):
     """A float trait."""
 
     default_value = 0.0
     info_text = 'a float'
 
     def validate(self, obj, value):
         if isinstance(value, float):
             return value
         if isinstance(value, int):
             return float(value)
         self.error(obj, value)
 
 
 class CFloat(Float):
     """A casting version of the float trait."""
 
     def validate(self, obj, value):
         try:
             return float(value)
         except:
             self.error(obj, value)
 
 class Complex(TraitType):
     """A trait for complex numbers."""
 
     default_value = 0.0 + 0.0j
     info_text = 'a complex number'
 
     def validate(self, obj, value):
         if isinstance(value, complex):
             return value
         if isinstance(value, (float, int)):
             return complex(value)
         self.error(obj, value)
 
 
 class CComplex(Complex):
     """A casting version of the complex number trait."""
 
     def validate (self, obj, value):
         try:
             return complex(value)
         except:
             self.error(obj, value)
 
 # We should always be explicit about whether we're using bytes or unicode, both
 # for Python 3 conversion and for reliable unicode behaviour on Python 2. So
 # we don't have a Str type.
 class Bytes(TraitType):
     """A trait for byte strings."""
 
     default_value = b''
     info_text = 'a string'
 
     def validate(self, obj, value):
         if isinstance(value, bytes):
             return value
         self.error(obj, value)
 
 
 class CBytes(Bytes):
     """A casting version of the byte string trait."""
 
     def validate(self, obj, value):
         try:
             return bytes(value)
         except:
             self.error(obj, value)
 
 
 class Unicode(TraitType):
     """A trait for unicode strings."""
 
     default_value = u''
     info_text = 'a unicode string'
 
     def validate(self, obj, value):
         if isinstance(value, unicode):
             return value
         if isinstance(value, bytes):
             return unicode(value)
         self.error(obj, value)
 
 
 class CUnicode(Unicode):
     """A casting version of the unicode trait."""
 
     def validate(self, obj, value):
         try:
             return unicode(value)
         except:
             self.error(obj, value)
 
 
 class ObjectName(TraitType):
     """A string holding a valid object name in this version of Python.
 
     This does not check that the name exists in any scope."""
     info_text = "a valid object identifier in Python"
 
     if py3compat.PY3:
         # Python 3:
         coerce_str = staticmethod(lambda _,s: s)
 
     else:
         # Python 2:
         def coerce_str(self, obj, value):
             "In Python 2, coerce ascii-only unicode to str"
             if isinstance(value, unicode):
                 try:
                     return str(value)
                 except UnicodeEncodeError:
                     self.error(obj, value)
             return value
 
     def validate(self, obj, value):
         value = self.coerce_str(obj, value)
 
         if isinstance(value, str) and py3compat.isidentifier(value):
             return value
         self.error(obj, value)
 
 class DottedObjectName(ObjectName):
     """A string holding a valid dotted object name in Python, such as A.b3._c"""
     def validate(self, obj, value):
         value = self.coerce_str(obj, value)
 
         if isinstance(value, str) and py3compat.isidentifier(value, dotted=True):
             return value
         self.error(obj, value)
 
 
 class Bool(TraitType):
     """A boolean (True, False) trait."""
 
     default_value = False
     info_text = 'a boolean'
 
     def validate(self, obj, value):
         if isinstance(value, bool):
             return value
         self.error(obj, value)
 
 
 class CBool(Bool):
     """A casting version of the boolean trait."""
 
     def validate(self, obj, value):
         try:
             return bool(value)
         except:
             self.error(obj, value)
 
 
 class Enum(TraitType):
     """An enum that whose value must be in a given sequence."""
 
     def __init__(self, values, default_value=None, allow_none=True, **metadata):
         self.values = values
         self._allow_none = allow_none
         super(Enum, self).__init__(default_value, **metadata)
 
     def validate(self, obj, value):
         if value is None:
             if self._allow_none:
                 return value
 
         if value in self.values:
                 return value
         self.error(obj, value)
 
     def info(self):
         """ Returns a description of the trait."""
         result = 'any of ' + repr(self.values)
         if self._allow_none:
             return result + ' or None'
         return result
 
 class CaselessStrEnum(Enum):
     """An enum of strings that are caseless in validate."""
 
     def validate(self, obj, value):
         if value is None:
             if self._allow_none:
                 return value
 
         if not isinstance(value, basestring):
             self.error(obj, value)
 
         for v in self.values:
             if v.lower() == value.lower():
                 return v
         self.error(obj, value)
 
 class Container(Instance):
     """An instance of a container (list, set, etc.)
 
     To be subclassed by overriding klass.
     """
     klass = None
     _valid_defaults = SequenceTypes
     _trait = None
 
     def __init__(self, trait=None, default_value=None, allow_none=True,
                 **metadata):
         """Create a container trait type from a list, set, or tuple.
 
         The default value is created by doing ``List(default_value)``,
         which creates a copy of the ``default_value``.
 
         ``trait`` can be specified, which restricts the type of elements
         in the container to that TraitType.
 
         If only one arg is given and it is not a Trait, it is taken as
         ``default_value``:
 
         ``c = List([1,2,3])``
 
         Parameters
         ----------
 
         trait : TraitType [ optional ]
             the type for restricting the contents of the Container.  If unspecified,
             types are not checked.
 
         default_value : SequenceType [ optional ]
             The default value for the Trait.  Must be list/tuple/set, and
             will be cast to the container type.
 
         allow_none : Bool [ default True ]
             Whether to allow the value to be None
 
         **metadata : any
             further keys for extensions to the Trait (e.g. config)
 
         """
         # allow List([values]):
         if default_value is None and not is_trait(trait):
             default_value = trait
             trait = None
 
         if default_value is None:
             args = ()
         elif isinstance(default_value, self._valid_defaults):
             args = (default_value,)
         else:
             raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value))
 
         if is_trait(trait):
             self._trait = trait() if isinstance(trait, type) else trait
             self._trait.name = 'element'
         elif trait is not None:
             raise TypeError("`trait` must be a Trait or None, got %s"%repr_type(trait))
 
         super(Container,self).__init__(klass=self.klass, args=args,
                                   allow_none=allow_none, **metadata)
 
     def element_error(self, obj, element, validator):
         e = "Element of the '%s' trait of %s instance must be %s, but a value of %s was specified." \
             % (self.name, class_of(obj), validator.info(), repr_type(element))
         raise TraitError(e)
 
     def validate(self, obj, value):
         value = super(Container, self).validate(obj, value)
         if value is None:
             return value
 
         value = self.validate_elements(obj, value)
 
         return value
 
     def validate_elements(self, obj, value):
         validated = []
         if self._trait is None or isinstance(self._trait, Any):
             return value
         for v in value:
             try:
                 v = self._trait.validate(obj, v)
             except TraitError:
                 self.element_error(obj, v, self._trait)
             else:
                 validated.append(v)
         return self.klass(validated)
 
 
 class List(Container):
     """An instance of a Python list."""
     klass = list
 
     def __init__(self, trait=None, default_value=None, minlen=0, maxlen=sys.maxsize,
                 allow_none=True, **metadata):
         """Create a List trait type from a list, set, or tuple.
 
         The default value is created by doing ``List(default_value)``,
         which creates a copy of the ``default_value``.
 
         ``trait`` can be specified, which restricts the type of elements
         in the container to that TraitType.
 
         If only one arg is given and it is not a Trait, it is taken as
         ``default_value``:
 
         ``c = List([1,2,3])``
 
         Parameters
         ----------
 
         trait : TraitType [ optional ]
             the type for restricting the contents of the Container.  If unspecified,
             types are not checked.
 
         default_value : SequenceType [ optional ]
             The default value for the Trait.  Must be list/tuple/set, and
             will be cast to the container type.
 
         minlen : Int [ default 0 ]
             The minimum length of the input list
 
         maxlen : Int [ default sys.maxsize ]
             The maximum length of the input list
 
         allow_none : Bool [ default True ]
             Whether to allow the value to be None
 
         **metadata : any
             further keys for extensions to the Trait (e.g. config)
 
         """
         self._minlen = minlen
         self._maxlen = maxlen
         super(List, self).__init__(trait=trait, default_value=default_value,
                                 allow_none=allow_none, **metadata)
 
     def length_error(self, obj, value):
         e = "The '%s' trait of %s instance must be of length %i <= L <= %i, but a value of %s was specified." \
             % (self.name, class_of(obj), self._minlen, self._maxlen, value)
         raise TraitError(e)
 
     def validate_elements(self, obj, value):
         length = len(value)
         if length < self._minlen or length > self._maxlen:
             self.length_error(obj, value)
 
         return super(List, self).validate_elements(obj, value)
 
 
 class Set(Container):
     """An instance of a Python set."""
     klass = set
 
 class Tuple(Container):
     """An instance of a Python tuple."""
     klass = tuple
 
     def __init__(self, *traits, **metadata):
         """Tuple(*traits, default_value=None, allow_none=True, **medatata)
 
         Create a tuple from a list, set, or tuple.
 
         Create a fixed-type tuple with Traits:
 
         ``t = Tuple(Int, Str, CStr)``
 
         would be length 3, with Int,Str,CStr for each element.
 
         If only one arg is given and it is not a Trait, it is taken as
         default_value:
 
         ``t = Tuple((1,2,3))``
 
         Otherwise, ``default_value`` *must* be specified by keyword.
 
         Parameters
         ----------
 
         *traits : TraitTypes [ optional ]
             the tsype for restricting the contents of the Tuple.  If unspecified,
             types are not checked. If specified, then each positional argument
             corresponds to an element of the tuple.  Tuples defined with traits
             are of fixed length.
 
         default_value : SequenceType [ optional ]
             The default value for the Tuple.  Must be list/tuple/set, and
             will be cast to a tuple. If `traits` are specified, the
             `default_value` must conform to the shape and type they specify.
 
         allow_none : Bool [ default True ]
             Whether to allow the value to be None
 
         **metadata : any
             further keys for extensions to the Trait (e.g. config)
 
         """
         default_value = metadata.pop('default_value', None)
         allow_none = metadata.pop('allow_none', True)
 
         # allow Tuple((values,)):
         if len(traits) == 1 and default_value is None and not is_trait(traits[0]):
             default_value = traits[0]
             traits = ()
 
         if default_value is None:
             args = ()
         elif isinstance(default_value, self._valid_defaults):
             args = (default_value,)
         else:
             raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value))
 
         self._traits = []
         for trait in traits:
             t = trait() if isinstance(trait, type) else trait
             t.name = 'element'
             self._traits.append(t)
 
         if self._traits and default_value is None:
             # don't allow default to be an empty container if length is specified
             args = None
         super(Container,self).__init__(klass=self.klass, args=args,
                                   allow_none=allow_none, **metadata)
 
     def validate_elements(self, obj, value):
         if not self._traits:
             # nothing to validate
             return value
         if len(value) != len(self._traits):
             e = "The '%s' trait of %s instance requires %i elements, but a value of %s was specified." \
                 % (self.name, class_of(obj), len(self._traits), repr_type(value))
             raise TraitError(e)
 
         validated = []
         for t,v in zip(self._traits, value):
             try:
                 v = t.validate(obj, v)
             except TraitError:
                 self.element_error(obj, v, t)
             else:
                 validated.append(v)
         return tuple(validated)
 
 
 class Dict(Instance):
     """An instance of a Python dict."""
 
     def __init__(self, default_value=None, allow_none=True, **metadata):
         """Create a dict trait type from a dict.
 
         The default value is created by doing ``dict(default_value)``,
         which creates a copy of the ``default_value``.
         """
         if default_value is None:
             args = ((),)
         elif isinstance(default_value, dict):
             args = (default_value,)
         elif isinstance(default_value, SequenceTypes):
             args = (default_value,)
         else:
             raise TypeError('default value of Dict was %s' % default_value)
 
         super(Dict,self).__init__(klass=dict, args=args,
                                   allow_none=allow_none, **metadata)
 
 class TCPAddress(TraitType):
     """A trait for an (ip, port) tuple.
 
     This allows for both IPv4 IP addresses as well as hostnames.
     """
 
     default_value = ('127.0.0.1', 0)
     info_text = 'an (ip, port) tuple'
 
     def validate(self, obj, value):
         if isinstance(value, tuple):
             if len(value) == 2:
                 if isinstance(value[0], basestring) and isinstance(value[1], int):
                     port = value[1]
                     if port >= 0 and port <= 65535:
                         return value
         self.error(obj, value)
 
 class CRegExp(TraitType):
     """A casting compiled regular expression trait.
 
     Accepts both strings and compiled regular expressions. The resulting
     attribute will be a compiled regular expression."""
 
     info_text = 'a regular expression'
 
     def validate(self, obj, value):
         try:
             return re.compile(value)
         except:
             self.error(obj, value)

docs/sphinxext/apigen.py

@@ -1,417 +1,412 b''
 """Attempt to generate templates for module reference with Sphinx
 
 XXX - we exclude extension modules
 
 To include extension modules, first identify them as valid in the
 ``_uri2path`` method, then handle them in the ``_parse_module`` script.
 
 We get functions and classes by parsing the text of .py files.
 Alternatively we could import the modules for discovery, and we'd have
 to do that for extension modules.  This would involve changing the
 ``_parse_module`` method to work via import and introspection, and
 might involve changing ``discover_modules`` (which determines which
 files are modules, and therefore which module URIs will be passed to
 ``_parse_module``).
 
 NOTE: this is a modified version of a script originally shipped with the
 PyMVPA project, which we've adapted for NIPY use.  PyMVPA is an MIT-licensed
 project."""
 
 # Stdlib imports
 import ast
 import os
 import re
 
 class Obj(object):
     '''Namespace to hold arbitrary information.'''
     def __init__(self, **kwargs):
         for k, v in kwargs.items():
             setattr(self, k, v)
 
 # Functions and classes
 class ApiDocWriter(object):
     ''' Class for automatic detection and parsing of API docs
     to Sphinx-parsable reST format'''
 
     # only separating first two levels
     rst_section_levels = ['*', '=', '-', '~', '^']
 
     def __init__(self,
                  package_name,
                  rst_extension='.rst',
                  package_skip_patterns=None,
                  module_skip_patterns=None,
                  ):
         ''' Initialize package for parsing
 
         Parameters
         ----------
         package_name : string
             Name of the top-level package.  *package_name* must be the
             name of an importable package
         rst_extension : string, optional
             Extension for reST files, default '.rst'
         package_skip_patterns : None or sequence of {strings, regexps}
             Sequence of strings giving URIs of packages to be excluded
             Operates on the package path, starting at (including) the
             first dot in the package path, after *package_name* - so,
             if *package_name* is ``sphinx``, then ``sphinx.util`` will
             result in ``.util`` being passed for earching by these
             regexps.  If is None, gives default. Default is:
             ['\.tests$']
         module_skip_patterns : None or sequence
             Sequence of strings giving URIs of modules to be excluded
             Operates on the module name including preceding URI path,
             back to the first dot after *package_name*.  For example
             ``sphinx.util.console`` results in the string to search of
             ``.util.console``
             If is None, gives default. Default is:
             ['\.setup$', '\._']
         '''
         if package_skip_patterns is None:
             package_skip_patterns = ['\\.tests$']
         if module_skip_patterns is None:
             module_skip_patterns = ['\\.setup$', '\\._']
         self.package_name = package_name
         self.rst_extension = rst_extension
         self.package_skip_patterns = package_skip_patterns
         self.module_skip_patterns = module_skip_patterns
 
     def get_package_name(self):
         return self._package_name
 
     def set_package_name(self, package_name):
         ''' Set package_name
 
         >>> docwriter = ApiDocWriter('sphinx')
         >>> import sphinx
         >>> docwriter.root_path == sphinx.__path__[0]
         True
         >>> docwriter.package_name = 'docutils'
         >>> import docutils
         >>> docwriter.root_path == docutils.__path__[0]
         True
         '''
         # It's also possible to imagine caching the module parsing here
         self._package_name = package_name
         self.root_module = __import__(package_name)
         self.root_path = self.root_module.__path__[0]
         self.written_modules = None
 
     package_name = property(get_package_name, set_package_name, None,
                             'get/set package_name')
 
     def _uri2path(self, uri):
         ''' Convert uri to absolute filepath
 
         Parameters
         ----------
         uri : string
             URI of python module to return path for
 
         Returns
         -------
         path : None or string
             Returns None if there is no valid path for this URI
             Otherwise returns absolute file system path for URI
 
         Examples
         --------
         >>> docwriter = ApiDocWriter('sphinx')
         >>> import sphinx
         >>> modpath = sphinx.__path__[0]
         >>> res = docwriter._uri2path('sphinx.builder')
         >>> res == os.path.join(modpath, 'builder.py')
         True
         >>> res = docwriter._uri2path('sphinx')
         >>> res == os.path.join(modpath, '__init__.py')
         True
         >>> docwriter._uri2path('sphinx.does_not_exist')
 
         '''
         if uri == self.package_name:
             return os.path.join(self.root_path, '__init__.py')
         path = uri.replace('.', os.path.sep)
         path = path.replace(self.package_name + os.path.sep, '')
         path = os.path.join(self.root_path, path)
         # XXX maybe check for extensions as well?
         if os.path.exists(path + '.py'): # file
             path += '.py'
         elif os.path.exists(os.path.join(path, '__init__.py')):
             path = os.path.join(path, '__init__.py')
         else:
             return None
         return path
 
     def _path2uri(self, dirpath):
         ''' Convert directory path to uri '''
         relpath = dirpath.replace(self.root_path, self.package_name)
         if relpath.startswith(os.path.sep):
             relpath = relpath[1:]
         return relpath.replace(os.path.sep, '.')
 
     def _parse_module(self, uri):
         ''' Parse module defined in *uri* '''
         filename = self._uri2path(uri)
         if filename is None:
             # nothing that we could handle here.
             return ([],[])
         with open(filename, 'rb') as f:
             mod = ast.parse(f.read())
         return self._find_functions_classes(mod)
 
     @staticmethod
     def _find_functions_classes(mod):
         """Extract top-level functions and classes from a module AST.
         
         Skips objects with an @undoc decorator, or a name starting with '_'.
         """
         def has_undoc_decorator(node):
             return any(isinstance(d, ast.Name) and d.id == 'undoc' \
                                         for d in node.decorator_list)
         
         functions, classes = [], []
         for node in mod.body:
             if isinstance(node, ast.FunctionDef) and \
                         not node.name.startswith('_') and \
                         not has_undoc_decorator(node):
                 functions.append(node.name)
             elif isinstance(node, ast.ClassDef) and \
                         not node.name.startswith('_') and \
                         not has_undoc_decorator(node):
                 cls = Obj(name=node.name)
                 cls.has_init = any(isinstance(n, ast.FunctionDef) and \
                                     n.name=='__init__' for n in node.body)
                 classes.append(cls)
         
         return functions, classes
 
     def generate_api_doc(self, uri):
         '''Make autodoc documentation template string for a module
 
         Parameters
         ----------
         uri : string
             python location of module - e.g 'sphinx.builder'
 
         Returns
         -------
         S : string
             Contents of API doc
         '''
         # get the names of all classes and functions
         functions, classes = self._parse_module(uri)
         if not len(functions) and not len(classes):
             print 'WARNING: Empty -',uri  # dbg
             return ''
 
         # Make a shorter version of the uri that omits the package name for
         # titles
         uri_short = re.sub(r'^%s\.' % self.package_name,'',uri)
 
         ad = '.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n'
 
         # Set the chapter title to read 'Module:' for all modules except for the
         # main packages
         if '.' in uri:
             chap_title = 'Module: :mod:`' + uri_short + '`'
         else:
             chap_title = ':mod:`' + uri_short + '`'
         ad += chap_title + '\n' + self.rst_section_levels[1] * len(chap_title)
 
-        if len(classes):
-            ad += '\nInheritance diagram for ``%s``:\n\n' % uri
-            ad += '.. inheritance-diagram:: %s \n' % uri
-            ad += '   :parts: 3\n'
-
         ad += '\n.. automodule:: ' + uri + '\n'
         ad += '\n.. currentmodule:: ' + uri + '\n'
         multi_class = len(classes) > 1
         multi_fx = len(functions) > 1
         if multi_class:
             ad += '\n' + 'Classes' + '\n' + \
                   self.rst_section_levels[2] * 7 + '\n'
         elif len(classes) and multi_fx:
             ad += '\n' + 'Class' + '\n' + \
                   self.rst_section_levels[2] * 5 + '\n'
         for c in classes:
             ad += '\n:class:`' + c.name + '`\n' \
                   + self.rst_section_levels[multi_class + 2 ] * \
                   (len(c.name)+9) + '\n\n'
             ad += '\n.. autoclass:: ' + c.name + '\n'
             # must NOT exclude from index to keep cross-refs working
             ad += '  :members:\n' \
                   '  :show-inheritance:\n'
             if c.has_init:
                   ad += '\n  .. automethod:: __init__\n'
         if multi_fx:
             ad += '\n' + 'Functions' + '\n' + \
                   self.rst_section_levels[2] * 9 + '\n\n'
         elif len(functions) and multi_class:
             ad += '\n' + 'Function' + '\n' + \
                   self.rst_section_levels[2] * 8 + '\n\n'
         for f in functions:
             # must NOT exclude from index to keep cross-refs working
             ad += '\n.. autofunction:: ' + uri + '.' + f + '\n\n'
         return ad
 
     def _survives_exclude(self, matchstr, match_type):
         ''' Returns True if *matchstr* does not match patterns
 
         ``self.package_name`` removed from front of string if present
 
         Examples
         --------
         >>> dw = ApiDocWriter('sphinx')
         >>> dw._survives_exclude('sphinx.okpkg', 'package')
         True
         >>> dw.package_skip_patterns.append('^\\.badpkg$')
         >>> dw._survives_exclude('sphinx.badpkg', 'package')
         False
         >>> dw._survives_exclude('sphinx.badpkg', 'module')
         True
         >>> dw._survives_exclude('sphinx.badmod', 'module')
         True
         >>> dw.module_skip_patterns.append('^\\.badmod$')
         >>> dw._survives_exclude('sphinx.badmod', 'module')
         False
         '''
         if match_type == 'module':
             patterns = self.module_skip_patterns
         elif match_type == 'package':
             patterns = self.package_skip_patterns
         else:
             raise ValueError('Cannot interpret match type "%s"'
                              % match_type)
         # Match to URI without package name
         L = len(self.package_name)
         if matchstr[:L] == self.package_name:
             matchstr = matchstr[L:]
         for pat in patterns:
             try:
                 pat.search
             except AttributeError:
                 pat = re.compile(pat)
             if pat.search(matchstr):
                 return False
         return True
 
     def discover_modules(self):
         ''' Return module sequence discovered from ``self.package_name``
 
 
         Parameters
         ----------
         None
 
         Returns
         -------
         mods : sequence
             Sequence of module names within ``self.package_name``
 
         Examples
         --------
         >>> dw = ApiDocWriter('sphinx')
         >>> mods = dw.discover_modules()
         >>> 'sphinx.util' in mods
         True
         >>> dw.package_skip_patterns.append('\.util$')
         >>> 'sphinx.util' in dw.discover_modules()
         False
         >>>
         '''
         modules = [self.package_name]
         # raw directory parsing
         for dirpath, dirnames, filenames in os.walk(self.root_path):
             # Check directory names for packages
             root_uri = self._path2uri(os.path.join(self.root_path,
                                                    dirpath))
             for dirname in dirnames[:]: # copy list - we modify inplace
                 package_uri = '.'.join((root_uri, dirname))
                 if (self._uri2path(package_uri) and
                     self._survives_exclude(package_uri, 'package')):
                     modules.append(package_uri)
                 else:
                     dirnames.remove(dirname)
             # Check filenames for modules
             for filename in filenames:
                 module_name = filename[:-3]
                 module_uri = '.'.join((root_uri, module_name))
                 if (self._uri2path(module_uri) and
                     self._survives_exclude(module_uri, 'module')):
                     modules.append(module_uri)
         return sorted(modules)
 
     def write_modules_api(self, modules,outdir):
         # write the list
         written_modules = []
         for m in modules:
             api_str = self.generate_api_doc(m)
             if not api_str:
                 continue
             # write out to file
             outfile = os.path.join(outdir,
                                    m + self.rst_extension)
             fileobj = open(outfile, 'wt')
             fileobj.write(api_str)
             fileobj.close()
             written_modules.append(m)
         self.written_modules = written_modules
 
     def write_api_docs(self, outdir):
         """Generate API reST files.
 
         Parameters
         ----------
         outdir : string
             Directory name in which to store files
             We create automatic filenames for each module
 
         Returns
         -------
         None
 
         Notes
         -----
         Sets self.written_modules to list of written modules
         """
         if not os.path.exists(outdir):
             os.mkdir(outdir)
         # compose list of modules
         modules = self.discover_modules()
         self.write_modules_api(modules,outdir)
 
     def write_index(self, outdir, froot='gen', relative_to=None):
         """Make a reST API index file from written files
 
         Parameters
         ----------
         path : string
             Filename to write index to
         outdir : string
             Directory to which to write generated index file
         froot : string, optional
             root (filename without extension) of filename to write to
             Defaults to 'gen'.  We add ``self.rst_extension``.
         relative_to : string
             path to which written filenames are relative.  This
             component of the written file path will be removed from
             outdir, in the generated index.  Default is None, meaning,
             leave path as it is.
         """
         if self.written_modules is None:
             raise ValueError('No modules written')
         # Get full filename path
         path = os.path.join(outdir, froot+self.rst_extension)
         # Path written into index is relative to rootpath
         if relative_to is not None:
             relpath = outdir.replace(relative_to + os.path.sep, '')
         else:
             relpath = outdir
         idx = open(path,'wt')
         w = idx.write
         w('.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n')
         w('.. toctree::\n\n')
         for f in self.written_modules:
             w('   %s\n' % os.path.join(relpath,f))
         idx.close()